VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Assistente de importação

Importar em etapas

Envia a planilha, valida o mapeamento, executa a importação de produtos e acompanha o andamento.

As quatro chamadas abaixo formam o fluxo completo. Guarde o job_id do primeiro passo: ele identifica a importação em todos os outros.

1. Enviar

POST/api/v1/vendor/import/uploadSeller

Enviar a planilha

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

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

filefileobrigatório
Planilha .csv, .txt, .xml, .xlsx ou .xlsm. Formulário de até 64 MB. O delimitador (; ou ,) é detectado sozinho.
object_typestringpadrão: products
Só products é aceito.

Exemplo de requisição (enviar)

Resposta (enviar)

200Planilha lida

Campos da resposta

job_idstring (uuid)
Id da importação. Use em validate, execute e status.
file_namestring
Nome do arquivo enviado.
total_rowsinteger
Linhas de dados (sem o cabeçalho).
csv_columnsarray of string
Colunas do cabeçalho.
detected_delimiterstring
Delimitador detectado.
preview_rowsarray
Até 5 primeiras linhas.
auto_mappingobject
Sugestão coluna para campo. Pode conter erros: revise.
available_fieldsarray
Campos aceitos, em grupos: key, label, label_pt e fields[] (key, required, field_type, default_value...).

Erros (enviar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}
400Falta file, formulário inválido, object_type diferente de products, planilha vazia ou inválida.{"error":"vendor imports limited to products","detail":"users"}
415Extensão não aceita.{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}

2. Validar

Percorre todas as linhas aplicando o mapeamento e classifica cada uma como criar, atualizar ou ignorar. Não grava produtos. Guarda o mapeamento e as opções no trabalho.

POST/api/v1/vendor/import/validateSeller

Validar o mapeamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

job_idstring (uuid)obrigatório
Id devolvido por upload.
field_mappingobjectobrigatório
Mapeamento no formato {"<nome da coluna na planilha>": "<campo da plataforma>"}. Colunas não mapeadas são ignoradas.
optionsobject

Opções da importação.

strategystringpadrão: import_all
import_allupdate_existingcreate_new
import_all cria e atualiza; update_existing só atualiza; create_new só cria.
update_existingboolean
Atualiza produtos que já existem.
skip_errorsboolean
Continua depois de uma linha com erro.
delimiterstring
Força o delimitador, em vez do detectado.
create_categoriesboolean
Cria as categorias que faltarem.
category_delimiterstringpadrão: ///
Separador de níveis em category_path.
price_formatstringpadrão: auto
autodecimalcents
Como ler preços.

Exemplo de requisição (validar)

Resposta (validar)

200Resultado da validação

Campos da resposta

job_idstring (uuid)
A importação.
total_rowsinteger
Linhas lidas.
will_createinteger
Produtos que serão criados.
will_updateinteger
Produtos que serão atualizados.
will_skipinteger
Linhas que serão ignoradas.
moderation_countinteger
Produtos que ficarão pendentes de aprovação (premoderação).
validboolean
false se há erro que impede a execução.
fatalboolean
Presente e true quando a execução não deve nem começar (por exemplo, linha em branco).
errorsarray
Erros por linha: row, field, message.
warningsarray
Avisos que não bloqueiam (preço ambíguo, categoria não resolvida, linhas sem vendedor).

Erros (validar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}
400job_id ou field_mapping ausentes, ou corpo inválido.{"error":"field_mapping is required"}
500Importação inexistente ou arquivo já apagado.{"error":"validation failed","detail":"..."}

3. Executar

Grava os produtos. Até 1.000 linhas a chamada espera o fim e devolve as contagens finais; acima disso a importação roda em segundo plano e a resposta traz status: "processing". O vendor_id é sempre o seu.

POST/api/v1/vendor/import/executeSeller

Executar a importação

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

job_idstring (uuid)obrigatório
Id devolvido por upload.
field_mappingobjectobrigatório
Mapeamento no formato {"<nome da coluna na planilha>": "<campo da plataforma>"}. Colunas não mapeadas são ignoradas.
optionsobject

As mesmas opções de validate, mais as abaixo.

strategystringpadrão: import_all
import_allupdate_existingcreate_new
Estratégia.
update_existingboolean
Atualiza existentes.
skip_errorsboolean
Continua após erro de linha.
create_categoriesboolean
Cria categorias que faltam.
category_delimiterstring
Separador de categorias.
price_formatstring
autodecimalcents
Formato de preço.
dry_runbooleanpadrão: false
true roda tudo e conta, mas não grava nada.
data_modifiersarray

Transformações de valor por campo, aplicadas antes de gravar. Entram na ordem enviada e só valem para o campo indicado em field_key.

field_keystringobrigatório
Campo da plataforma ao qual o modificador se aplica (um valor de field_mapping, por exemplo price). Funciona em campos de valor único, como sku, name, price, quantity, barcode, description e weight.
typestringobrigatório
nonepercent_markuppercent_discountfixed_addfixed_subtracttext_prefixtext_suffixtext_replaceset_valueroundmultiply
Transformação. Um tipo desconhecido é reportado em errors e o valor original é mantido.
valuestring
Valor principal: o percentual, o valor a somar, o texto a acrescentar, o texto a localizar, o valor fixo, o número de casas decimais ou o fator.
value2string
Texto de substituição, só para text_replace.

