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

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

Resposta

200CSV (padrão brasileiro)

text

sku;name;price;quantity
SD-001392;Garrafa Vintage Rosa 01392;89,90;1
SD-002076;Teclado Max Verde 02076;999,90;2

200Campos de produto (reduzido)

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"]
}

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

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `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"}`

Veja também

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.

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

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

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

Resposta

200CSV (padrão brasileiro)

text

sku;name;price;quantity
SD-001392;Garrafa Vintage Rosa 01392;89,90;1
SD-002076;Teclado Max Verde 02076;999,90;2

200Campos de produto (reduzido)

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"]
}

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

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `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"}`