API atual/Referência completa/Operações em lote

Tarefas de lote

Lista as tarefas de lote recentes, consulta o estado de uma tarefa e acompanha o progresso em tempo real por eventos.

Um lote com 50 registros ou mais não responde na hora: ele vira uma tarefa que roda no servidor, em pedaços, fora da requisição. Estas três rotas deixam você acompanhar cada tarefa. Elas servem a qualquer lote da plataforma (lote genérico, preços, estoque, importações em massa, desfazer), não só ao POST /bulk/apply.

O estado de cada tarefa é guardado, então uma tarefa que ficou running quando o servidor reiniciou aparece como interrupted, e não "girando para sempre".

Listar tarefas

GET/api/v1/admin/bulk-jobsAdmin

Listar as tarefas de lote mais recentes

Devolve as tarefas da loja, da mais nova para a mais antiga. Sem paginação: use limit.

Parâmetros de consulta

limitintegerpadrão: 20

De 1 a 100. Fora disso vale 20.

session_idstring

Só tarefas iniciadas por esta sessão do painel.

bash

curl "$BASE_URL/api/v1/admin/bulk-jobs?limit=5" \
  -H "Authorization: Bearer $TOKEN"

200Tarefas

json

{
  "jobs": [
    {
      "id": "7341b071-4e43-46fc-9470-19a04cb8d048",
      "route": "POST /bulk/apply",
      "action": "PUT /products/{id}",
      "description": "Editar produtos: calcular price = round(price * 0.9)",
      "status": "done",
      "total": 129,
      "processed": 129,
      "affected": 129,
      "failed": 0,
      "percent": 100,
      "result": { "skipped": 0, "undo_id": "0e6c0167-9b7b-4f72-b810-7c0768d4ce8e" },
      "created_at": "2026-09-15T21:52:29.322653Z",
      "started_at": "2026-09-15T21:52:29.326354Z",
      "finished_at": "2026-09-15T21:52:33.440435Z"
    }
  ]
}

Consultar uma tarefa

GET/api/v1/admin/bulk-jobs/{id}Admin

Estado de uma tarefa de lote

Devolve a tarefa no formato da lista. É a consulta para quem acompanha por polling (a cada 1 a 2 segundos).

Parâmetros de caminho

iduuidobrigatório

Id da tarefa, vindo de job.id na resposta 202.

bash

curl "$BASE_URL/api/v1/admin/bulk-jobs/7341b071-4e43-46fc-9470-19a04cb8d048" \
  -H "Authorization: Bearer $TOKEN"

200Tarefa

O corpo é uma tarefa, como no exemplo da lista.

Campos da resposta

iduuid

Id da tarefa.

routestring

A rota que originou a tarefa (por exemplo POST /bulk/apply ou POST /products/bulk/prices).

actionstring

A ação executada em cada registro.

descriptionstring

Descrição legível, em português.

statusstring

queuedrunningdonefailedinterrupted

Estado.

totalinteger

Registros do recorte.

processedinteger

Quantos já foram tratados, com sucesso ou não.

affectedinteger

Quantos foram alterados.

failedinteger

Quantos falharam.

percentinteger

0 a 100.

errorsarray

Até 50 primeiras falhas, cada uma com id e error. Ausente sem falhas.

resultobject

Dados finais do lote, por exemplo undo_id e skipped. Ausente enquanto roda.

errorstring

Motivo, quando a tarefa inteira falhou.

session_idstring

Sessão do painel que iniciou a tarefa, quando há.

queue_positioninteger

Posição na fila da sessão enquanto queued.

created_atstring

RFC 3339, UTC.

started_atstring

Quando começou. Ausente na fila.

finished_atstring

Quando terminou. Ausente enquanto roda.

Acompanhar em tempo real

GET/api/v1/admin/bulk-jobs/{id}/streamAdmin

Eventos de progresso de uma tarefa (Server-Sent Events)

Abre um fluxo text/event-stream. O servidor envia o estado atual na hora, um evento a cada mudança e fecha o fluxo com o evento done quando a tarefa termina. A cada 15 segundos sem novidade envia uma linha de comentário (: keepalive) para a conexão não cair.

Parâmetros de caminho

iduuidobrigatório

Id da tarefa.

bash

curl -N "$BASE_URL/api/v1/admin/bulk-jobs/7341b071-4e43-46fc-9470-19a04cb8d048/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

200Fluxo de eventos

text

event: progress
data: {"id":"7341b071-...","status":"running","total":129,"processed":40,"percent":31, ...}

: keepalive

event: done
data: {"id":"7341b071-...","status":"done","total":129,"processed":129,"affected":129,"failed":0,"percent":100, ...}

Campos da resposta

eventstring

progressdone

progress a cada mudança; done uma vez, no fim (e o servidor fecha o fluxo).

dataobject

