API atual/Referência completa/Importação e exportação

Jobs de importação

Consulta o andamento de uma importação em segundo plano, pede o cancelamento e baixa o relatório de erros por linha.

Uma importação grande não termina dentro da requisição. A plataforma devolve um job (um trabalho em segundo plano) e continua gravando. Estas quatro rotas servem para saber em que ponto o job está, para parar um job que você começou por engano e para descobrir quais linhas falharam e por quê.

O job_id vem das respostas de Importar produtos, de preços por quantidade e do assistente de importação. Todas as rotas abaixo exigem manage_catalog.

Ciclo de vida do job

pending→processing→completed

Status	Significado
`pending`	O arquivo foi recebido e preparado, mas a gravação ainda não começou.
`processing`	A gravação está em andamento.
`completed`	Terminou. Isso não quer dizer que todas as linhas entraram: veja `skipped_count` e os erros.
`failed`	Parou por erro geral ou foi cancelado pelo usuário. As linhas gravadas antes da parada continuam gravadas.

GET/api/v1/admin/import/jobs/{id}Admin

Consulta um job de importação

Devolve o estado completo do job, com as contagens finais e a lista de erros.

Parâmetros de caminho

iduuidobrigatório

Id do job (job_id).

GET/api/v1/admin/import/jobs/{id}/progressAdmin

Andamento resumido do job

Versão leve para uma barra de progresso: só contadores e porcentagem, sem a lista de erros. Consulte a cada dois segundos; não há ganho em consultar mais rápido.

Parâmetros de caminho

iduuidobrigatório

Id do job.

POST/api/v1/admin/import/jobs/{id}/cancelAdmin

Pede o cancelamento do job

Marca o job para parar. A gravação confere o pedido a cada 25 linhas e então para; o job termina como failed, com o erro cancelled by user. O que já foi gravado não é desfeito. Só funciona em job que ainda não terminou; em job concluído a resposta é 404.

Parâmetros de caminho

iduuidobrigatório

Id do job.

GET/api/v1/admin/import/jobs/{id}/errors.csvAdmin

Baixa os erros por linha em CSV

Devolve um CSV (UTF-8 com BOM, anexo import-errors-<id>.csv) com as colunas row, field e message, uma linha por problema. row é o número da linha na planilha enviada (o cabeçalho é a linha 1). Funciona com o job em andamento ou terminado. Sem erros, o arquivo só tem o cabeçalho.

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

JOB=7aa94252-0df6-4293-8404-c0ffc2a96fbc

curl "$BASE_URL/api/v1/admin/import/jobs/$JOB/progress" -H "Authorization: Bearer $TOKEN"

curl -X POST "$BASE_URL/api/v1/admin/import/jobs/$JOB/cancel" -H "Authorization: Bearer $TOKEN"

curl "$BASE_URL/api/v1/admin/import/jobs/$JOB/errors.csv" -H "Authorization: Bearer $TOKEN" -o erros.csv

Resposta

200Job consultado

json

{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "completed",
  "total_rows": 2,
  "processed_rows": 2,
  "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
}

200Andamento

json

{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "processing",
  "total": 12840,
  "processed": 3200,
  "percent": 24.9,
  "current_chunk": 64,
  "created_count": 2900,
  "updated_count": 280,
  "skipped_count": 20,
  "error_count": 20
}

200Cancelamento pedido

json

{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "cancelling",
  "message": "cancel requested; the import loop will stop at the next 25-row checkpoint"
}

Campos da resposta (job)

statusstring

pendingprocessingcompletedfailed

Estado do job.

total_rowsinteger

Linhas de dados no arquivo.

processed_rowsinteger

Linhas já tratadas.

created_countinteger

Registros criados.

updated_countinteger

Registros atualizados.

skipped_countinteger

Linhas puladas por erro.

moderation_countinteger

Produtos que entraram em moderação (aguardando aprovação) em vez de ir direto ao ar.

errorsarray

Erros por linha (row, field, message). Pode faltar quando não há erro.

image_stored_countinteger

Imagens baixadas e gravadas, quando a planilha trazia imagens.

image_skipped_countinteger

Imagens ignoradas.

image_failed_countinteger

Imagens que falharam ao baixar.

Campos da resposta (andamento)

totalinteger

Linhas de dados.

processedinteger

Linhas tratadas.

percentnumber

De 0 a 100.

current_chunkinteger

Lote atual. A gravação trabalha em lotes de 50 linhas.

error_countinteger

