API atual/Guia rápido/Lote, importação e exportação

Assistente de importação

Pré-visualize uma importação sem gravar, mapeie as colunas do arquivo, rode importações grandes em segundo plano e consulte o progresso.

O assistente é o jeito cuidadoso de importar: você envia o arquivo, o servidor o lê, sugere qual coluna vai para qual campo do produto, diz o que criaria, atualizaria ou recusaria, e só então você executa. É o que a tela de importação do painel usa, e é a escolha certa para arquivos grandes (acima de 1000 linhas a execução vai para segundo plano), para arquivos com cabeçalhos diferentes dos nossos e sempre que você quiser ver o resultado antes de gravar.

Pré-visualize ou valide
POST /products/import/preview (simulação pura) ou POST /products/import/validate. Os dois recebem o seu arquivo e devolvem um job_id, o auto_mapping sugerido (validate) e os problemas achados linha a linha. Nenhum produto é gravado.
Ajuste o mapeamento
Edite o mapeamento se preciso: é um objeto JSON {"<cabeçalho da coluna no seu arquivo>": "<campo do produto>"}.
Execute
POST /products/import/execute com o job_id e os field_mappings (ou com o próprio arquivo).
Consulte o status
GET /products/import/status/{job_id} a cada 2 segundos até o status ser completed ou failed.

As quatro rotas exigem o privilégio manage_catalog e os mesmos formatos de Importar um arquivo: CSV (; ou ,), .txt, .xlsx/.xlsm (primeira planilha). Os preços seguem a mesma regra: com separador decimal são reais, sem ele são centavos.

Estratégias e campos de formulário comuns

strategy é create_update (padrão: cria o novo, atualiza o existente), update_only (linhas cujo SKU não existe são puladas) ou create_only (linhas cujo SKU existe são puladas). upsert é aceito como apelido de create_update no preview e no validate. default_vendor_id é o seller usado nas linhas sem coluna de seller. Um produto novo precisa de name, price e um seller; uma atualização só precisa do SKU e das colunas a mudar.

As chaves de campo para as quais você pode mapear incluem sku, name, slug, status, vendor_id, price, list_price, cost_price, quantity, min_quantity, max_quantity, quantity_step, weight, length, width, height, free_shipping, shipping_freight, description, short_description, promo_text, meta_title, meta_description, meta_keywords, category_id, category_name, category_path, brand, barcode, ncm_code, main_image e additional_images. GET /api/v1/admin/import-export/fields/products devolve a lista completa com rótulos. Uma célula category_id que não é UUID é resolvida como nome ou caminho de categoria. Uma célula de seller pode trazer a razão social, o slug, o e-mail ou o id.

Pré-visualizar (simulação)

POST/api/v1/admin/products/import/previewAdmin

Simulação de uma importação

Roda toda a validação das linhas e não grava nada. O arquivo recebido fica disponível sob o job_id devolvido.

Corpo da requisição (multipart/form-data)

filefileobrigatório

Arquivo CSV ou XLSX.

field_mappingsstring

Objeto JSON {"coluna": "campo"}. Se omitido, usa-se o mapeamento automático.

strategystringpadrão: create_update

create_updateupsertupdate_onlycreate_only

O que fazer com SKUs existentes e novos.

default_vendor_iduuid

Seller das linhas sem seller.

bash

curl -X POST "$BASE_URL/api/v1/admin/products/import/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.csv" -F "strategy=create_update" \
  -F "default_vendor_id=9d9d9d56-eb43-4719-889d-055632f7c7da"

200Resultado da simulação

json

{
  "job_id": "51d36ba6-c07d-4693-b316-f50f3ec8c281",
  "total_rows": 3,
  "would_create": 1,
  "would_update": 1,
  "would_skip": 1,
  "errors_by_row": [
    { "row": 4, "field": "name", "message": "produto novo exige name" }
  ],
  "preview_rows": [
    { "row_number": 2, "action": "update", "data": { "sku": "CAM-001", "name": "Camiseta Azul", "price": "59,90", "quantity": "11" } },
    { "row_number": 3, "action": "create", "data": { "sku": "GAR-004", "name": "Garrafa", "price": "19,90", "quantity": "3" } },
    { "row_number": 4, "action": "error", "data": { "sku": "XXX-005", "name": "", "price": "10,00" }, "error": "produto novo exige name" }
  ],
  "valid": false
}

Campos da resposta

job_iduuid

