API atual/Referência completa/Moderação de produtos e sellers

Moderação em lote

Aprova ou recusa vários produtos de uma vez, por lista de ids ou por filtro com simulação e confirmação.

Quando a fila tem dezenas de produtos parecidos, decida todos de uma vez. Existem três rotas com o mesmo efeito de aprovar e recusar um produto, repetido para cada item: uma genérica (/bulk, com a ação no corpo) e duas dedicadas (/bulk-approve, /bulk-reject). Cada produto passa pelos mesmos efeitos da operação individual (aviso ao seller, reindexação, ligação ao catálogo mestre).

Há dois jeitos de dizer quais produtos:

Lista de ids, resposta imediata.
Filtro, em duas chamadas: primeiro você simula e recebe o total, uma amostra e um confirm_token; depois repete o mesmo corpo com o token para executar.

Aprovar ou recusar em lote (ação no corpo)

POST/api/v1/admin/moderation/bulkAdmin

Aprova ou recusa vários produtos

Corpo da requisição

product_idsarrayobrigatório

Ids (UUID) dos produtos. Obrigatório quando não há filter.

actionstringobrigatório

approvereject

O que fazer com todos.

reasonstring

Motivo. Obrigatório quando action é reject. Aceita também rejected_reason e notes.

filterobject

Escolhe os produtos por critério em vez de ids. Veja o filtro abaixo.

simulateboolean

true só calcula e devolve o total, a amostra e o confirm_token, sem alterar nada.

confirm_tokenstring

Token devolvido pela simulação. Obrigatório para executar um lote por filtro.

200Lote concluído (lista de ids)

json

{ "message": "bulk moderation complete", "action": "approve", "requested": 3, "updated": 2 }

Aprovar em lote

POST/api/v1/admin/moderation/bulk-approveAdmin

Aprova vários produtos, com resultado por id

Corpo da requisição

idsarrayobrigatório

Ids (UUID) dos produtos. Aceita product_ids como apelido antigo. Obrigatório quando não há filter.

filterobject

Critério em vez de ids (veja abaixo).

simulateboolean

Só simula.

confirm_tokenstring

Token da simulação, para executar por filtro.

Recusar em lote

POST/api/v1/admin/moderation/bulk-rejectAdmin

Recusa vários produtos, com resultado por id

Corpo da requisição

idsarrayobrigatório

Ids (UUID) dos produtos. Aceita product_ids. Obrigatório quando não há filter.

rejected_reasonstringobrigatório

Motivo, o mesmo para todos. Aceita também reason e notes. A checagem é feita antes de qualquer alteração.

filterobject

Critério em vez de ids (veja abaixo).

simulateboolean

Só simula.

confirm_tokenstring

Token da simulação, para executar por filtro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/moderation/bulk-reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d"], "rejected_reason": "Fotos fora do padrão."}'

Resposta

200Resultado por id

json

