API atual/Referência completa/Importação e exportação

Exportar catálogo

Baixa produtos, categorias, características, marcas e preços por quantidade em CSV, XLSX ou XLS, com filtros e contagem prévia.

Use estas rotas para tirar o catálogo da loja em planilha: para conferir preços e estoque no Excel, para alimentar um ERP ou para fazer uma correção em massa e reenviar com a importação. Cada rota devolve um arquivo (não JSON), exceto quando você manda count=1.

Todas aceitam os mesmos parâmetros de formato: format (csv, xlsx ou xls) e count. O CSV sai em UTF-8 com BOM. Em xlsx e xls a resposta traz o cabeçalho X-Export-Returned com o número de linhas exportadas.

GET/api/v1/admin/export/productsAdmin

Exporta produtos

Privilégio manage_catalog. Exporta os produtos não excluídos. Colunas: product_code, name, price, list_price, status, quantity, weight, category_id, vendor_id, description, short_description. Preços saem em reais com vírgula decimal (49,90).

Parâmetros de consulta

statusstring

AHD

Filtra pelo status. Aceita a letra ou uma palavra (ativo, oculto, inativo, active, hidden, disabled). Palavra desconhecida volta 400.

vendor_iduuid

Só os produtos deste seller (lojista).

category_iduuid

Só os produtos desta categoria.

date_fromstring

Data inicial, YYYY-MM-DD.

date_tostring

Data final, YYYY-MM-DD. Não pode ser menor que date_from.

idsstring

Lista de ids de produto separados por vírgula. Exporta só esses.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve {"count": N} em vez do arquivo.

GET/api/v1/admin/export/categoriesAdmin

Exporta categorias

Privilégio manage_categories. Colunas: id, name, parent_id, slug, description, status, position, meta_title, meta_keywords. O separador é a vírgula. Categorias na lixeira não saem.

Parâmetros de consulta

statusstring

AHD

Filtra pelo status da categoria.

idsstring

Lista de ids de categoria separados por vírgula.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

GET/api/v1/admin/export/featuresAdmin

Exporta características

Privilégio manage_features. Característica (feature) é um atributo de produto, como Cor ou Voltagem. Colunas: feature_id, name, feature_type, group_name, description, status, position, variants, categories. Os valores possíveis ficam em variants, separados por |. O separador do arquivo é ;.

Parâmetros de consulta

statusstring

AHD

Filtra pelo status.

idsstring

Lista de ids de característica separados por vírgula.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

GET/api/v1/admin/export/brandsAdmin

Exporta marcas

Privilégio manage_features. Marcas são valores de uma característica do tipo marca. Colunas: brand_id, feature_id, name, code, description, position, image_url, slug_url, page_title, meta_description, meta_keywords. Separador ;.

Parâmetros de consulta

idsstring

Lista de ids de marca separados por vírgula.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

GET/api/v1/admin/export/qty-discountsAdmin

Exporta preços por quantidade

Privilégio manage_catalog. Preço por quantidade (faixa de preço) é o desconto que o cliente ganha ao comprar a partir de certo número de unidades. Cada linha é uma faixa. Colunas, com os nomes em inglês do formato padrão de importação: Product code, Price, Value per Kg, Value per Unit, Lower limit, Percentage discount, User group. Separador ;.

Parâmetros de consulta

idsstring

Lista de ids de produto separados por vírgula. Exporta só as faixas desses produtos.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

Exemplo de requisição

bash

# 1) quantas linhas o arquivo teria
curl "$BASE_URL/api/v1/admin/export/products?status=A&vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36&count=1" \
  -H "Authorization: Bearer $TOKEN"

# 2) baixar em XLSX
curl "$BASE_URL/api/v1/admin/export/products?status=A&vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36&format=xlsx" \
  -H "Authorization: Bearer $TOKEN" -o produtos.xlsx

Resposta

200Contagem (count=1)

json

{ "count": 4987 }

200Arquivo CSV (exemplo reduzido)

text

product_code;name;price;list_price;status;quantity;weight;category_id;vendor_id;description;short_description
SKU-001;Camiseta Algodão;49,90;59,90;A;100;0,500;54227821-63c2-45f8-aa1c-4dc40e599f8c;94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36;Camiseta 100% algodão;Camiseta básica

Cabeçalhos da resposta

Content-Typestring

text/csv; charset=utf-8, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx) ou application/vnd.ms-excel (xls).

Content-Dispositionstring