A importação recebida. Use-a no execute.

total_rowsinteger

Linhas de dados do arquivo.

would_createinteger

Linhas que criariam um produto.

would_updateinteger

Linhas que atualizariam um produto existente.

would_skipinteger

Linhas que seriam recusadas.

errors_by_rowarray

Problemas: row (o cabeçalho é a linha 1), field, message. As mensagens vêm em português.

preview_rowsarray

As 10 primeiras linhas boas e as 10 primeiras ruins: row_number, action (create, update, skip, error), data (os valores por campo do produto) e error.

validboolean

true quando nenhuma linha tem erro.

Validar e sugerir o mapeamento

POST/api/v1/admin/products/import/validateAdmin

Receber o arquivo e validar o mapeamento

Como o preview, e devolve também o que o assistente precisa para desenhar a etapa de mapeamento: as colunas do arquivo, o mapeamento automático e os campos disponíveis. Os mesmos campos de formulário do preview.

Corpo da requisição (multipart/form-data)

filefileobrigatório

Arquivo CSV ou XLSX.

field_mappingsstring

Objeto JSON {"coluna": "campo"}. Vazio significa mapeamento automático.

strategystringpadrão: create_update

create_updateupsertupdate_onlycreate_only

Estratégia.

default_vendor_iduuid

Seller das linhas sem seller.

bash

curl -X POST "$BASE_URL/api/v1/admin/products/import/validate" \
  -H "Authorization: Bearer $TOKEN" -F "file=@produtos.csv"

200Resultado da validação

json

{
  "job_id": "2fead437-b344-4fcc-ab4e-d228141e03ad",
  "total": 3,
  "will_create": 1,
  "will_update": 1,
  "errors": 1,
  "under_moderation": 0,
  "valid": false,
  "auto_mapping": { "sku": "sku", "name": "name", "price": "price", "quantity": "quantity", "status": "status", "category_id": "category_id", "vendor_id": "vendor_id" },
  "csv_columns": ["sku", "name", "price", "quantity", "status", "category_id", "vendor_id"],
  "rows": [
    { "row_number": 2, "action": "create", "data": { "sku": "CAM-001", "name": "Camiseta Azul", "price": "59,90" } },
    { "row_number": 4, "action": "error", "data": { "sku": "XXX-005", "name": "" }, "error": "produto novo exige name" }
  ],
  "available_fields": [
    { "key": "basic", "label": "Basic Information", "label_pt": "Informacoes Basicas", "fields": [{ "key": "sku", "label": "SKU / Product Code", "required": false, "field_type": "string" }] }
  ]
}

Campos da resposta

job_iduuid

A importação recebida.

totalinteger

Linhas de dados.

will_createinteger

Linhas que criariam produtos.

will_updateinteger

Linhas que atualizariam produtos.

errorsinteger

Número de linhas com erro (uma contagem, não uma lista).

under_moderationinteger

Linhas cujos produtos esperariam revisão antes de aparecer na loja.

validboolean

true quando não há erros.

auto_mappingobject

Sugestão {"coluna": "campo"}.

csv_columnsarray

Nomes de cabeçalho encontrados no arquivo.

rowsarray

As 10 primeiras linhas, com row_number, action e data. Aqui action é só create ou error, mesmo para linhas que atualizariam; use will_update para a contagem.

available_fieldsarray

Grupos de campos do produto para os quais você pode mapear, cada um com key, label, label_pt e fields.

Executar

POST/api/v1/admin/products/import/executeAdmin

Executar a importação recebida

Duas formas de chamar:

Com job_id (do preview ou do validate): executa aquele arquivo, de forma síncrona, qualquer que seja o tamanho. Você precisa mandar field_mappings (use o auto_mapping devolvido pelo validate). Sem mapeamento todas as linhas são puladas.
Com file (sem job_id): recebe e executa numa só chamada. Sem field_mappings usa-se o mapeamento automático. Acima de 1000 linhas a importação roda em segundo plano e a resposta vem na hora com status: "processing"; consulte a rota de status.

Corpo da requisição (multipart/form-data)

job_iduuid

Tarefa recebida no preview ou no validate.

filefile

O arquivo, quando não há job_id.

field_mappingsstring

Objeto JSON {"coluna": "campo"}.

strategystringpadrão: create_update

create_updateupdate_onlycreate_only

Estratégia.

default_vendor_iduuid

Seller das linhas sem seller.

test_modestring

