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

Categorias

Lista as categorias ativas da vitrine em lista plana, em formato de menu ou em árvore, e consulta uma categoria pelo id.

As categorias organizam o catálogo em uma árvore: cada categoria pode ter uma categoria-pai (parent_id) e várias filhas. Estas cinco rotas leem a mesma árvore em formatos diferentes. Todas devolvem somente categorias ativas (A) cujos ancestrais também estão ativos, e todas aceitam ?lang= ou Accept-Language para traduzir nome e descrição.

RotaQuando usar
GET /categoriesLista plana completa, com contagens.
GET /categories/visibleA mesma lista, sem categorias vazias se a loja ativou "ocultar categorias vazias".
GET /categories/navO mesmo conteúdo de visible em formato leve, para menus. Cache de 60 s.
GET /categories/treeÁrvore aninhada (children).
GET /categories/{id}Uma categoria.

Em todas, product_count é a quantidade de produtos que o comprador veria naquela categoria, aplicando as mesmas regras da lista de produtos (ativo, com preço e com estoque, conforme as configurações da loja). A contagem de uma categoria-pai não soma as filhas (no exemplo, "Informática" tem 4 e a filha "Notebooks" tem 163).

Listar categorias

GET/api/v1/storefront/categoriesPública

Listar categorias ativas (lista plana)

Parâmetros de consulta

langstring
Idioma de name e description (pt-BR, en, es). Também vale Accept-Language. Sem tradução, o texto base.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/categories?lang=pt-BR"

Resposta

200Categorias retornadas (reduzido)
json
{
  "total": 14,
  "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": 305,
      "created_at": "2026-09-09T13:11:20.906519Z",
      "updated_at": "2026-09-09T13:11:20.906519Z"
    },
    {
      "id": "698ce279-0cd1-402f-805d-3364e7e9d793",
      "parent_id": "3d7099bc-8e0f-4c4d-a6b0-a48feb8c1344",
      "name": "Mesas",
      "slug": "mesas",
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/4214581e-ebd8-4890-ba23-8f8b07715d1c/ai_c41327806cb9452a8266fbfafd0795c0.png",
      "position": 0,
      "status": "A",
      "path": "795ac349-83c1-4bcc-a64a-3317bf84ab5e/3d7099bc-8e0f-4c4d-a6b0-a48feb8c1344/698ce279-0cd1-402f-805d-3364e7e9d793",
      "depth": 2,
      "product_count": 149
    }
  ]
}

Campos da resposta

categoriesarray
Categorias ativas, em lista plana.
totalinteger
Quantidade de itens da lista.
categories[].iduuid
Id da categoria. category_id é um apelido.
categories[].parent_iduuid
Categoria-pai. Omitido nas categorias de topo.
categories[].namestring
Nome no idioma pedido. category é um apelido.
categories[].slugstring
Slug para a URL. seo_name é um apelido. Slugs não servem como {id} nas rotas de categoria.
categories[].descriptionstring
Descrição. Pode conter HTML.
categories[].image_urlstring
Imagem da categoria. Omitido se não há. icon_url traz o ícone, quando existe.
categories[].seo_titlestring
Título SEO. Omitido se vazio, assim como seo_description e meta_keywords.
categories[].positioninteger
Ordem de exibição entre irmãs.
categories[].pathstring
Ids da raiz até esta categoria, separados por /.
categories[].depthinteger
Nível na árvore: 0 = topo.
categories[].product_countinteger
Produtos visíveis na categoria (veja acima).
categories[].created_atstring
Criação, RFC 3339 (UTC). updated_at é a última alteração; timestamp e updated_timestamp repetem em Unix.

Categorias visíveis

Igual à rota acima, mas respeita a configuração ocultar categorias vazias: se estiver ligada, saem as categorias sem produtos, exceto as que têm descendentes com produtos (o pai fica para manter o caminho). Use esta rota, e não /categories, para páginas e menus.

GET/api/v1/storefront/categories/visiblePública

Listar categorias visíveis (sem vazias)

Parâmetros de consulta

langstring
Idioma dos textos, como em /categories.

A resposta tem o mesmo formato de /categories (categories e total).

Menu de navegação

O mesmo conteúdo de /categories/visible, em um formato leve: sem descrição, SEO, datas nem apelidos. Ideal para menus, trilhos de categoria e para achar o id a partir de um slug (percorra a lista e compare slug). A resposta é cacheável por 60 segundos.

GET/api/v1/storefront/categories/navPública

