Pular para o conteúdo principal
GET
List products by category

📌 Endpoint

GET /stores/{storeId}/categories/{categoryId}/products Retorna os produtos públicos (não desabilitados) que pertencem a uma categoria de uma loja. Os produtos são retornados na ordem de position (ascendente).

🔐 Autenticação

  • Rota pública para consulta.
  • A loja precisa existir e 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á produtos na categoria, o modo offset (sem cursor) retorna 404 PRODUCTS_NOT_FOUND, enquanto o modo cursor retorna 200 com products: [], 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 PRODUCTS_NOT_FOUND → nenhum produto encontrado para a categoria (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
categoryId
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 products by category.

code
string
obrigatório
Exemplo:

"PRODUCTS_BY_CATEGORY_FETCHED"

products
object[]
obrigatório
pagination
object
obrigatório