true

Com true nada é gravado: age como o validate e precisa do arquivo.

bash

curl -X POST "$BASE_URL/api/v1/admin/products/import/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -F "job_id=2fead437-b344-4fcc-ab4e-d228141e03ad" \
  -F 'field_mappings={"sku":"sku","name":"name","price":"price","vendor_id":"vendor_id"}' \
  -F "strategy=create_update"

200Concluída

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "completed",
  "total_rows": 3,
  "processed_rows": 2,
  "created_count": 1,
  "updated_count": 1,
  "skipped_count": 1,
  "moderation_count": 0,
  "errors": [{ "row": 4, "field": "name", "message": "produto novo exige name" }],
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}

200Iniciada em segundo plano (arquivo acima de 1000 linhas)

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "processing",
  "total_rows": 5400,
  "processed_rows": 0,
  "created_count": 0,
  "updated_count": 0,
  "skipped_count": 0,
  "moderation_count": 0,
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}

Consultar o status

GET/api/v1/admin/products/import/status/{id}Admin

Progresso e resultado de uma importação

Parâmetros de caminho

iduuidobrigatório

O job_id devolvido pelo preview, validate ou execute.

bash

curl "$BASE_URL/api/v1/admin/products/import/status/af361351-ce28-44ef-b389-9cac3a7bac26" \
  -H "Authorization: Bearer $TOKEN"

A resposta tem o mesmo formato da resposta do execute.

Campos da resposta (execute e status)

job_iduuid

A tarefa.

statusstring

pendingprocessingcompletedfailed

pending recebida e não iniciada, processing rodando, completed concluída, failed interrompida por erro fatal.

total_rowsinteger

Linhas de dados.

processed_rowsinteger

Linhas já tratadas.

created_countinteger

Produtos criados.

updated_countinteger

Produtos atualizados.

skipped_countinteger

Linhas recusadas.

moderation_countinteger

Produtos criados aguardando revisão.

errorsarray

Problemas das linhas {row, field, message}. Omitido quando vazio.

warningsarray

Linhas importadas mas não exatamente como escritas (por exemplo um slug que já existia). Só na resposta do execute.

image_stored_countinteger

Imagens baixadas e anexadas.

image_skipped_countinteger

Referências de imagem ignoradas.

image_failed_countinteger

Imagens que não puderam ser buscadas.

Erros

Status	Quando	Exemplo de corpo
400	Não é multipart, ou sem `file` (e sem `job_id`)	`{"error":"missing file field in form","detail":"..."}`
400	`field_mappings` não é JSON válido	`{"error":"invalid field_mappings JSON","detail":"..."}`
400	Arquivo vazio ou planilha malformada	`{"error":"csv_empty","detail":"uploaded file is empty"}`
401 / 403	Sem token / sem `manage_catalog`	`{"error":"missing authorization header"}` / `{"error":"insufficient privileges","required":"manage_catalog"}`
404	Status de uma tarefa desconhecida	`{"error":"import job not found","detail":"import job not found: 000..."}`
415	Extensão não aceita	`{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}`
500	O arquivo não pôde ser lido ou recebido, ou a importação falhou	`{"error":"import execution failed","detail":"..."}`

Veja também

API atual/Guia rápido/Lote, importação e exportação

Assistente de importação

Pré-visualize uma importação sem gravar, mapeie as colunas do arquivo, rode importações grandes em segundo plano e consulte o progresso.

Pré-visualize ou valide
POST /products/import/preview (simulação pura) ou POST /products/import/validate. Os dois recebem o seu arquivo e devolvem um job_id, o auto_mapping sugerido (validate) e os problemas achados linha a linha. Nenhum produto é gravado.
Ajuste o mapeamento
Edite o mapeamento se preciso: é um objeto JSON {"<cabeçalho da coluna no seu arquivo>": "<campo do produto>"}.
Execute
POST /products/import/execute com o job_id e os field_mappings (ou com o próprio arquivo).
Consulte o status
GET /products/import/status/{job_id} a cada 2 segundos até o status ser completed ou failed.

Estratégias e campos de formulário comuns

Pré-visualizar (simulação)

POST/api/v1/admin/products/import/previewAdmin

Simulação de uma importação

Roda toda a validação das linhas e não grava nada. O arquivo recebido fica disponível sob o job_id devolvido.

Corpo da requisição (multipart/form-data)

filefileobrigatório

Arquivo CSV ou XLSX.

