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

Assistente de importação

Importa produtos em quatro etapas (enviar, validar, executar, acompanhar), com mapeamento de colunas, opções e simulação sem gravar.

O assistente é a importação de produtos com controle. Em vez de depender do nome das colunas da planilha, você vê as colunas encontradas, escolhe para qual campo do produto cada uma vai, valida o resultado antes de gravar e só então executa. É o mesmo fluxo da tela de importação do painel.

Enviar o arquivo→Validar o mapeamento→Executar→Acompanhar o job

Cada etapa é uma chamada. O job criado no envio (job_id) carrega o arquivo e liga as etapas entre si. Todas as rotas exigem o privilégio manage_catalog.

Antes de usar o assistente

Para uma planilha no formato do modelo, a rota simples Importar produtos resolve em uma chamada. Use o assistente quando as colunas têm outros nomes, quando precisa ajustar valores durante a importação (reajuste de preço, prefixo no nome), criar categorias que não existem ou testar sem gravar.

POST/api/v1/admin/advanced-import/uploadAdmin

Etapa 1: envia o arquivo e recebe as colunas

Lê o arquivo, detecta o separador, sugere o mapeamento de colunas e guarda tudo em um job. Nada é gravado no catálogo. Envie multipart/form-data.

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

filefileobrigatório
Planilha .csv, .txt, .xml, .xlsx ou .xlsm.
object_typestringpadrão: products
Tipo de registro do job. O assistente de produtos usa o padrão.
POST/api/v1/admin/advanced-import/validateAdmin

Etapa 2: valida o mapeamento sem gravar

Aplica o mapeamento e as opções ao arquivo do job e conta o que aconteceria: quantos produtos seriam criados, atualizados ou pulados, e quais linhas têm erro. Não grava produtos.

Corpo da requisição (JSON)

job_iduuidobrigatório
O job_id do envio.
field_mappingobjectobrigatório
Mapa de nome da coluna da planilha para campo do produto, por exemplo {"Código":"sku","Preço":"price"}. Não pode ser vazio. Os campos válidos estão em Campos importáveis e exportáveis.
optionsobject

Opções da importação.

strategystringpadrão: import_all
import_allupdate_existingcreate_new
import_all cria e atualiza; update_existing só atualiza SKUs que já existem; create_new só cria.
update_existingboolean
Quando false, linhas cujo SKU já existe são puladas.
skip_errorsboolean
Quando true, uma linha com erro é registrada e o resto continua. Quando false (ou omitido), a execução para na primeira linha com erro.
default_vendor_iduuid
Seller padrão das linhas sem vendor_id. A coluna da planilha vence quando preenchida.
delimiterstring
Separador do arquivo, se você quiser forçar. Por padrão é detectado.
create_categoriesboolean
Quando true, os trechos de categoria que não existem são criados.
category_delimiterstringpadrão: ///
Separador dos níveis dentro de um caminho de categoria (Moda///Camisetas).
price_formatstringpadrão: auto
autodecimalcents
Como ler o preço: decimal são reais (49,90), cents são centavos inteiros (4990), auto decide pelo valor.
POST/api/v1/admin/advanced-import/executeAdmin

Etapa 3: executa a importação

Grava os produtos. Aceita as mesmas opções da validação mais as abaixo. Com até 1.000 linhas, roda dentro da requisição e responde com o resultado final (status completed). Com mais de 1.000, vira trabalho em segundo plano: a resposta é 200 com status processing e você acompanha na etapa 4.

Corpo da requisição (JSON)

job_iduuidobrigatório
O job_id do envio.
field_mappingobjectobrigatório
O mesmo mapeamento da validação.
optionsobject

Mesmas opções da validação, mais:

dry_runbooleanpadrão: false
Roda toda a validação e a classificação (criar ou atualizar), mas não grava nada. Os contadores da resposta dizem o que teria acontecido.
set_zero_quantitiesbooleanpadrão: false
Zera o estoque de todos os produtos antes de importar. É a opção de quem manda a planilha de estoque completa e quer que o que não está nela fique sem saldo. Destrutiva.
data_modifiersarray

Transformações aplicadas ao valor de um campo antes de gravar.

field_keystringobrigatório
Campo que recebe a transformação (price, name...).
typestringobrigatório
nonepercent_markuppercent_discountfixed_addfixed_subtractmultiplyroundtext_prefixtext_suffixtext_replaceset_value
Tipo da transformação. As numéricas (percent_markup, percent_discount, fixed_add, fixed_subtract, multiply, round) valem para preço e quantidade; as de texto (text_prefix, text_suffix, text_replace) para nome e descrição; set_value serve para qualquer campo.
valuestring
Valor principal: o percentual, o valor somado, o fator, o texto, o número de casas decimais.
value2string
Segundo valor: o texto de substituição em text_replace.
GET/api/v1/admin/advanced-import/jobs/{id}Admin

Etapa 4: consulta o job

Devolve o estado do job. É a mesma resposta de /import/jobs/{id}, então vale para ambas as famílias de rotas.

Parâmetros de caminho

iduuidobrigatório
O job_id.

Exemplo de requisição

bash
# 1) enviar
curl "$BASE_URL/api/v1/admin/advanced-import/upload" \
  -H "Authorization: Bearer $TOKEN" -F "file=@erp.csv"

# 2) validar (use o job_id da resposta anterior)
curl "$BASE_URL/api/v1/admin/advanced-import/validate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"job_id":"7aa94252-0df6-4293-8404-c0ffc2a96fbc",
       "field_mapping":{"Código":"sku","Descrição":"name","Preço":"price","Saldo":"quantity","Fornecedor":"vendor_id"},
       "options":{"strategy":"import_all","skip_errors":true,"price_format":"decimal"}}'