Exemplo de requisição (executar)

Resposta (executar)

200Importação concluída
200Importação em segundo plano

Campos da resposta

job_idstring (uuid)
A importação.
statusstring
completed ou processing.
total_rowsinteger
Linhas de dados.
processed_rowsinteger
Linhas processadas.
created_countinteger
Criados.
updated_countinteger
Atualizados.
skipped_countinteger
Ignorados.
moderation_countinteger
Que ficaram pendentes de aprovação.
errorsarray
Erros por linha: row, field, message.
warningsarray
Linhas importadas, mas não exatamente como escritas.
image_stored_countinteger
Imagens gravadas.
image_skipped_countinteger
Imagens ignoradas.
image_failed_countinteger
Imagens com falha.

Erros (executar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}
400job_id ou field_mapping ausentes; planilha sem coluna de identidade; coluna obrigatória faltando.{"error":"missing_required_column","detail":"missing required column: price"}
500Importação inexistente, ou falha geral na execução.{"error":"import execution failed","detail":"..."}

4. Acompanhar

GET/api/v1/vendor/import/status/{id}Seller

Acompanhar a importação

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id da importação (job_id) devolvido pelo envio.

Exemplo de requisição (acompanhar)

Resposta (acompanhar)

200Andamento

Campos da resposta

(campos)object
Os mesmos campos da resposta de execute, com status entre pending, processing, completed e failed.

Erros (acompanhar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}
404Importação inexistente.{"error":"import job not found","detail":"..."}
Não envie `set_zero_quantities`

A opção options.set_zero_quantities existe no corpo de execute, mas ela zera o estoque de todos os produtos da loja, de todos os sellers, antes de importar. Nunca a use na API do seller.

Ensaio primeiro

Rode execute com dry_run: true na primeira vez. Você recebe as mesmas contagens e erros, sem gravar, e depois repete com dry_run: false.

Acompanhamento

Em importações de até 1.000 linhas a própria resposta de execute já é o resultado final; status serve para as maiores. O arquivo enviado é apagado quando a execução termina.

Veja também

  • Assistente de importação: visão geral
Anterior
Assistente de importação
Próxima
Modelos de mapeamento
Nesta página
  • 1. Enviar
  • Exemplo de requisição (enviar)
  • Resposta (enviar)
  • Erros (enviar)
  • 2. Validar
  • Exemplo de requisição (validar)
  • Resposta (validar)
  • Erros (validar)
  • 3. Executar
  • Exemplo de requisição (executar)
  • Resposta (executar)
  • Erros (executar)
  • 4. Acompanhar
  • Exemplo de requisição (acompanhar)
  • Resposta (acompanhar)
  • Erros (acompanhar)
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/vendor/import/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.xlsx"
bash
curl -X POST "$BASE_URL/api/v1/vendor/import/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "field_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity",
    "Categoria": "category_path"
  },
  "options": {
    "strategy": "import_all",
    "update_existing": true,
    "skip_errors": true,
    "create_categories": true,
    "category_delimiter": "///",
    "price_format": "decimal"
  }
}'
bash
curl -X POST "$BASE_URL/api/v1/vendor/import/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "field_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity",
    "Categoria": "category_path"
  },
  "options": {
    "strategy": "import_all",
    "update_existing": true,
    "skip_errors": true,
    "create_categories": true,
    "category_delimiter": "///",
    "price_format": "decimal",
    "dry_run": false
  }
}'
bash
curl "$BASE_URL/api/v1/vendor/import/status/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "file_name": "produtos.xlsx",
  "total_rows": 2,
  "csv_columns": [
    "Código",
    "Produto",
    "Preço",
    "Estoque",
    "Categoria"
  ],
  "detected_delimiter": ";",
  "preview_rows": [
    [
      "CAM-001",
      "Camiseta Básica Preta",
      "49,90",
      "25",
      "Roupas///Camisetas"
    ],
    [
      "BON-001",
      "Boné Liso",
      "39,90",
      "10",
      "Roupas///Bonés"
    ]
  ],
  "auto_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity"
  },
  "available_fields": [
    {
      "key": "basic",
      "label": "Basic",
      "label_pt": "Básico",
      "fields": [
        {
          "key": "sku",
          "label": "SKU / Product Code",
          "label_pt": "Codigo do Produto",
          "group": "basic",
          "required": false,
          "db_column": "sku",
          "field_type": "string"
        }
      ]
    }
  ]
}
json
{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "total_rows": 2,
  "will_create": 1,
  "will_update": 1,
  "will_skip": 0,
  "moderation_count": 2,
  "valid": true,
  "warnings": []
}
json
{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "status": "completed",
  "total_rows": 2,
  "processed_rows": 2,
  "created_count": 1,
  "updated_count": 1,
  "skipped_count": 0,
  "moderation_count": 2,
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}
json
{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "status": "processing",
  "total_rows": 5400
}
json
{
  "job_id": "5a6b7c8d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "status": "processing",
  "total_rows": 5400,
  "processed_rows": 2300,
  "created_count": 1500,
  "updated_count": 800,
  "skipped_count": 0,
  "moderation_count": 1500,
  "image_stored_count": 0,
  "image_skipped_count": 0,
  "image_failed_count": 0
}