VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Produtos

Categorias do produto

Lista as categorias em que um produto está e substitui o conjunto inteiro, definindo qual é a principal.

Um produto fica em uma categoria principal e, se quiser, em várias categorias adicionais. É a principal que define o caminho da URL e a trilha de navegação (Início / Casa / Cozinha / Caneca); as adicionais só fazem o produto aparecer também nas outras listagens. Esta página mostra como ler esse vínculo e como trocá-lo de uma vez, sem editar o produto inteiro.

Quando você só precisa trocar a categoria principal ao alterar o produto, o campo category_id do PUT basta, mas ele mantém a categoria antiga como adicional. Para tirar o produto de uma categoria, ou para definir várias de uma vez, use a rota PUT .../categories desta página: ela substitui o conjunto inteiro.

GET/api/v1/admin/products/{id}/categoriesAdmin

Categorias de um produto

Autenticação: Authorization: Bearer <token> de um usuário administrador com o privilégio view_catalog ou manage_catalog. Um produto que não existe devolve 200 com listas vazias.

Path parameters

iduuidobrigatório
UUID do produto.

Exemplo de requisição (leitura)

bash
curl "$BASE_URL/api/v1/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c/categories" \
  -H "Authorization: Bearer $TOKEN"

Resposta (leitura)

200Categorias do produto
json
{
  "categories": [
    {
      "id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "name": "Informática",
      "slug": "informatica",
      "description": "",
      "position": 0,
      "status": "A",
      "path": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "depth": 0,
      "product_count": 0,
      "created_at": "2026-06-29T02:33:02.245706Z",
      "updated_at": "2026-07-10T07:22:15.460489Z",
      "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "category": "Informática",
      "seo_name": "informatica",
      "timestamp": 1782700382,
      "updated_timestamp": 1783668135
    }
  ],
  "links": [
    {
      "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
      "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "position": 0,
      "is_primary": true
    }
  ],
  "total": 1
}

Campos da resposta

categoriesarray
As categorias do produto.
categories[].iduuid
Id da categoria. category_id repete o valor.
categories[].namestring
Nome da categoria. category repete o valor.
categories[].slugstring
Slug da URL. seo_name repete o valor.
categories[].descriptionstring
Descrição.
categories[].image_urlstring
Imagem da categoria. Ausente quando não há.
categories[].parent_iduuid
Categoria-pai. Ausente na raiz.
categories[].positioninteger
Posição entre as irmãs.
categories[].statusstring
ADH
Status da categoria: A ativa, D desativada, H oculta.
categories[].pathstring
Caminho de ids da raiz até a categoria.
categories[].depthinteger
Profundidade na árvore (0 = raiz).
categories[].product_countinteger
Número de produtos da categoria.
categories[].created_atstring
Criação, RFC 3339.
categories[].updated_atstring
Última alteração, RFC 3339.
categories[].timestampinteger
Criação em Unix timestamp (segundos).
categories[].updated_timestampinteger
Última alteração em Unix timestamp (segundos).
linksarray
Um item por categoria, com os dados do vínculo.
links[].product_iduuid
Produto.
links[].category_iduuid
Categoria.
links[].positioninteger
Posição do vínculo (a ordem em que foram gravadas).
links[].is_primaryboolean
true na categoria principal.
totalinteger
Quantidade de categorias.
PUT/api/v1/admin/products/{id}/categoriesAdmin

Substitui as categorias de um produto

Substitui todos os vínculos de categoria do produto pelos que você enviar, de forma atômica (tudo ou nada), e atualiza o category_id do produto para a principal. Autenticação: Authorization: Bearer <token> de um usuário com o privilégio manage_catalog. A resposta é a mesma da leitura, já com o novo conjunto.

Path parameters

iduuidobrigatório
UUID do produto.

Corpo da requisição

category_idsarrayobrigatório
Ids de todas as categorias do produto (pelo menos uma), incluindo a principal. Quem não estiver na lista deixa de ser vinculado.
primary_category_iduuidobrigatório
A categoria principal. Tem de estar em category_ids.

Exemplo de requisição (escrita)

bash
curl -X PUT "$BASE_URL/api/v1/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c/categories" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category_ids": [
      "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
      "345ac33e-4dcd-4d60-bedf-a2c2d47897d9"
    ],
    "primary_category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9"
  }'

Resposta (escrita)

200Categorias substituídas
json
{
  "categories": [
    { "id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9", "name": "Informática", "slug": "informatica", "position": 0, "status": "A", "path": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9", "depth": 0, "product_count": 0, "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9", "category": "Informática", "seo_name": "informatica" },
    { "id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "name": "Escritório", "slug": "escritorio", "position": 0, "status": "A", "path": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "depth": 0, "product_count": 0, "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "category": "Escritório", "seo_name": "escritorio" }
  ],
  "links": [
    { "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c", "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9", "position": 0, "is_primary": true },
    { "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c", "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "position": 1, "is_primary": false }
  ],
  "total": 2
}

Os campos da resposta são os da leitura, descritos acima (versão abreviada no exemplo).

Erros

StatusQuandoCorpo
400(PUT) category_ids vazio ou ausente{"error":"category_ids is required and must not be empty"}
400(PUT) primary_category_id ausente{"error":"primary_category_id is required"}
400(PUT) JSON inválido{"error":"invalid request body","detail":"..."}
401Sem credenciais, chave inválida ou token expirado{"error":"invalid or expired token"}
403Sem o privilégio (view_catalog/manage_catalog na leitura, manage_catalog na escrita){"error":"insufficient privileges","required":"manage_catalog"}
429Limite de requisições{"error":"rate limit exceeded","detail":"too many requests, please try again later"}
500(PUT) primary_category_id fora de category_ids; categoria ou produto inexistentes. Por limitação conhecida saem como 500 e não como 400/404{"error":"failed to set product categories","detail":"primary_category_id must be included in category_ids"}
500(GET) {id} que não é UUID{"error":"failed to get product categories","detail":"..."}
Quem não está na lista sai da categoria

O PUT não acrescenta: ele troca o conjunto. Para adicionar uma categoria sem perder as atuais, leia primeiro (GET), junte a nova à lista e envie tudo de volta. Se a lista vier sem a categoria atual, o produto deixa de aparecer nela.

Veja também

  • Alterar produto
  • Criar produto
  • Consultar produto
  • Lote, importação e exportação
Anterior
Excluir produto
Próxima
Clonar produto
Nesta página
  • Exemplo de requisição (leitura)
  • Resposta (leitura)
  • Exemplo de requisição (escrita)
  • Resposta (escrita)
  • Erros
  • Veja também