A tarefa em JSON, no mesmo formato das outras rotas.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio de catálogo.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	A tarefa não existe, é de outra loja, ou (no painel de seller) foi iniciada por outro usuário.	`{"error":"bulk job not found"}`
500	Falha ao listar.	`{"error":"failed to list bulk jobs","detail":"..."}`

Veja também

API atual/Referência completa/Operações em lote

Tarefas de lote

Lista as tarefas de lote recentes, consulta o estado de uma tarefa e acompanha o progresso em tempo real por eventos.

O estado de cada tarefa é guardado, então uma tarefa que ficou running quando o servidor reiniciou aparece como interrupted, e não "girando para sempre".

Listar tarefas

GET/api/v1/admin/bulk-jobsAdmin

Listar as tarefas de lote mais recentes

Devolve as tarefas da loja, da mais nova para a mais antiga. Sem paginação: use limit.

Parâmetros de consulta

limitintegerpadrão: 20

De 1 a 100. Fora disso vale 20.

session_idstring

Só tarefas iniciadas por esta sessão do painel.

bash

curl "$BASE_URL/api/v1/admin/bulk-jobs?limit=5" \
  -H "Authorization: Bearer $TOKEN"

200Tarefas

json

{
  "jobs": [
    {
      "id": "7341b071-4e43-46fc-9470-19a04cb8d048",
      "route": "POST /bulk/apply",
      "action": "PUT /products/{id}",
      "description": "Editar produtos: calcular price = round(price * 0.9)",
      "status": "done",
      "total": 129,
      "processed": 129,
      "affected": 129,
      "failed": 0,
      "percent": 100,
      "result": { "skipped": 0, "undo_id": "0e6c0167-9b7b-4f72-b810-7c0768d4ce8e" },
      "created_at": "2026-09-15T21:52:29.322653Z",
      "started_at": "2026-09-15T21:52:29.326354Z",
      "finished_at": "2026-09-15T21:52:33.440435Z"
    }
  ]
}

Consultar uma tarefa

GET/api/v1/admin/bulk-jobs/{id}Admin

Estado de uma tarefa de lote

Devolve a tarefa no formato da lista. É a consulta para quem acompanha por polling (a cada 1 a 2 segundos).

Parâmetros de caminho

iduuidobrigatório

Id da tarefa, vindo de job.id na resposta 202.

bash

curl "$BASE_URL/api/v1/admin/bulk-jobs/7341b071-4e43-46fc-9470-19a04cb8d048" \
  -H "Authorization: Bearer $TOKEN"

200Tarefa

O corpo é uma tarefa, como no exemplo da lista.

Campos da resposta

iduuid

Id da tarefa.

routestring

A rota que originou a tarefa (por exemplo POST /bulk/apply ou POST /products/bulk/prices).

actionstring

A ação executada em cada registro.

descriptionstring

Descrição legível, em português.

statusstring

queuedrunningdonefailedinterrupted

Estado.

totalinteger

Registros do recorte.

processedinteger

Quantos já foram tratados, com sucesso ou não.

affectedinteger

Quantos foram alterados.

failedinteger

Quantos falharam.

percentinteger

0 a 100.

errorsarray

Até 50 primeiras falhas, cada uma com id e error. Ausente sem falhas.

resultobject

Dados finais do lote, por exemplo undo_id e skipped. Ausente enquanto roda.

errorstring

Motivo, quando a tarefa inteira falhou.

session_idstring

Sessão do painel que iniciou a tarefa, quando há.

queue_positioninteger

Posição na fila da sessão enquanto queued.

created_atstring

RFC 3339, UTC.

started_atstring

Quando começou. Ausente na fila.

finished_atstring

Quando terminou. Ausente enquanto roda.

Acompanhar em tempo real

GET/api/v1/admin/bulk-jobs/{id}/streamAdmin

Eventos de progresso de uma tarefa (Server-Sent Events)

Parâmetros de caminho

iduuidobrigatório

Id da tarefa.

bash

curl -N "$BASE_URL/api/v1/admin/bulk-jobs/7341b071-4e43-46fc-9470-19a04cb8d048/stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

200Fluxo de eventos

text

event: progress
data: {"id":"7341b071-...","status":"running","total":129,"processed":40,"percent":31, ...}

: keepalive

event: done
data: {"id":"7341b071-...","status":"done","total":129,"processed":129,"affected":129,"failed":0,"percent":100, ...}

Campos da resposta

eventstring

progressdone

progress a cada mudança; done uma vez, no fim (e o servidor fecha o fluxo).

dataobject

A tarefa em JSON, no mesmo formato das outras rotas.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio de catálogo.	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	A tarefa não existe, é de outra loja, ou (no painel de seller) foi iniciada por outro usuário.	`{"error":"bulk job not found"}`
500	Falha ao listar.	`{"error":"failed to list bulk jobs","detail":"..."}`