API atual/Referência completa/Ferramentas do catálogo do seller

Tarefas em lote

Consulta o estado de uma tarefa em lote do seller e acompanha o progresso em tempo real.

Operações que mexem em muitos registros (clonar dezenas de mestres, editar produtos por filtro) não cabem numa resposta HTTP. Quando a execução alcança 50 registros ou mais, a plataforma responde 202 com uma tarefa e continua o trabalho em segundo plano. As rotas abaixo mostram o andamento. Elas só enxergam tarefas iniciadas pelo seu usuário.

Consultar a tarefa

GET/api/v1/vendor/bulk-jobs/{id}Seller

Estado de uma tarefa em lote

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da tarefa (vem em job.id na resposta 202 da operação em lote).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Tarefa

json

{
  "id": "7341b071-4e43-46fc-9470-19a04cb8d048",
  "route": "POST /vendor/master-catalog/bulk-clone",
  "action": "clone",
  "description": "Clonar produtos do catálogo mestre para a loja do seller",
  "status": "running",
  "total": 87,
  "processed": 40,
  "affected": 38,
  "failed": 2,
  "percent": 45,
  "errors": [
    {
      "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "error": "..."
    }
  ],
  "created_at": "2026-10-11T22:05:00Z",
  "started_at": "2026-10-11T22:05:01Z"
}

Campos da resposta

iduuid

Id da tarefa.

routestring

Rota que gerou a tarefa.

actionstring

Ação executada.

descriptionstring

Descrição para o usuário, em português.

statusstring

queuedrunningdonefailedinterrupted

Estado da tarefa.

totalinteger

Registros no recorte.

processedinteger

Registros já tratados.

affectedinteger

Registros alterados com sucesso.

failedinteger

Registros que falharam.

percentinteger

0 a 100.

errorsarray

Até 50 primeiras falhas (id, error). Ausente sem falhas.

resultobject

Dados extras da operação (por exemplo skipped). Ausente se não houver.

errorstring

Motivo, quando failed.

session_idstring

Conversa da Venddor Intelligence que iniciou a tarefa. Ausente se não foi por ela.

queue_positioninteger

Posição na fila da conversa, quando queued.

created_atstring

RFC 3339.

started_atstring

RFC 3339. Ausente enquanto na fila.

finished_atstring

RFC 3339. Ausente enquanto em andamento.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
404	Tarefa inexistente, de outra loja ou iniciada por outro usuário.	`{"error":"bulk job not found"}`

Acompanhar em tempo real

Abre uma conexão text/event-stream. O servidor manda o estado atual na hora (event: progress), manda de novo a cada mudança e fecha com event: done quando a tarefa termina. Uma linha : keepalive sai a cada 15 segundos para a conexão não cair. Tarefa que já terminou (ou que sobrou de um reinício) recebe só o done.

GET/api/v1/vendor/bulk-jobs/{id}/streamSeller

Progresso em tempo real (SSE)

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da tarefa (vem em job.id na resposta 202 da operação em lote).

Exemplo de requisição

bash

curl -N "$BASE_URL/api/v1/vendor/bulk-jobs/$JOB_ID/stream" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxo de eventos (`text/event-stream`)

json

event: progress
data: {"id":"7341b071-4e43-46fc-9470-19a04cb8d048","status":"running","total":87,"processed":40,"affected":38,"failed":2,"percent":45}

: keepalive

event: done
data: {"id":"7341b071-4e43-46fc-9470-19a04cb8d048","status":"done","total":87,"processed":87,"affected":85,"failed":2,"percent":100}

Eventos

eventstring

progressdone

progress enquanto a tarefa não terminou; done no último evento.

dataobject

O objeto da tarefa, com os mesmos campos de Consultar a tarefa.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
404	Tarefa inexistente, de outra loja ou iniciada por outro usuário.	`{"error":"bulk job not found"}`
500	O servidor não consegue fazer streaming (por exemplo, atrás de um proxy que armazena a resposta).	`{"error":"streaming not supported"}`

API atual/Referência completa/Ferramentas do catálogo do seller

Tarefas em lote

Consulta o estado de uma tarefa em lote do seller e acompanha o progresso em tempo real.

Consultar a tarefa

GET/api/v1/vendor/bulk-jobs/{id}Seller

Estado de uma tarefa em lote

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da tarefa (vem em job.id na resposta 202 da operação em lote).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Tarefa

json

{
  "id": "7341b071-4e43-46fc-9470-19a04cb8d048",
  "route": "POST /vendor/master-catalog/bulk-clone",
  "action": "clone",
  "description": "Clonar produtos do catálogo mestre para a loja do seller",
  "status": "running",
  "total": 87,
  "processed": 40,
  "affected": 38,
  "failed": 2,
  "percent": 45,
  "errors": [
    {
      "id": "6b5806fe-4370-4f12-bc95-a7dbba04918b",
      "error": "..."
    }
  ],
  "created_at": "2026-10-11T22:05:00Z",
  "started_at": "2026-10-11T22:05:01Z"
}

Campos da resposta

iduuid

Id da tarefa.

routestring

Rota que gerou a tarefa.

actionstring

Ação executada.

descriptionstring

Descrição para o usuário, em português.

statusstring

queuedrunningdonefailedinterrupted

Estado da tarefa.

totalinteger

Registros no recorte.

processedinteger

Registros já tratados.

affectedinteger

Registros alterados com sucesso.

failedinteger

Registros que falharam.

percentinteger

0 a 100.

errorsarray

Até 50 primeiras falhas (id, error). Ausente sem falhas.

resultobject

Dados extras da operação (por exemplo skipped). Ausente se não houver.

errorstring

Motivo, quando failed.

session_idstring

Conversa da Venddor Intelligence que iniciou a tarefa. Ausente se não foi por ela.

queue_positioninteger

Posição na fila da conversa, quando queued.

created_atstring

RFC 3339.

started_atstring

RFC 3339. Ausente enquanto na fila.

finished_atstring

RFC 3339. Ausente enquanto em andamento.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
404	Tarefa inexistente, de outra loja ou iniciada por outro usuário.	`{"error":"bulk job not found"}`

Acompanhar em tempo real

GET/api/v1/vendor/bulk-jobs/{id}/streamSeller

Progresso em tempo real (SSE)

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da tarefa (vem em job.id na resposta 202 da operação em lote).

Exemplo de requisição

bash

curl -N "$BASE_URL/api/v1/vendor/bulk-jobs/$JOB_ID/stream" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxo de eventos (`text/event-stream`)

json

event: progress
data: {"id":"7341b071-4e43-46fc-9470-19a04cb8d048","status":"running","total":87,"processed":40,"affected":38,"failed":2,"percent":45}

: keepalive

event: done
data: {"id":"7341b071-4e43-46fc-9470-19a04cb8d048","status":"done","total":87,"processed":87,"affected":85,"failed":2,"percent":100}

Eventos

eventstring

progressdone

progress enquanto a tarefa não terminou; done no último evento.

dataobject

O objeto da tarefa, com os mesmos campos de Consultar a tarefa.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
404	Tarefa inexistente, de outra loja ou iniciada por outro usuário.	`{"error":"bulk job not found"}`
500	O servidor não consegue fazer streaming (por exemplo, atrás de um proxy que armazena a resposta).	`{"error":"streaming not supported"}`