field_mappingsstring

Objeto JSON {"coluna": "campo"}. Se omitido, usa-se o mapeamento automático.

strategystringpadrão: create_update

create_updateupsertupdate_onlycreate_only

O que fazer com SKUs existentes e novos.

default_vendor_iduuid

Seller das linhas sem seller.

bash

curl -X POST "$BASE_URL/api/v1/admin/products/import/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.csv" -F "strategy=create_update" \
  -F "default_vendor_id=9d9d9d56-eb43-4719-889d-055632f7c7da"

200Resultado da simulação

json

{
  "job_id": "51d36ba6-c07d-4693-b316-f50f3ec8c281",
  "total_rows": 3,
  "would_create": 1,
  "would_update": 1,
  "would_skip": 1,
  "errors_by_row": [
    { "row": 4, "field": "name", "message": "produto novo exige name" }
  ],
  "preview_rows": [
    { "row_number": 2, "action": "update", "data": { "sku": "CAM-001", "name": "Camiseta Azul", "price": "59,90", "quantity": "11" } },
    { "row_number": 3, "action": "create", "data": { "sku": "GAR-004", "name": "Garrafa", "price": "19,90", "quantity": "3" } },
    { "row_number": 4, "action": "error", "data": { "sku": "XXX-005", "name": "", "price": "10,00" }, "error": "produto novo exige name" }
  ],
  "valid": false
}

Campos da resposta

job_iduuid

A importação recebida. Use-a no execute.

total_rowsinteger

Linhas de dados do arquivo.

would_createinteger

Linhas que criariam um produto.

would_updateinteger

Linhas que atualizariam um produto existente.

would_skipinteger

Linhas que seriam recusadas.

errors_by_rowarray

Problemas: row (o cabeçalho é a linha 1), field, message. As mensagens vêm em português.

preview_rowsarray

As 10 primeiras linhas boas e as 10 primeiras ruins: row_number, action (create, update, skip, error), data (os valores por campo do produto) e error.

validboolean

true quando nenhuma linha tem erro.

Validar e sugerir o mapeamento

POST/api/v1/admin/products/import/validateAdmin

Receber o arquivo e validar o mapeamento

Corpo da requisição (multipart/form-data)

filefileobrigatório

Arquivo CSV ou XLSX.

field_mappingsstring

Objeto JSON {"coluna": "campo"}. Vazio significa mapeamento automático.

strategystringpadrão: create_update

create_updateupsertupdate_onlycreate_only

Estratégia.

default_vendor_iduuid

Seller das linhas sem seller.

bash

curl -X POST "$BASE_URL/api/v1/admin/products/import/validate" \
  -H "Authorization: Bearer $TOKEN" -F "file=@produtos.csv"

200Resultado da validação

json

{
  "job_id": "2fead437-b344-4fcc-ab4e-d228141e03ad",
  "total": 3,
  "will_create": 1,
  "will_update": 1,
  "errors": 1,
  "under_moderation": 0,
  "valid": false,
  "auto_mapping": { "sku": "sku", "name": "name", "price": "price", "quantity": "quantity", "status": "status", "category_id": "category_id", "vendor_id": "vendor_id" },
  "csv_columns": ["sku", "name", "price", "quantity", "status", "category_id", "vendor_id"],
  "rows": [
    { "row_number": 2, "action": "create", "data": { "sku": "CAM-001", "name": "Camiseta Azul", "price": "59,90" } },
    { "row_number": 4, "action": "error", "data": { "sku": "XXX-005", "name": "" }, "error": "produto novo exige name" }
  ],
  "available_fields": [
    { "key": "basic", "label": "Basic Information", "label_pt": "Informacoes Basicas", "fields": [{ "key": "sku", "label": "SKU / Product Code", "required": false, "field_type": "string" }] }
  ]
}

Campos da resposta

job_iduuid

A importação recebida.

totalinteger

Linhas de dados.

will_createinteger

Linhas que criariam produtos.

will_updateinteger

Linhas que atualizariam produtos.

errorsinteger

Número de linhas com erro (uma contagem, não uma lista).

under_moderationinteger

Linhas cujos produtos esperariam revisão antes de aparecer na loja.

validboolean

true quando não há erros.

auto_mappingobject

Sugestão {"coluna": "campo"}.

csv_columnsarray

Nomes de cabeçalho encontrados no arquivo.

rowsarray

