POSTAções em lote

Muda o status, move para outra mãe ou exclui até 100 categorias em uma única chamada.

Use esta operação para mexer em muitas categorias de uma vez: desativar uma linha inteira antes de uma troca de catálogo, mover um grupo de categorias para baixo de outra ou limpar categorias vazias. Em vez de 100 chamadas de Alterar categoria, você faz uma.

O lote é parcial: ele processa uma categoria por vez, e as que falham (por exemplo, uma categoria com produtos num delete) entram em failed sem impedir as outras. Confira sempre affected e failed na resposta.

POST/api/v1/admin/categories/bulkAdmin

Ação em lote nas categorias

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio manage_categories.

Corpo da requisição

category_idsarrayobrigatório

Ids (UUID) das categorias. De 1 a 100 itens.

actionstringobrigatório

update_statusmove_parentdelete

A ação a aplicar a todas.

statusstring

AHD

Obrigatório em update_status. Novo status, em letra (A, H, D) ou por nome (active, enabled, visible, hidden, disabled, inactive). A lixeira (T) não é aceita aqui. Categorias que já estão na lixeira nunca são alteradas.

parent_idstring

Usado em move_parent: UUID da nova mãe. Se omitido ou vazio, as categorias vão para o topo da árvore.

filterobject

Modo avançado: em vez de listar ids, descreve o recorte e o servidor resolve quais categorias entram. Exige simulate e confirm_token abaixo. Para integrações simples, use category_ids.

simulateboolean

Com true, nada é alterado: a resposta traz a contagem, uma amostra do antes e depois e um confirm_token.

confirm_tokenstring

Token devolvido pela simulação. Com filter, a execução real só roda com ele.

O que cada ação faz

`action`	Efeito	Falha por categoria quando
`update_status`	Define o status. Uma única atualização para todas as categorias do lote.	Não há falha por item: ids inexistentes ou na lixeira simplesmente não são contados em `affected`.
`move_parent`	Move cada categoria para a nova mãe, uma a uma, com as mesmas regras de Alterar categoria (sem ciclo, profundidade máxima 5, nome não repetido).	A categoria viola alguma regra: o id entra em `failed`. Uma mãe inexistente ou na lixeira recusa o lote inteiro com erro 500.
`delete`	Exclui sem cascata: cada categoria vazia vai para a lixeira.	A categoria tem produtos ou filhas vivas: o id entra em `failed`.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/categories/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_ids": [
      "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
      "b854c1fa-3318-408d-baa7-343de4fbce09"
    ],
    "action": "update_status",
    "status": "D"
  }'

Resposta

200Lote processado

json

{
  "action": "update_status",
  "affected": 1,
  "failed": null,
  "message": "Updated 1 categories to status \"H\"",
  "message_code": "categories.bulk.status_updated"
}

Campos da resposta

actionstring

A ação executada.

affectedinteger

Quantas categorias foram alteradas, movidas ou excluídas.

failedarray

Ids que não puderam ser processados (move_parent e delete). null quando nenhum falhou.

messagestring

Resumo em inglês, para log. Não use para decidir nada.

message_codestring

categories.bulk.status_updatedcategories.bulk.movedcategories.bulk.deleted

Código estável do resultado, próprio para tradução.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body","detail":"..."}`
400	`category_ids` vazio	`{"error":"category_ids is required and must not be empty"}`
400	Mais de 100 ids	`{"error":"maximum 100 categories per bulk action"}`
400	Sem `action`	`{"error":"action is required"}`
400	`action` desconhecida	`{"error":"invalid action","detail":"action must be one of: update_status, move_parent, delete"}`
400	`update_status` sem `status`	`{"error":"status is required for update_status action"}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_categories`	`{"error":"insufficient privileges","required":"manage_categories"}`
500	`status` desconhecido, mãe de destino inexistente ou falha interna	`{"error":"failed to bulk update category status","detail":"invalid status: X (must be active, hidden, or disabled)"}`

Veja também