VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Categorias do seller

Categorias próprias

Lista, cria, altera e exclui as categorias que pertencem ao próprio seller, em árvore de até 6 níveis.

Com categorias próprias o seller monta a vitrine da sua loja no marketplace sem depender do administrador: crie a categoria e use o id dela em category_id ao criar produtos.

Listar

GET/api/v1/vendor/categories/ownSeller

Listar as categorias próprias

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição (listar)

bash
curl "$BASE_URL/api/v1/vendor/categories/own" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Categorias
json
{
  "categories": [
    {
      "id": "5e4d3c2b-0001-4a1b-9c2d-3e4f5a6b7c8d",
      "parent_id": null,
      "name": "Camisetas",
      "slug": "camisetas",
      "description": "Camisetas básicas e estampadas",
      "image_url": null,
      "position": 0,
      "status": "A",
      "path": "5e4d3c2b-0001-4a1b-9c2d-3e4f5a6b7c8d",
      "depth": 0,
      "product_count": 12,
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

categoriesarray

Lista plana, ordenada pelo caminho da árvore e pela posição. Use parent_id e depth para montar a árvore.

idstring (uuid)
Id da categoria.
parent_idstring (uuid) | null
Categoria pai; ausente na raiz.
namestring
Nome.
slugstring
Trecho da URL, único entre as categorias.
descriptionstring
Descrição.
image_urlstring | null
Imagem da categoria.
positioninteger
Ordem entre as irmãs.
statusstring
AHDT
Status em letra.
pathstring
Ids dos ancestrais e o próprio id, separados por /.
depthinteger
Nível: 0 na raiz, até 5.
product_countinteger
Produtos ativos (A) ou pendentes (R) da categoria.
whatsapp_hiddenboolean
Escondida do catálogo do WhatsApp.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).
totalinteger
Quantidade.

Erros (listar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404Usuário sem cadastro de seller.{"error":"vendor profile not found"}

Criar

POST/api/v1/vendor/categoriesSeller

Criar uma categoria própria

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

namestringobrigatório
Nome. Não pode repetir sob o mesmo pai.
slugstring
Trecho da URL. Se vazio, nasce do nome. Se já existir, ganha -2, -3...
parent_idstring (uuid)
Categoria pai, que precisa ser sua. Omita para criar na raiz.
descriptionstring
Descrição.
image_urlstring
Imagem.
icon_urlstring
Ícone.
positionintegerpadrão: 0
Ordem entre as irmãs.
statusstringpadrão: A
AHDT
Status inicial.
seo_titlestring
Título SEO.
seo_descriptionstring
Descrição SEO.
meta_keywordsstring
Palavras-chave.
whatsapp_hiddenboolean
Esconde do catálogo do WhatsApp.
descriptionsobject
Conteúdo por idioma (pt-BR, en...).

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/categories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Camisetas",
  "description": "Camisetas básicas e estampadas",
  "position": 0,
  "status": "A"
}'

Resposta (criar)

201Categoria criada
json
{
  "id": "5e4d3c2b-0001-4a1b-9c2d-3e4f5a6b7c8d",
  "parent_id": null,
  "name": "Camisetas",
  "slug": "camisetas",
  "description": "Camisetas básicas e estampadas",
  "image_url": null,
  "position": 0,
  "status": "A",
  "path": "5e4d3c2b-0001-4a1b-9c2d-3e4f5a6b7c8d",
  "depth": 0,
  "product_count": 12,
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z"
}

Campos da resposta

idstring (uuid)
Id da categoria.
parent_idstring (uuid) | null
Categoria pai; ausente na raiz.
namestring
Nome.
slugstring
Trecho da URL, único entre as categorias.
descriptionstring
Descrição.
image_urlstring | null
Imagem da categoria.
positioninteger
Ordem entre as irmãs.
statusstring
AHDT
Status em letra.
pathstring
Ids dos ancestrais e o próprio id, separados por /.
depthinteger
Nível: 0 na raiz, até 5.
product_countinteger
Produtos ativos (A) ou pendentes (R) da categoria.
whatsapp_hiddenboolean
Escondida do catálogo do WhatsApp.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (criar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
400name ausente.{"error":"name is required"}
404parent_id não é uma categoria sua.{"error":"parent category not found"}
500Nome repetido sob o mesmo pai, mais de 6 níveis, ou pai inexistente.{"error":"failed to create category","detail":"category name \"Camisetas\" already exists under this parent (id ...)"}

Alterar

PUT/api/v1/vendor/categories/{categoryId}Seller

Alterar uma categoria própria

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

categoryIdstring (uuid)obrigatório
Id da categoria.

Corpo da requisição

namestring
Novo nome.
slugstring
Novo slug.
descriptionstring
Descrição.
parent_idstring (uuid)
Novo pai (precisa ser seu). "" move para a raiz.
image_urlstring
Imagem.
icon_urlstring
Ícone.
positioninteger
Ordem.
statusstring
AHDT
Status.
seo_titlestring
Título SEO.
seo_descriptionstring
Descrição SEO.
meta_keywordsstring
Palavras-chave.
usergroup_idsarray of string
Grupos de clientes que veem a categoria. Lista vazia = todos; ausente não mexe.
whatsapp_hiddenboolean
Esconde do catálogo do WhatsApp.
look_tryon_enabledboolean
Liga o provador virtual de looks nos produtos desta categoria.
descriptionsobject
Conteúdo por idioma; só os idiomas enviados mudam.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/categories/$CATEGORY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Camisetas básicas, lisas e estampadas",
  "position": 1
}'

Resposta (alterar)

200Categoria alterada
json
{
  "id": "5e4d3c2b-0001-4a1b-9c2d-3e4f5a6b7c8d",
  "parent_id": null,
  "name": "Camisetas",
  "slug": "camisetas",
  "description": "Camisetas básicas e estampadas",
  "image_url": null,
  "position": 1,
  "status": "A",
  "path": "5e4d3c2b-0001-4a1b-9c2d-3e4f5a6b7c8d",
  "depth": 0,
  "product_count": 12,
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z"
}

Campos da resposta

idstring (uuid)
Id da categoria.
parent_idstring (uuid) | null
Categoria pai; ausente na raiz.
namestring
Nome.
slugstring
Trecho da URL, único entre as categorias.
descriptionstring
Descrição.
image_urlstring | null
Imagem da categoria.
positioninteger
Ordem entre as irmãs.
statusstring
AHDT
Status em letra.
pathstring
Ids dos ancestrais e o próprio id, separados por /.
depthinteger
Nível: 0 na raiz, até 5.
product_countinteger
Produtos ativos (A) ou pendentes (R) da categoria.
whatsapp_hiddenboolean
Escondida do catálogo do WhatsApp.
created_atstring
Criação (RFC 3339).
updated_atstring
Última alteração (RFC 3339).

Erros (alterar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404A categoria não existe ou não é sua (o pai também).{"error":"category not found"}
500Nome repetido, ciclo na árvore, mais de 6 níveis ou outra regra da árvore.{"error":"failed to update category","detail":"..."}

Excluir

DELETE/api/v1/vendor/categories/{categoryId}Seller

Excluir uma categoria própria

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

categoryIdstring (uuid)obrigatório
Id da categoria.

Parâmetros de consulta

cascadebooleanpadrão: false
true apaga também as subcategorias e os produtos delas. recursive=true é um apelido.

Exemplo de requisição (excluir)

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/categories/$CATEGORY_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (excluir)

200Categoria excluída
json
{
  "message": "category deleted"
}

Campos da resposta

messagestring
Confirmação fixa.

Erros (excluir)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings"]}
404A categoria não existe ou não é sua (o pai também).{"error":"category not found"}
409A categoria tem produtos.{"error":"category_has_products","product_count":3,"category_id":"..."}
409A categoria tem subcategorias.{"error":"category_has_subcategories","subcat_count":2,"category_id":"..."}
cascade apaga produtos

Com ?cascade=true, a categoria, as subcategorias e todos os produtos que estão nelas saem do ar. Sem cascade, a plataforma responde 409 e não apaga nada, que é o comportamento seguro: mova ou apague os produtos antes.

Contagem de produtos

product_count conta produtos A (ativos) e R (pendentes) do próprio seller, para que um produto recém-criado e ainda em moderação não apareça como "0 produtos".

Veja também

  • Categorias do seller: visão geral
Anterior
Categorias do seller
Próxima
Categorias liberadas
Nesta página
  • Listar
  • Exemplo de requisição (listar)
  • Resposta (listar)
  • Erros (listar)
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Excluir
  • Exemplo de requisição (excluir)
  • Resposta (excluir)
  • Erros (excluir)
  • Veja também