As 10 primeiras linhas, com row_number, action e data. Aqui action é só create ou error, mesmo para linhas que atualizariam; use will_update para a contagem.

available_fieldsarray

Grupos de campos do produto para os quais você pode mapear, cada um com key, label, label_pt e fields.

Executar

POST/api/v1/admin/products/import/executeAdmin

Executar a importação recebida

Duas formas de chamar:

Com job_id (do preview ou do validate): executa aquele arquivo, de forma síncrona, qualquer que seja o tamanho. Você precisa mandar field_mappings (use o auto_mapping devolvido pelo validate). Sem mapeamento todas as linhas são puladas.
Com file (sem job_id): recebe e executa numa só chamada. Sem field_mappings usa-se o mapeamento automático. Acima de 1000 linhas a importação roda em segundo plano e a resposta vem na hora com status: "processing"; consulte a rota de status.

Corpo da requisição (multipart/form-data)

job_iduuid

Tarefa recebida no preview ou no validate.

filefile

O arquivo, quando não há job_id.

field_mappingsstring

Objeto JSON {"coluna": "campo"}.

strategystringpadrão: create_update

create_updateupdate_onlycreate_only

Estratégia.

default_vendor_iduuid

Seller das linhas sem seller.

test_modestring

true

Com true nada é gravado: age como o validate e precisa do arquivo.

bash

curl -X POST "$BASE_URL/api/v1/admin/products/import/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -F "job_id=2fead437-b344-4fcc-ab4e-d228141e03ad" \
  -F 'field_mappings={"sku":"sku","name":"name","price":"price","vendor_id":"vendor_id"}' \
  -F "strategy=create_update"

200Concluída

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "completed",
  "total_rows": 3,
  "processed_rows": 2,
  "created_count": 1,
  "updated_count": 1,
  "skipped_count": 1,
  "moderation_count": 0,
  "errors": [{ "row": 4, "field": "name", "message": "produto novo exige name" }],
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}

200Iniciada em segundo plano (arquivo acima de 1000 linhas)

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "processing",
  "total_rows": 5400,
  "processed_rows": 0,
  "created_count": 0,
  "updated_count": 0,
  "skipped_count": 0,
  "moderation_count": 0,
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}

Consultar o status

GET/api/v1/admin/products/import/status/{id}Admin

Progresso e resultado de uma importação

Parâmetros de caminho

iduuidobrigatório

O job_id devolvido pelo preview, validate ou execute.

bash

curl "$BASE_URL/api/v1/admin/products/import/status/af361351-ce28-44ef-b389-9cac3a7bac26" \
  -H "Authorization: Bearer $TOKEN"

A resposta tem o mesmo formato da resposta do execute.

Campos da resposta (execute e status)

job_iduuid

A tarefa.

statusstring

pendingprocessingcompletedfailed

pending recebida e não iniciada, processing rodando, completed concluída, failed interrompida por erro fatal.

total_rowsinteger

Linhas de dados.

processed_rowsinteger

Linhas já tratadas.

created_countinteger

Produtos criados.

updated_countinteger

Produtos atualizados.

skipped_countinteger

Linhas recusadas.

moderation_countinteger

Produtos criados aguardando revisão.

errorsarray

Problemas das linhas {row, field, message}. Omitido quando vazio.

warningsarray

Linhas importadas mas não exatamente como escritas (por exemplo um slug que já existia). Só na resposta do execute.

image_stored_countinteger

Imagens baixadas e anexadas.

image_skipped_countinteger

Referências de imagem ignoradas.

image_failed_countinteger

Imagens que não puderam ser buscadas.

Erros

Status	Quando	Exemplo de corpo
400	Não é multipart, ou sem `file` (e sem `job_id`)	`{"error":"missing file field in form","detail":"..."}`
400	`field_mappings` não é JSON válido	`{"error":"invalid field_mappings JSON","detail":"..."}`
400	Arquivo vazio ou planilha malformada	`{"error":"csv_empty","detail":"uploaded file is empty"}`
401 / 403	Sem token / sem `manage_catalog`	`{"error":"missing authorization header"}` / `{"error":"insufficient privileges","required":"manage_catalog"}`
404	Status de uma tarefa desconhecida	`{"error":"import job not found","detail":"import job not found: 000..."}`
415	Extensão não aceita	`{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}`
500	O arquivo não pôde ser lido ou recebido, ou a importação falhou	`{"error":"import execution failed","detail":"..."}`