attachment; filename="products.csv" (ou categories, features, brands, qty_discounts; extensão conforme o formato).

X-Export-Returnedinteger

Número de linhas exportadas. Só em xlsx e xls.

Erros

Status	Quando	Corpo de exemplo
400	`status` com palavra desconhecida	`{"error":"unknown_record_status","detail":"situação desconhecida: \"ativos2\". Use ativo (A), oculto (H) ou desativado (D)."}`
400	`date_from` maior que `date_to`	`{"error":"invalid_date_range","detail":"date_from must be on or before date_to"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta o privilégio da tabela da home da seção	`{"error":"insufficient privileges","required":"manage_catalog"}`
500	Falha ao montar o arquivo	`{"error":"export products failed","detail":"..."}`

A mensagem de unknown_record_status é devolvida em português pelo servidor.

Veja também

Exportar catálogo

Baixa produtos, categorias, características, marcas e preços por quantidade em CSV, XLSX ou XLS, com filtros e contagem prévia.

GET/api/v1/admin/export/productsAdmin

Exporta produtos

Parâmetros de consulta

statusstring

AHD

Filtra pelo status. Aceita a letra ou uma palavra (ativo, oculto, inativo, active, hidden, disabled). Palavra desconhecida volta 400.

vendor_iduuid

Só os produtos deste seller (lojista).

category_iduuid

Só os produtos desta categoria.

date_fromstring

Data inicial, YYYY-MM-DD.

date_tostring

Data final, YYYY-MM-DD. Não pode ser menor que date_from.

idsstring

Lista de ids de produto separados por vírgula. Exporta só esses.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve {"count": N} em vez do arquivo.

GET/api/v1/admin/export/categoriesAdmin

Exporta categorias

Parâmetros de consulta

statusstring

AHD

Filtra pelo status da categoria.

idsstring

Lista de ids de categoria separados por vírgula.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

GET/api/v1/admin/export/featuresAdmin

Exporta características

Parâmetros de consulta

statusstring

AHD

Filtra pelo status.

idsstring

Lista de ids de característica separados por vírgula.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

GET/api/v1/admin/export/brandsAdmin

Exporta marcas

Parâmetros de consulta

idsstring

Lista de ids de marca separados por vírgula.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

GET/api/v1/admin/export/qty-discountsAdmin

Exporta preços por quantidade

Parâmetros de consulta

idsstring

Lista de ids de produto separados por vírgula. Exporta só as faixas desses produtos.

formatstringpadrão: csv

csvxlsxxls

Formato do arquivo.

countstring

1trueyesonly

Devolve só a contagem.

Exemplo de requisição

bash

# 1) quantas linhas o arquivo teria
curl "$BASE_URL/api/v1/admin/export/products?status=A&vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36&count=1" \
  -H "Authorization: Bearer $TOKEN"

# 2) baixar em XLSX
curl "$BASE_URL/api/v1/admin/export/products?status=A&vendor_id=94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36&format=xlsx" \
  -H "Authorization: Bearer $TOKEN" -o produtos.xlsx

Resposta

200Contagem (count=1)

json

{ "count": 4987 }

200Arquivo CSV (exemplo reduzido)

text

product_code;name;price;list_price;status;quantity;weight;category_id;vendor_id;description;short_description
SKU-001;Camiseta Algodão;49,90;59,90;A;100;0,500;54227821-63c2-45f8-aa1c-4dc40e599f8c;94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36;Camiseta 100% algodão;Camiseta básica

Cabeçalhos da resposta

Content-Typestring

text/csv; charset=utf-8, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx) ou application/vnd.ms-excel (xls).

Content-Dispositionstring

attachment; filename="products.csv" (ou categories, features, brands, qty_discounts; extensão conforme o formato).

X-Export-Returnedinteger

Número de linhas exportadas. Só em xlsx e xls.

Erros

Status	Quando	Corpo de exemplo
400	`status` com palavra desconhecida	`{"error":"unknown_record_status","detail":"situação desconhecida: \"ativos2\". Use ativo (A), oculto (H) ou desativado (D)."}`
400	`date_from` maior que `date_to`	`{"error":"invalid_date_range","detail":"date_from must be on or before date_to"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta o privilégio da tabela da home da seção	`{"error":"insufficient privileges","required":"manage_catalog"}`
500	Falha ao montar o arquivo	`{"error":"export products failed","detail":"..."}`

A mensagem de unknown_record_status é devolvida em português pelo servidor.