VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Lote, importação e exportação

Exportar

Baixa produtos em arquivo CSV, XLSX ou XML, com filtros, escolha de colunas e formato próprio de números e datas.

Três rotas baixam o catálogo. Escolha pelo que você precisa:

RotaMelhor paraSaída
GET /products/exportUm arquivo de ida e volta: as mesmas colunas que o importador lê, com filtros simplesCSV, XLSX ou XLS
POST /products/exportSó algumas colunas, separador ou sinal decimal à escolha, lista de idsCSV
POST /products/export-xmlAlimentar outro sistema que quer XMLXML

As três exigem o privilégio manage_catalog, devolvem um arquivo (não JSON) e só incluem produtos não excluídos. O dinheiro nesses arquivos é número decimal em reais (52.90), não centavos.

Baixar em CSV, XLSX ou XLS

GET/api/v1/admin/products/exportAdmin

Exportar produtos para CSV, XLSX ou XLS

O padrão é um CSV com ; como separador, UTF-8 com BOM, uma linha de cabeçalho e uma linha por produto. Estas 25 colunas, nesta ordem, são exatamente o que Importar um arquivo lê de volta:

sku, name, slug, price, list_price, cost_price, quantity, min_quantity, max_quantity, quantity_step, status, category_id, vendor_id, description, short_description, promo_text, weight, length, width, height, free_shipping (Y ou N), shipping_freight, meta_title, meta_description, meta_keywords.

Os preços usam ponto (52.90). Preço de lista, custo e frete vazios ficam em branco.

Parâmetros de consulta

statusstring
ADH
Só produtos com este status. Use a letra: esta rota não traduz palavras, e um valor desconhecido não devolve linhas.
vendor_iduuid
Só produtos deste seller.
category_iduuid
Só produtos cuja categoria principal é esta (subcategorias não entram).
date_fromstring
Criados nesta data ou depois (AAAA-MM-DD).
date_tostring
Criados até esta data. Uma data sem hora vale meia-noite, então produtos criados mais tarde nesse mesmo dia não entram; use o dia seguinte. date_from depois de date_to devolve 400.
idsstring
UUIDs de produto separados por vírgula.
formatstringpadrão: csv
csvxlsxxls
Formato do arquivo. xlsx é uma pasta de trabalho Excel de verdade; xls é o formato XML antigo do Excel 2003.
countstring
1trueyes
Devolve {"count": N} em JSON em vez do arquivo, com os mesmos filtros. Use para saber o tamanho antes.
bash
curl "$BASE_URL/api/v1/admin/products/export?status=A&format=xlsx" \
  -H "Authorization: Bearer $TOKEN" -o produtos.xlsx
200CSV (início do arquivo)
text
sku;name;slug;price;list_price;cost_price;quantity;min_quantity;max_quantity;quantity_step;status;category_id;vendor_id;description;short_description;promo_text;weight;length;width;height;free_shipping;shipping_freight;meta_title;meta_description;meta_keywords
CAM-001;Camiseta Azul;camiseta-azul;52.90;;;12;0;0;1;A;345ac33e-4dcd-4d60-bedf-a2c2d47897d9;9d9d9d56-eb43-4719-889d-055632f7c7da;;;;;;;;N;;;;
200count=1
json
{ "count": 2 }

Os cabeçalhos da resposta trazem Content-Disposition: attachment; filename="produtos.csv" (.xlsx ou .xls nesses formatos) e, em xlsx e xls, X-Export-Returned com o número de linhas.

Exportar colunas escolhidas

POST/api/v1/admin/products/exportAdmin

Exportar colunas selecionadas para CSV

Devolve produtos_export.csv. Sem format, vale o estilo brasileiro: separador ;, vírgula decimal (52,90), datas dd/mm/yyyy, UTF-8 com BOM. A linha de cabeçalho usa as chaves de campo que você pediu.

Corpo da requisição

fieldsarray
Chaves dos campos a incluir, em ordem. Vazio significa todos os campos. Chaves que não existem são ignoradas; se nenhuma for válida a chamada falha. As principais são sku, name, slug, status, vendor_id, brand, category_id, category_name, category_path, price, list_price, cost_price, quantity, min_quantity, max_quantity, weight, length, width, height, free_shipping, shipping_freight, description, short_description, meta_title, meta_description, ncm_code, main_image, additional_images, created_at, updated_at. A lista completa com rótulos é GET /api/v1/admin/import-export/fields/products.
filtersobject

Restringe os produtos.

