Pular para o conteúdo principal
GET
List categories

📌 Endpoint

GET /stores/{storeId}/categories Retorna todas as categorias de uma loja. As categorias são retornadas na ordem de position (ascendente), ideal para montar menu/listagem no frontend.

🔐 Autenticação

  • Rota pública para consulta.
  • A loja vinculada ao storeId precisa estar com plano ativo.

🧾 Parâmetros de rota


✅ Exemplo de requisição


🔎 Query params


🔄 Paginação por cursor

Para listas grandes (mais de ~100 itens), prefira paginação por cursor no lugar de page:
  1. Faça a primeira chamada sem cursor.
  2. Se hasMore for true, a resposta traz o campo nextCursor.
  3. Envie esse nextCursor no parâmetro cursor da próxima requisição para buscar a página seguinte.
No modo cursor, a paginação é retornada apenas com nextCursor, hasMore e limit:
  • cursor e page não podem ser usados juntos (400 INVALID_PAGINATION).
  • Quando não há categorias, o modo offset (sem cursor) retorna 404 CATEGORIES_NOT_FOUND, enquanto o modo cursor retorna 200 com categories: [], nextCursor: null e hasMore: false.
  • nextCursor: null com hasMore: false indicam o fim da lista (a API responde 200 com array vazio).

📦 Resposta de sucesso (200)

A primeira chamada (sem cursor) já retorna nextCursor e hasMore na paginação, permitindo iniciar a paginação por cursor sem chamadas extras.

⚠️ Possíveis erros

  • 400 INVALID_DATA → parâmetro inválido
  • 400 INVALID_PAGINATION_LIMIT → limit fora do intervalo permitido (1 a 100)
  • 400 INVALID_PAGINATION_PAGE → page inválida
  • 400 INVALID_PAGINATION_CURSOR → cursor inválido ou malformado
  • 400 INVALID_PAGINATION → page e cursor utilizados juntos
  • 401 UNAUTHENTICATED → não foi possível identificar o usuário da assinatura
  • 403 NO_ACTIVE_SUBSCRIPTION → plano inativo ou expirado
  • 404 STORE_NOT_FOUND → loja não encontrada
  • 404 CATEGORIES_NOT_FOUND → nenhuma categoria encontrada (retornado apenas no modo offset quando total é 0; no modo cursor retorna 200 com [])
  • 429 RATE_LIMIT_EXCEEDED → limite de requisições por minuto excedido
  • 500 INTERNAL_SERVER_ERROR → erro interno
  • 503 SERVICE_UNAVAILABLE → serviço ou banco de dados indisponível

Parâmetros de caminho

storeId
string
obrigatório
Required string length: 1 - 50

Parâmetros de consulta

page
integer
padrão:1
Intervalo obrigatório: x >= 1
limit
integer
padrão:20
Intervalo obrigatório: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page).

Resposta

List categories.

code
string
obrigatório
Exemplo:

"CATEGORIES_FETCHED"

categories
object[]
obrigatório
pagination
object
obrigatório