Excluir categoria

Manda uma categoria vazia para a lixeira ou, com cascata, apaga de vez a categoria, as filhas e os produtos delas.

Use esta operação para remover uma categoria do catálogo. O comportamento depende do conteúdo dela e é a parte mais delicada desta seção, então leia a tabela antes de integrar.

Situação da categoria	Sem `cascade`	Com `cascade=true`
Vazia e sem filhas vivas	Vai para a lixeira (`status` `T`). Some das listas, mas pode ser restaurada em até 30 dias. Responde 204.	Apagada de vez, com todas as descendentes. Responde 204.
Com produtos	Recusa com `409 category_has_products` e informa quantos.	Apaga de vez a categoria, as filhas e todos os produtos ligados a elas.
Com filhas vivas	Recusa com `409 category_has_subcategories`.	Apaga de vez a subárvore inteira.

Produtos que já foram excluídos (soft delete) não contam como "produtos" para a recusa. "Filhas vivas" são as que não estão na lixeira.

DELETE/api/v1/admin/categories/{id}Admin

Exclui uma categoria

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

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Parâmetros de consulta

cascadestring

true

Com o valor exato true, apaga também as filhas e os produtos (veja o aviso acima).

recursivestring

true

Sinônimo antigo de cascade, mantido para clientes antigos. Prefira cascade.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Categoria removida

http

HTTP/1.1 204 No Content

409Categoria com filhas

json

{
  "category_id": "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "error": "category_has_subcategories",
  "subcat_count": 1
}

Campos do erro 409

errorstring

category_has_productscategory_has_subcategoriescategory_products_referenced

Motivo da recusa.

category_iduuid

A categoria que você tentou excluir.

product_countinteger

Só em category_has_products: quantos produtos estão ligados a ela.

subcat_countinteger

Só em category_has_subcategories: quantas filhas vivas ela tem.

constraintstring

Só em category_products_referenced (com cascade): o vínculo de outro registro que impede apagar os produtos.

Erros

Status	Quando	Corpo
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `manage_categories`	`{"error":"insufficient privileges","required":"manage_categories"}`
404	Categoria não existe	`{"error":"category not found","detail":"category not found"}`
409	Tem produtos, tem filhas vivas ou (com cascata) algum produto é referenciado por outro registro	veja acima
500	Falha interna, ou id que não é UUID nem slug existente	`{"error":"failed to delete category","detail":"..."}`

Veja também

Excluir categoria

Manda uma categoria vazia para a lixeira ou, com cascata, apaga de vez a categoria, as filhas e os produtos delas.

Use esta operação para remover uma categoria do catálogo. O comportamento depende do conteúdo dela e é a parte mais delicada desta seção, então leia a tabela antes de integrar.

Situação da categoria	Sem `cascade`	Com `cascade=true`
Vazia e sem filhas vivas	Vai para a lixeira (`status` `T`). Some das listas, mas pode ser restaurada em até 30 dias. Responde 204.	Apagada de vez, com todas as descendentes. Responde 204.
Com produtos	Recusa com `409 category_has_products` e informa quantos.	Apaga de vez a categoria, as filhas e todos os produtos ligados a elas.
Com filhas vivas	Recusa com `409 category_has_subcategories`.	Apaga de vez a subárvore inteira.

Produtos que já foram excluídos (soft delete) não contam como "produtos" para a recusa. "Filhas vivas" são as que não estão na lixeira.

DELETE/api/v1/admin/categories/{id}Admin

Exclui uma categoria

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

Parâmetros de caminho

iduuidobrigatório

Id da categoria.

Parâmetros de consulta

cascadestring

true

Com o valor exato true, apaga também as filhas e os produtos (veja o aviso acima).

recursivestring

true

Sinônimo antigo de cascade, mantido para clientes antigos. Prefira cascade.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/categories/b53fa6b9-a1a5-4862-9fac-cdc5585017c7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Categoria removida

http

HTTP/1.1 204 No Content

409Categoria com filhas

json

{
  "category_id": "b53fa6b9-a1a5-4862-9fac-cdc5585017c7",
  "error": "category_has_subcategories",
  "subcat_count": 1
}

Campos do erro 409

errorstring

category_has_productscategory_has_subcategoriescategory_products_referenced

Motivo da recusa.

category_iduuid

A categoria que você tentou excluir.

product_countinteger

Só em category_has_products: quantos produtos estão ligados a ela.

subcat_countinteger

Só em category_has_subcategories: quantas filhas vivas ela tem.

constraintstring

Só em category_products_referenced (com cascade): o vínculo de outro registro que impede apagar os produtos.

Erros

Status	Quando	Corpo
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `manage_categories`	`{"error":"insufficient privileges","required":"manage_categories"}`
404	Categoria não existe	`{"error":"category not found","detail":"category not found"}`
409	Tem produtos, tem filhas vivas ou (com cascata) algum produto é referenciado por outro registro	veja acima
500	Falha interna, ou id que não é UUID nem slug existente	`{"error":"failed to delete category","detail":"..."}`