# 3) executar, com reajuste de 10% no preço
curl "$BASE_URL/api/v1/admin/advanced-import/execute" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"job_id":"7aa94252-0df6-4293-8404-c0ffc2a96fbc",
       "field_mapping":{"Código":"sku","Descrição":"name","Preço":"price","Saldo":"quantity","Fornecedor":"vendor_id"},
       "options":{"strategy":"import_all","skip_errors":true,"price_format":"decimal",
                  "data_modifiers":[{"field_key":"price","type":"percent_markup","value":"10"}]}}'

Resposta

200Etapa 1: arquivo recebido
json
{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "file_name": "erp.csv",
  "total_rows": 2,
  "csv_columns": ["product_code", "name", "price", "status", "quantity", "vendor_id"],
  "detected_delimiter": ";",
  "preview_rows": [
    ["DOCS-API-001", "Camiseta Docs Teste", "49,90", "A", "10", "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"],
    ["DOCS-API-002", "", "19,90", "A", "5", ""]
  ],
  "auto_mapping": { "name": "name", "price": "price", "product_code": "sku", "quantity": "quantity", "status": "status", "vendor_id": "vendor_id" },
  "available_fields": [
    {
      "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" }
      ]
    }
  ]
}
200Etapa 2: validação
json
{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "total_rows": 2,
  "will_create": 1,
  "will_update": 0,
  "will_skip": 1,
  "moderation_count": 0,
  "errors": [
    {
      "row": 3,
      "field": "vendor_id,name",
      "message": "produto novo exige vendor_id, name — selecione o \"Vendedor padrão\" ou mapeie uma coluna para vendor_id"
    }
  ],
  "valid": false
}
200Etapa 3: resultado (simulação com dry_run)
json
{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "completed",
  "total_rows": 2,
  "processed_rows": 0,
  "created_count": 1,
  "updated_count": 0,
  "skipped_count": 1,
  "moderation_count": 0,
  "errors": [
    { "row": 3, "field": "vendor_id,name", "message": "produto novo exige vendor_id, name — selecione o \"Vendedor padrão\" antes de importar, ou mapeie uma coluna para vendor_id" }
  ],
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}

Campos da resposta (envio)

job_iduuid
Id do job. Guarde para as próximas etapas.
file_namestring
Nome do arquivo enviado.
total_rowsinteger
Linhas de dados.
csv_columnsarray
Nomes das colunas, na ordem do arquivo.
detected_delimiterstring
Separador detectado (;, , ou tabulação).
preview_rowsarray
As primeiras linhas, como listas de texto na ordem de csv_columns.
auto_mappingobject
Mapeamento sugerido: nome da coluna para campo do produto. Pode ser usado direto em field_mapping.
available_fieldsarray
Campos disponíveis, agrupados (basic, pricing, inventory...). Cada campo tem key, label, label_pt, required, field_type e group.

Campos da resposta (validação)

will_createinteger
Produtos que seriam criados.
will_updateinteger
Produtos que seriam atualizados.
will_skipinteger
Linhas que seriam puladas.
moderation_countinteger
Produtos que cairiam em moderação (aguardam aprovação) em vez de ir direto ao ar.
errorsarray
Erros por linha (row, field, message).
warningsarray
Avisos que não impedem a importação (preço ambíguo, caminho de categoria que não existe). Pode faltar.
validboolean
true quando não há erro.
fatalboolean
true quando a execução não deve começar (por exemplo, linhas vazias no meio do arquivo). Só aparece quando verdadeiro.

Erros

StatusQuandoCorpo de exemplo
400file ausente no envio{"error":"missing file field in form","detail":"http: no such file"}
400job_id ausente{"error":"job_id is required"}
400field_mapping ausente ou vazio{"error":"field_mapping is required"}
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
400Arquivo vazio, linha em branco ou coluna obrigatória ausente{"error":"csv_empty","detail":"uploaded file is empty"}
401Token ausente ou expirado{"error":"invalid or expired token"}
403Falta manage_catalog{"error":"insufficient privileges","required":"manage_catalog"}
404GET de um job que não existe{"error":"import job not found","detail":"import job not found: <id>"}
415Extensão não aceita no envio{"error":"unsupported file type","detail":"..."}
500validate ou execute com um job_id que não existe{"error":"validation failed","detail":"import job not found: <id>"}
job_id inexistente volta 500, não 404

Nas etapas de validar e executar, um job_id desconhecido responde 500 (validation failed ou get job status failed). Só a consulta do job (GET) usa 404. Trate os dois como "job não encontrado".

set_zero_quantities zera o estoque de todo o catálogo

Com set_zero_quantities: true, o estoque de todos os produtos vai a zero antes da primeira linha. Se a execução falhar no meio, os produtos que ainda não chegaram na fila ficam sem saldo. Use dry_run primeiro e só ligue esta opção quando a planilha for o estoque completo.

Veja também

  • Importar produtos
  • Predefinições de importação
  • Jobs de importação
Anterior
Importação avançada
Próxima
Predefinições de importação
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também