VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Importação avançada

Exportação avançada

Exporta produtos escolhendo as colunas, os filtros e o formato do CSV, e lista os campos disponíveis para importar e exportar.

A exportação simples (Exportar catálogo) devolve sempre as mesmas colunas. A exportação avançada deixa você escolher quais campos sai (custo, SEO, peso, imagens...), como o arquivo é formatado (separador, vírgula ou ponto decimal, formato de data) e filtrar por seller, categoria, status e período. A lista de campos que você pode escolher vem de uma rota própria, e é a mesma lista que o assistente de importação usa para o mapeamento.

As duas rotas desta página exigem o privilégio manage_settings.

GET/api/v1/admin/advanced-export/fields/{entity}Admin

Lista os campos importáveis e exportáveis

Devolve os campos de um tipo de registro, agrupados. Use para montar a lista fields da exportação e o field_mapping da importação.

Parâmetros de caminho

entitystringobrigatório
productscategoriesusersordersvendorsfeaturesbrandsqty_discounts
Tipo de registro. Um valor que não está na lista não dá erro: a resposta repete o texto em entity, mas traz os campos de produto.
POST/api/v1/admin/advanced-export/executeAdmin

Exporta produtos com campos e formato escolhidos

Gera e devolve o CSV na hora (anexo produtos_export.csv). Exporta sempre produtos, qualquer que seja o tipo pedido.

Corpo da requisição (JSON)

fieldsarray
Chaves dos campos a exportar, na ordem das colunas (["sku","name","price"]). Vazio exporta todos os campos, menos os de data de criação e alteração. Chaves desconhecidas são ignoradas; se nenhuma for válida, o pedido falha.
filtersobject

Filtros.

statusstring
AHD
Status do produto. Letra ou palavra.
vendor_iduuid
Só os produtos deste seller.
category_iduuid
Só os produtos desta categoria principal.
date_fromstring
Criados a partir desta data, YYYY-MM-DD (à meia-noite).
date_tostring
Criados até esta data, YYYY-MM-DD. Vale a meia-noite do início do dia: produtos criados durante esse dia não entram. Para incluir o dia inteiro, use o dia seguinte.
product_idsarray
Lista de ids de produto. Quando preenchida, só esses saem (além dos filtros).
formatobject

Formato do CSV.

delimiterstring
Separador de colunas, ; ou ,. Sem o objeto format (ou com delimiter vazio), vale o padrão brasileiro inteiro: ;, vírgula decimal, data dd/mm/yyyy e BOM.
decimal_sepstring
Separador decimal. Sem o objeto format, vale ,. Com o objeto e sem este campo, vale ..
date_formatstring
dd/mm/yyyyyyyy-mm-dd
Formato de data. Sem o objeto format, vale dd/mm/yyyy. Com o objeto e sem este campo, vale yyyy-mm-dd.
include_bomboolean
Escreve o BOM do UTF-8 no começo, para o Excel abrir os acentos certos. Sem o objeto format, vale true. Com o objeto, vale false se você não mandar.
currency_prefixstring
Texto colocado antes dos preços (R$ ). Vazio por padrão.

Exemplo de requisição

Resposta

200CSV (padrão brasileiro)
200Campos de produto (reduzido)

Campos da resposta (lista de campos)

entitystring
O tipo pedido, como foi enviado.
groupsarray
Os campos agrupados para exibir em tela. Em produtos: basic, pricing, inventory, shipping, content, seo, relationships, images, features, variations, timestamps.
fieldsarray
Os mesmos campos em lista plana.
entity_typesarray
Todos os tipos aceitos em {entity}.

Campos de cada item de fields

keystring
Chave do campo. É o que vai em fields na exportação e no lado direito do field_mapping na importação.
labelstring
Nome em inglês.
label_ptstring
Nome em português.
groupstring
Grupo.
requiredboolean
Obrigatório na importação (por exemplo price e vendor_id). Não afeta a exportação.
db_columnstring
Coluna de origem. Vazio quando o campo é calculado.
field_typestring
stringintfloatmoneybooldate
Tipo do valor.
default_valuestring
Valor padrão sugerido, quando existe.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
401Token ausente ou expirado{"error":"invalid or expired token"}
403Falta manage_settings{"error":"insufficient privileges","required":"manage_settings"}
200 (com erro no corpo)Nenhum campo válido em fields{"error":"export products failed","detail":"no valid fields selected for export"}
Erro dentro de um 200

A resposta é um fluxo: o status 200 e o início do CSV (o BOM, o cabeçalho) já foram enviados quando um erro aparece. Por isso uma falha não muda o status e o corpo pode vir como um CSV cortado, ou como um JSON de erro colado ao fim dele. Confira se o corpo começa com {"error" ou termina com um JSON, e confira a contagem de linhas. Um exemplo real: pedir a coluna vendor_id quando existe produto sem seller devolve metade do arquivo e depois um JSON scan row: ... vendor_id.

Células que parecem fórmula

Para proteger quem abre o arquivo no Excel, uma célula de texto que começa com =, +, - ou @ recebe um apóstrofo na frente. Se você processa o CSV por programa, remova o apóstrofo inicial ao ler.

Veja também

  • Exportar catálogo
  • Assistente de importação
  • Predefinições de exportação
Anterior
Predefinições de importação
Próxima
Predefinições de exportação
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
# campos disponíveis para produtos
curl "$BASE_URL/api/v1/admin/advanced-export/fields/products" \
  -H "Authorization: Bearer $TOKEN"

# exportar SKU, nome, preço e estoque de um seller, em CSV internacional
curl -X POST "$BASE_URL/api/v1/admin/advanced-export/execute" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "fields": ["sku", "name", "price", "quantity"],
    "filters": {"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"},
    "format": {"delimiter": ",", "decimal_sep": ".", "date_format": "yyyy-mm-dd", "include_bom": false}
  }' -o produtos.csv
text
sku;name;price;quantity
SD-001392;Garrafa Vintage Rosa 01392;89,90;1
SD-002076;Teclado Max Verde 02076;999,90;2
json
{
  "entity": "products",
  "groups": [
    {
      "key": "basic",
      "label": "Basic Information",
      "label_pt": "Informacoes Basicas",
      "fields": [
        { "key": "sku", "label": "SKU / Product Code", "label_pt": "Codigo do Produto", "group": "basic", "required": false, "db_column": "sku", "field_type": "string" },
        { "key": "vendor_id", "label": "Vendor ID", "label_pt": "ID do Fornecedor", "group": "basic", "required": true, "db_column": "vendor_id", "field_type": "string" }
      ]
    }
  ],
  "fields": [
    { "key": "price", "label": "Price", "label_pt": "Preco", "group": "pricing", "required": true, "db_column": "price", "field_type": "money" }
  ],
  "entity_types": ["products", "categories", "users", "orders", "vendors", "features", "brands", "qty_discounts"]
}