Linhas com erro (igual a skipped_count).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Job não existe	`{"error":"import job not found","detail":"import job not found: <id>"}`
404	Cancelar um job que já terminou	`{"error":"cancel failed","detail":"import job <id> not found or already finished"}`
404	Andamento de job que não existe	`{"error":"progress lookup failed","detail":"..."}`

Veja também

Jobs de importação

Consulta o andamento de uma importação em segundo plano, pede o cancelamento e baixa o relatório de erros por linha.

O job_id vem das respostas de Importar produtos, de preços por quantidade e do assistente de importação. Todas as rotas abaixo exigem manage_catalog.

Ciclo de vida do job

pending→processing→completed

Status	Significado
`pending`	O arquivo foi recebido e preparado, mas a gravação ainda não começou.
`processing`	A gravação está em andamento.
`completed`	Terminou. Isso não quer dizer que todas as linhas entraram: veja `skipped_count` e os erros.
`failed`	Parou por erro geral ou foi cancelado pelo usuário. As linhas gravadas antes da parada continuam gravadas.

GET/api/v1/admin/import/jobs/{id}Admin

Consulta um job de importação

Devolve o estado completo do job, com as contagens finais e a lista de erros.

Parâmetros de caminho

iduuidobrigatório

Id do job (job_id).

GET/api/v1/admin/import/jobs/{id}/progressAdmin

Andamento resumido do job

Versão leve para uma barra de progresso: só contadores e porcentagem, sem a lista de erros. Consulte a cada dois segundos; não há ganho em consultar mais rápido.

Parâmetros de caminho

iduuidobrigatório

Id do job.

POST/api/v1/admin/import/jobs/{id}/cancelAdmin

Pede o cancelamento do job

Parâmetros de caminho

iduuidobrigatório

Id do job.

GET/api/v1/admin/import/jobs/{id}/errors.csvAdmin

Baixa os erros por linha em CSV

Parâmetros de caminho

iduuidobrigatório

Id do job.

Exemplo de requisição

bash

JOB=7aa94252-0df6-4293-8404-c0ffc2a96fbc

curl "$BASE_URL/api/v1/admin/import/jobs/$JOB/progress" -H "Authorization: Bearer $TOKEN"

curl -X POST "$BASE_URL/api/v1/admin/import/jobs/$JOB/cancel" -H "Authorization: Bearer $TOKEN"

curl "$BASE_URL/api/v1/admin/import/jobs/$JOB/errors.csv" -H "Authorization: Bearer $TOKEN" -o erros.csv

Resposta

200Job consultado

json

{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "completed",
  "total_rows": 2,
  "processed_rows": 2,
  "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
}

200Andamento

json

{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "processing",
  "total": 12840,
  "processed": 3200,
  "percent": 24.9,
  "current_chunk": 64,
  "created_count": 2900,
  "updated_count": 280,
  "skipped_count": 20,
  "error_count": 20
}

200Cancelamento pedido

json

{
  "job_id": "7aa94252-0df6-4293-8404-c0ffc2a96fbc",
  "status": "cancelling",
  "message": "cancel requested; the import loop will stop at the next 25-row checkpoint"
}

Campos da resposta (job)

statusstring

pendingprocessingcompletedfailed

Estado do job.

total_rowsinteger

Linhas de dados no arquivo.

processed_rowsinteger

Linhas já tratadas.

created_countinteger

Registros criados.

updated_countinteger

Registros atualizados.

skipped_countinteger

Linhas puladas por erro.

moderation_countinteger

Produtos que entraram em moderação (aguardando aprovação) em vez de ir direto ao ar.

errorsarray

Erros por linha (row, field, message). Pode faltar quando não há erro.

image_stored_countinteger

Imagens baixadas e gravadas, quando a planilha trazia imagens.

image_skipped_countinteger

Imagens ignoradas.

image_failed_countinteger

Imagens que falharam ao baixar.

Campos da resposta (andamento)

totalinteger

Linhas de dados.

processedinteger

Linhas tratadas.

percentnumber

De 0 a 100.

current_chunkinteger

Lote atual. A gravação trabalha em lotes de 50 linhas.

error_countinteger

Linhas com erro (igual a skipped_count).

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	Job não existe	`{"error":"import job not found","detail":"import job not found: <id>"}`
404	Cancelar um job que já terminou	`{"error":"cancel failed","detail":"import job <id> not found or already finished"}`
404	Andamento de job que não existe	`{"error":"progress lookup failed","detail":"..."}`