Menu de categorias em formato leve

Parâmetros de consulta

langstring
Idioma dos textos, como em /categories.
200Menu retornado (reduzido)
json
{
  "total": 14,
  "categories": [
    { "id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "name": "Escritório", "slug": "escritorio", "product_count": 305, "status": "A", "position": 0 },
    {
      "id": "698ce279-0cd1-402f-805d-3364e7e9d793",
      "parent_id": "3d7099bc-8e0f-4c4d-a6b0-a48feb8c1344",
      "name": "Mesas",
      "slug": "mesas",
      "image_url": "/uploads/dfe2555e-bfd0-41a8-9fa1-9586999f3798/product/4214581e-ebd8-4890-ba23-8f8b07715d1c/ai_c41327806cb9452a8266fbfafd0795c0.png",
      "product_count": 149,
      "status": "A",
      "position": 0
    }
  ]
}

Campos da resposta

categories[].iduuid
Id da categoria.
categories[].parent_iduuid
Categoria-pai. Omitido no topo.
categories[].namestring
Nome no idioma pedido.
categories[].slugstring
Slug.
categories[].image_urlstring
Imagem. Omitido se não há.
categories[].product_countinteger
Produtos visíveis.
categories[].statusstring
Sempre A aqui.
categories[].positioninteger
Ordem entre irmãs.

Árvore de categorias

Devolve as categorias já aninhadas: cada nó tem children. Só os nós de topo ficam no array tree. Se a loja ocultar categorias vazias, nós sem produtos e sem filhos com produtos são removidos.

GET/api/v1/storefront/categories/treePública

Árvore aninhada de categorias

Parâmetros de consulta

vendor_stockstring
1
Com 1, a contagem de cada categoria considera apenas ofertas de vendedores com estoque. Outro valor é ignorado.
200Árvore retornada (reduzida)
json
{
  "total": 2,
  "tree": [
    {
      "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": 4,
      "children": [
        {
          "id": "ae6f8f8b-7cbe-4725-84fa-247cce138143",
          "parent_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
          "name": "Notebooks",
          "slug": "notebooks",
          "position": 0,
          "status": "A",
          "path": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9/ae6f8f8b-7cbe-4725-84fa-247cce138143",
          "depth": 1,
          "product_count": 163
        }
      ]
    }
  ]
}

Campos da resposta

treearray
Categorias de topo, cada uma com children (mesmos campos de uma categoria, recursivo). children é omitido nas folhas.
totalinteger
Quantidade de nós de topo, não de todas as categorias.

Consultar uma categoria

GET/api/v1/storefront/categories/{id}Pública

Consultar uma categoria

Parâmetros de caminho

iduuidobrigatório
Id da categoria. Só UUID: um slug ou texto qualquer responde 404.

Parâmetros de consulta

langstring
Idioma dos textos, como em /categories.
200Categoria retornada
json
{
  "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": 1,
  "created_at": "2026-09-09T13:11:20.906519Z",
  "updated_at": "2026-09-09T13:11:20.906519Z"
}

A resposta é o objeto da categoria, com os mesmos campos descritos em "Listar categorias".

Erros

StatusQuandoExemplo de corpo
401A loja exige login para navegar e a requisição é anônima{"error":"shopping_requires_login","message":"this storefront requires login to browse"}
403Chave de API sem o escopo storefront:read{"error":"missing_scope","required":"storefront:read"}
404{id} não é um UUID, a categoria não existe, está desativada/oculta ou tem um ancestral inativo{"error":"category not found"}
500Falha ao consultar{"error":"failed to list categories","detail":"..."}
product_count de uma categoria sozinha pode divergir

Em GET /categories/{id}, product_count pode diferir do valor das listas (no exemplo, 1 contra 305). Para exibir contagens, use /categories/visible, /categories/nav ou /categories/tree.

Do slug ao id

As listas trazem slug e id. Guarde o mapa slug para id no seu cliente (o menu /categories/nav é leve e cacheável) para resolver uma URL de categoria, e passe o id para category_id em Listar produtos.

Veja também

  • Listar produtos
  • Filtros da categoria
  • Visão geral do catálogo
Anterior
Consultas rápidas de produto
Próxima
Filtros de categoria
Nesta página
  • Listar categorias
  • Exemplo de requisição
  • Resposta
  • Categorias visíveis
  • Menu de navegação
  • Árvore de categorias
  • Consultar uma categoria
  • Erros
  • Veja também