{
  "action": "reject",
  "requested": 2,
  "updated": 1,
  "results": [
    { "id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "status": "ok" },
    { "id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "status": "error", "error": "product not found: 0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d" }
  ]
}

Campos da resposta

actionstring

approvereject

Ação executada.

requestedinteger

Quantos ids você mandou.

updatedinteger

Quantos foram alterados.

resultsarray

Um item por id, na ordem enviada. Só em bulk-approve e bulk-reject.

results[].statusstring

okerror

Resultado daquele id.

results[].errorstring

Causa da falha, quando status é error.

O HTTP é 200 mesmo quando alguns itens falham. Confira updated e results.

Lote por filtro (simular e confirmar)

Para decidir "tudo o que casa com um critério" sem listar ids, mande filter no lugar da lista. O lote por filtro só alcança produtos que aguardam moderação (R) e nunca executa sem uma simulação antes.

Simule
Mande o corpo com filter e "simulate": true. A resposta traz total, uma sample, o confirm_token (válido por cerca de uma hora, veja expires_at) e async.
Mostre ao usuário
Confirme o total e a amostra com quem vai decidir.
Execute
Repita exatamente o mesmo corpo, sem simulate, com confirm_token. Se o recorte cresceu ou o corpo mudou, o token é recusado.

O filtro aceita chaves como name_contains, sku, sku_contains, brand, category_id, category_tree, vendor_id, price_min, price_max (preços em centavos), created_after, created_before, ids, exclude_ids e all (true para a tabela inteira). Uma chave desconhecida volta 400 invalid_filter listando as chaves aceitas, e um filtro vazio também é recusado.

200Simulação do lote por filtro

json

{
  "simulate": true,
  "action": "approve",
  "description": "Aprovar produtos em moderação",
  "total": 42,
  "sample": [],
  "confirm_token": "eyJ0IjoiZGZlMjU1NWUtYmZkMC00MWE4...",
  "expires_at": "2026-10-11T22:40:35Z",
  "async": false,
  "by": "filter"
}

Na execução por filtro o corpo da resposta tem action, by: "filter", total_requested, status, affected e failed (lista dos itens que falharam). Lotes grandes viram uma tarefa em segundo plano: a resposta é 202 com async: true e o objeto job.

Erros

Status	Quando	Corpo de exemplo
400	Lista vazia (`product_ids`/`ids` ausentes).	`{"error":"product_ids is required"}` em `/bulk`, `{"error":"ids is required"}` nas rotas dedicadas.
400	`action` inválida em `/bulk`.	`{"error":"action must be 'approve' or 'reject'"}`
400	Recusa sem motivo.	`{"error":"rejected_reason is required"}`
400	Filtro inválido ou vazio.	`{"error":"invalid_filter","detail":"..."}`
409	`confirm_token` de outro corpo, ou o recorte cresceu desde a simulação.	`{"error":"confirm_token_invalid","detail":"..."}`
428	Filtro executado sem simulação prévia.	`{"error":"simulate_required","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"product-moderation"}`

Veja também

API atual/Referência completa/Moderação de produtos e sellers

Moderação em lote

Aprova ou recusa vários produtos de uma vez, por lista de ids ou por filtro com simulação e confirmação.

Há dois jeitos de dizer quais produtos:

Lista de ids, resposta imediata.
Filtro, em duas chamadas: primeiro você simula e recebe o total, uma amostra e um confirm_token; depois repete o mesmo corpo com o token para executar.

Aprovar ou recusar em lote (ação no corpo)

POST/api/v1/admin/moderation/bulkAdmin

Aprova ou recusa vários produtos

Corpo da requisição

product_idsarrayobrigatório

Ids (UUID) dos produtos. Obrigatório quando não há filter.

actionstringobrigatório

approvereject

O que fazer com todos.

reasonstring

Motivo. Obrigatório quando action é reject. Aceita também rejected_reason e notes.

filterobject

Escolhe os produtos por critério em vez de ids. Veja o filtro abaixo.

simulateboolean

true só calcula e devolve o total, a amostra e o confirm_token, sem alterar nada.

confirm_tokenstring

Token devolvido pela simulação. Obrigatório para executar um lote por filtro.

200Lote concluído (lista de ids)

json

{ "message": "bulk moderation complete", "action": "approve", "requested": 3, "updated": 2 }

Aprovar em lote

POST/api/v1/admin/moderation/bulk-approveAdmin

Aprova vários produtos, com resultado por id

Corpo da requisição

idsarrayobrigatório

Ids (UUID) dos produtos. Aceita product_ids como apelido antigo. Obrigatório quando não há filter.

filterobject

Critério em vez de ids (veja abaixo).

simulateboolean

Só simula.

confirm_tokenstring

Token da simulação, para executar por filtro.

Recusar em lote

POST/api/v1/admin/moderation/bulk-rejectAdmin

Recusa vários produtos, com resultado por id

Corpo da requisição

idsarrayobrigatório

Ids (UUID) dos produtos. Aceita product_ids. Obrigatório quando não há filter.

rejected_reasonstringobrigatório

Motivo, o mesmo para todos. Aceita também reason e notes. A checagem é feita antes de qualquer alteração.

filterobject

Critério em vez de ids (veja abaixo).

simulateboolean

Só simula.

confirm_tokenstring

Token da simulação, para executar por filtro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/moderation/bulk-reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d"], "rejected_reason": "Fotos fora do padrão."}'

Resposta

200Resultado por id

json

{
  "action": "reject",
  "requested": 2,
  "updated": 1,
  "results": [
    { "id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "status": "ok" },
    { "id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d", "status": "error", "error": "product not found: 0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d" }
  ]
}

Campos da resposta

actionstring

approvereject

Ação executada.

requestedinteger

Quantos ids você mandou.

updatedinteger

Quantos foram alterados.

resultsarray

Um item por id, na ordem enviada. Só em bulk-approve e bulk-reject.

results[].statusstring

okerror

Resultado daquele id.

results[].errorstring

Causa da falha, quando status é error.

O HTTP é 200 mesmo quando alguns itens falham. Confira updated e results.

Lote por filtro (simular e confirmar)

Simule
Mande o corpo com filter e "simulate": true. A resposta traz total, uma sample, o confirm_token (válido por cerca de uma hora, veja expires_at) e async.
Mostre ao usuário
Confirme o total e a amostra com quem vai decidir.
Execute
Repita exatamente o mesmo corpo, sem simulate, com confirm_token. Se o recorte cresceu ou o corpo mudou, o token é recusado.

200Simulação do lote por filtro

json

{
  "simulate": true,
  "action": "approve",
  "description": "Aprovar produtos em moderação",
  "total": 42,
  "sample": [],
  "confirm_token": "eyJ0IjoiZGZlMjU1NWUtYmZkMC00MWE4...",
  "expires_at": "2026-10-11T22:40:35Z",
  "async": false,
  "by": "filter"
}

Erros

Status	Quando	Corpo de exemplo
400	Lista vazia (`product_ids`/`ids` ausentes).	`{"error":"product_ids is required"}` em `/bulk`, `{"error":"ids is required"}` nas rotas dedicadas.
400	`action` inválida em `/bulk`.	`{"error":"action must be 'approve' or 'reject'"}`
400	Recusa sem motivo.	`{"error":"rejected_reason is required"}`
400	Filtro inválido ou vazio.	`{"error":"invalid_filter","detail":"..."}`
409	`confirm_token` de outro corpo, ou o recorte cresceu desde a simulação.	`{"error":"confirm_token_invalid","detail":"..."}`
428	Filtro executado sem simulação prévia.	`{"error":"simulate_required","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"product-moderation"}`