GETCategorias
Lista as categorias ativas da vitrine em uma árvore achatada e lê uma categoria pelo id.
Categorias organizam o catálogo (Moda, Roupas, Camisetas). A lista devolve todas as categorias ativas de uma vez, já com a contagem de produtos visíveis em cada uma; a árvore é reconstruída por você a partir de parent_id, path e depth. A leitura individual devolve uma categoria.
As credenciais aceitas estão na visão geral.
Listar categorias
/api/storefront/categoriesPúblicaListar categorias ativas
Não há paginação nem filtro: todas as categorias ativas vêm numa resposta só. per_page e page são ignorados.
Parâmetros de consulta
langstringIdioma dos nomes e descrições (
pt-BR, en, es). Também vale o cabeçalho Accept-Language. Sem tradução, vale o texto base.Ler uma categoria
/api/storefront/categories/{id}PúblicaLer uma categoria pelo id
Parâmetros de caminho
iduuidobrigatórioId da categoria. Texto que não seja UUID responde 404, não 400.
Parâmetros de consulta
langstringIdioma dos textos, como na lista.
Exemplo de requisição
bash
curl "$BASE_URL/api/storefront/categories?lang=en"
curl "$BASE_URL/api/storefront/categories/8fcaf422-1631-4282-b503-85cc57380649"Resposta
200Lista de categorias (reduzida a 1 item)
json
{
"total": 46,
"categories": [
{
"id": "8fcaf422-1631-4282-b503-85cc57380649",
"parent_id": "5239a365-7ca5-4fd3-8d8f-aea92b7dfe3a",
"name": "Camisetas",
"slug": "camisetas",
"description": "",
"image_url": "/uploads/dfe2555e/product/c61df92a/camiseta.png",
"position": 0,
"status": "A",
"path": "e3e86e8b-cbf2-4c65-9bab-12638af84e49/5239a365-7ca5-4fd3-8d8f-aea92b7dfe3a/8fcaf422-1631-4282-b503-85cc57380649",
"depth": 2,
"product_count": 159,
"created_at": "2026-06-29T02:33:02.245706Z",
"updated_at": "2026-07-10T07:22:15.460489Z"
}
]
}Campos da resposta
totalintegerQuantidade de categorias na lista.
categories[].iduuidId da categoria.
category_id repete o valor.categories[].parent_iduuid|nullCategoria pai. Ausente ou nulo na raiz.
categories[].namestringNome (no idioma pedido).
category repete o valor.categories[].slugstringParte da URL amigável.
seo_name repete o valor.categories[].descriptionstringDescrição, pode ser vazia.
categories[].image_urlstringImagem, caminho relativo ao domínio da loja. Pode faltar.
categories[].positionintegerOrdem entre irmãs.
categories[].statusstringSempre
A (as demais nem aparecem).categories[].pathstringIds da raiz até a categoria, separados por
/. Serve para montar a árvore.categories[].depthintegerNível na árvore:
0 é raiz.categories[].product_countintegerProdutos visíveis na categoria, respeitando as regras de preço zero e estoque da loja.
categories[].created_atstringCriação, em RFC 3339.
categories[].updated_atstringÚltima alteração, em RFC 3339.
A leitura individual devolve o mesmo objeto da lista, sem o envelope categories/total.
Erros
| Status | Quando | Corpo |
|---|---|---|
| 401 | Loja que exige login para navegar e chamada anônima | {"error": "shopping_requires_login", "message": "this storefront requires login to browse"} |
| 403 | Chave sfk_ sem o escopo storefront:read | {"error": "missing_scope", "required": "storefront:read"} |
| 404 | Categoria inexistente, não ativa, com ancestral oculto ou id que não é UUID | {"error": "category not found"} |
| 500 | Falha ao ler categorias | {"error": "failed to list categories", ...} |