statusstring
A, D, H ou active, disabled, hidden.
vendor_iduuid
Seller.
category_iduuid
Categoria principal.
date_fromstring
Criados a partir de (AAAA-MM-DD).
date_tostring
Criados até (AAAA-MM-DD, meia-noite).
product_idsarray
Exporta só estes UUIDs de produto (combinados com os filtros).
formatobject

Estilo de números e datas. Se delimiter vier vazio, o objeto inteiro é substituído pelo padrão brasileiro.

delimiterstringpadrão: ;
Separador de colunas, ; ou ,.
decimal_sepstringpadrão: ,
Sinal decimal para dinheiro e decimais, , ou ..
date_formatstringpadrão: dd/mm/yyyy
dd/mm/yyyyyyyy-mm-dd
Estilo da data.
include_bombooleanpadrão: true
Escreve o BOM UTF-8 de que o Excel precisa.
currency_prefixstring
Texto colocado antes dos preços, por exemplo R$ .
bash
curl -X POST "$BASE_URL/api/v1/admin/products/export" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"fields":["sku","name","price","quantity"],"filters":{"status":"active"},
       "format":{"delimiter":",","decimal_sep":".","date_format":"yyyy-mm-dd","include_bom":false}}' \
  -o produtos_export.csv
200CSV, padrão brasileiro
text
sku;name;price;quantity
CAM-001;Camiseta Azul;52,90;12
CAN-002;Caneca Branca;49,90;20

Exportar em XML

POST/api/v1/admin/products/export-xmlAdmin

Exportar produtos em XML

Devolve produtos_export.xml, um elemento por produto e um filho por campo. Os preços têm ponto decimal (89.90), a menos que format.decimal_sep diga outra coisa.

Corpo da requisição

fieldsarray
Chaves dos campos, como no export CSV. Vazio significa todos os campos, exceto as datas de controle.
filtersobject

As mesmas chaves do export CSV: status, vendor_id, category_id, date_from, date_to. São a única forma de restringir um export XML.

formatobject
Estilo de números, as mesmas chaves do export CSV (decimal_sep, currency_prefix, date_format).
xml_configobject

Formato do documento.

root_elementstringpadrão: products
Nome do elemento externo.
item_elementstringpadrão: product
Nome do elemento de cada produto.
indentbooleanpadrão: false
Formata com indentação.
bash
curl -X POST "$BASE_URL/api/v1/admin/products/export-xml" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"fields":["sku","name","price"],"filters":{"vendor_id":"9d9d9d56-eb43-4719-889d-055632f7c7da"},
       "xml_config":{"root_element":"produtos","item_element":"produto","indent":true}}' \
  -o produtos_export.xml
200XML
xml
<?xml version="1.0" encoding="UTF-8"?>
<produtos>
  <produto>
    <sku>CAM-001</sku>
    <name>Camiseta Azul</name>
    <price>52.90</price>
  </produto>
</produtos>

Erros

StatusQuandoExemplo de corpo
400date_from depois de date_to (GET){"error":"invalid_date_range","detail":"date_from must be on or before date_to"}
400Corpo não é JSON válido (rotas POST){"error":"invalid request body","detail":"..."}
401 / 403Sem token / sem manage_catalog{"error":"missing authorization header"} / {"error":"insufficient privileges","required":"manage_catalog"}
500Falha ao montar uma planilha xlsx ou xls{"error":"export products failed","detail":"..."}
Uma exportação que falhou pode responder 200

O CSV e o XML são enviados em fluxo: depois dos primeiros bytes o status já é 200. Se a exportação falha em seguida (por exemplo ids=notuuid, ou fields sem nenhuma chave válida na rota POST), o corpo é um erro em JSON como {"error":"export products failed","detail":"..."} no lugar das linhas do CSV, ainda com status 200. Confira sempre que o conteúdo começa com o seu cabeçalho (ou examine o primeiro caractere) antes de confiar no arquivo. Use count=1 antes para validar os filtros da rota GET.

O export-xml ignora product_ids e filters.ids

A rota XML aceita product_ids no corpo mas não o usa, e filters.ids também não é usado: um export XML só com ids devolve todos os produtos. Restrinja com status, vendor_id, category_id, date_from e date_to, ou use as rotas CSV para uma lista de ids.

Veja também

  • Importar um arquivo
  • Assistente de importação
  • Listar produtos
Anterior
Assistente de importação
Próxima
Operações de manutenção
Nesta página
  • Baixar em CSV, XLSX ou XLS
  • Exportar colunas escolhidas
  • Exportar em XML
  • Erros
  • Veja também