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

Listar categorias

Retorna as categorias da loja em lista plana, com todas as categorias de uma vez, ou em árvore já aninhada.

Use esta operação para ler o catálogo de categorias: carregar a árvore em um PIM, montar o menu de outro canal ou conferir se uma categoria já existe antes de criá-la. A lista não inclui categorias na lixeira (T), mas inclui as ativas, desativadas e ocultas.

Há duas leituras: a lista plana com todas as categorias de uma vez (sem paginação) e a árvore já aninhada.

GET/api/v1/admin/categoriesAdmin

Lista todas as categorias

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_catalog, manage_catalog ou manage_categories. Devolve todas as categorias vivas em uma única resposta, sem paginação.

Parâmetros de consulta

langstring
Código do idioma (pt-BR, en...). Quando enviado, name, description e os campos de SEO vêm no idioma pedido. Sem ele, valem os textos padrão da loja.
GET/api/v1/admin/categories/treeAdmin

Category tree

A mesma coleção, já aninhada: cada categoria de topo traz as filhas em children, e assim por diante. Inclui categorias em qualquer status, exceto a lixeira. Não tem parâmetros.

Exemplo de requisição

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

Resposta

200Lista plana
json
{
  "categories": [
    {
      "id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
      "name": "Escritório",
      "slug": "escritorio",
      "description": "",
      "position": 0,
      "status": "A",
      "path": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
      "depth": 0,
      "product_count": 303,
      "created_at": "2026-09-09T13:11:20.906519Z",
      "updated_at": "2026-09-09T13:11:20.906519Z",
      "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
      "category": "Escritório",
      "seo_name": "escritorio",
      "timestamp": 1788959480,
      "updated_timestamp": 1788959480
    }
  ],
  "total": 47
}
200Árvore
json
{
  "tree": [
    {
      "id": "e3e86e8b-cbf2-4c65-9bab-12638af84e49",
      "name": "Moda",
      "slug": "moda",
      "position": 0,
      "status": "A",
      "path": "e3e86e8b-cbf2-4c65-9bab-12638af84e49",
      "depth": 0,
      "product_count": 0,
      "children": [
        {
          "id": "5239a365-7ca5-4fd3-8d8f-aea92b7dfe3a",
          "parent_id": "e3e86e8b-cbf2-4c65-9bab-12638af84e49",
          "name": "Roupas",
          "slug": "roupas",
          "position": 0,
          "status": "A",
          "path": "e3e86e8b-cbf2-4c65-9bab-12638af84e49/5239a365-7ca5-4fd3-8d8f-aea92b7dfe3a",
          "depth": 1,
          "product_count": 0
        }
      ]
    }
  ],
  "total": 15
}

Campos da resposta

categoriesarray
Lista plana, na lista; na árvore o campo se chama tree.
categories[].iduuid
Id da categoria. Os campos category_id repetem o mesmo valor.
categories[].parent_iduuid
Id da mãe. Ausente nas categorias de topo.
categories[].namestring
Nome (no idioma pedido em lang, quando enviado).
categories[].slugstring
Endereço da página, único na loja.
categories[].descriptionstring
Descrição, pode conter HTML.
categories[].image_urlstring
Imagem da categoria. Ausente quando não há.
categories[].icon_urlstring
Ícone da categoria. Ausente quando não há.
categories[].seo_titlestring
Título de SEO. Ausente quando não definido.
categories[].seo_descriptionstring
Descrição de SEO. Ausente quando não definida.
categories[].meta_keywordsstring
Palavras-chave de SEO. Ausente quando não definido.
categories[].positioninteger
Posição entre as irmãs.
categories[].statusstring
ADH
Letra do status. A lixeira (T) não aparece na lista; ela só é vista ao consultar a categoria por id.
categories[].pathstring
Cadeia de ids da raiz até a categoria, separados por /.
categories[].depthinteger
Profundidade: 0 para topo, até 5.
categories[].product_countinteger
Contagem de produtos pelas regras de visibilidade da loja.
categories[].childrenarray
Somente na árvore: as categorias filhas, com o mesmo formato.
categories[].usergroup_idsarray
Quando preenchido, só os grupos de clientes listados enxergam a categoria na loja. Ausente quando a categoria é visível para todos.
categories[].whatsapp_hiddenboolean
true quando a categoria e seus produtos ficam fora do catálogo do WhatsApp. Ausente quando false.
categories[].look_tryon_enabledboolean
true quando a prova virtual de look está ligada nos produtos da categoria. Ausente quando false.
categories[].created_atstring
Criação, RFC 3339 em UTC.
categories[].updated_atstring
Última alteração, RFC 3339 em UTC.
categories[].lang_codestring
Idioma dos textos, quando a leitura usou lang.
totalinteger
Na lista plana, o número de categorias; na árvore, o número de categorias de topo.

Erros

StatusQuandoCorpo
401Sem credenciais, chave inválida ou token expirado{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403Usuário sem o privilégio de catálogo{"error":"insufficient privileges","privilege_required_any":["manage_categories","view_catalog","manage_catalog"]}
429Limite de requisições (por exemplo, login repetido){"error":"rate limit exceeded","detail":"too many requests, please try again later"}
500Falha interna{"error":"failed to list categories","detail":"..."}

Veja também

  • Consultar categoria
  • Criar categoria
  • Listar produtos
  • Ações em lote
Anterior
Categorias
Próxima
Consultar categoria
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também