Listar produtos

Liste os produtos do seu catálogo com filtros (slug, categoria, nome, idioma, datas) e paginação. Use a lista paginada no dia a dia — para alimentar tabelas, telas administrativas ou buscas — e a lista completa (listall) quando precisar puxar o catálogo inteiro de uma vez, por exemplo para popular um seletor ou um cache local.

A API oferece duas formas de listar produtos, com formatos de resposta diferentes:

Ambos retornam uma projeção leve de cada produto (campos resumidos). Para o objeto completo — com variants, description, warrantyDays, etc. — use Consultar.

Como funciona

Os dois endpoints percorrem o mesmo catálogo e aceitam os mesmos filtros; a diferença está no formato da resposta e no teto de itens:

• GET /v1/products devolve um objeto paginado no nível raiz: offset, limit, total, hasMore, page (metadados de navegação) e data (o array de produtos). O limit vai de 1 a 100. É a forma recomendada para a maioria dos casos.
• GET /v1/products/listall devolve um array diretamente no nível raiz — sem offset/limit/total/data/page. Aceita um limit muito maior (até 999999), pensado para trazer o catálogo quase inteiro numa chamada só.

A lista paginada de produtos não inclui os blocos merchant nem _links (HATEOAS) que aparecem em outras listagens. E o listall, por ser um array puro, também não os inclui. Veja o padrão geral em Paginação.

Os filtros são aplicados pelo servidor antes da paginação, então total reflete a contagem após os filtros. Combine filtros (ex.: category + enabled) para refinar o resultado.

Quando usar (e quando NÃO usar)

• Use GET /v1/products para telas com paginação, busca por nome/slug, ou qualquer fluxo em que você navega página a página. É a opção segura para catálogos grandes.
• Use GET /v1/products/listall quando o catálogo é pequeno/médio e você precisa de tudo de uma vez (popular um <select>, sincronizar um cache, gerar um relatório simples). Evite-o em catálogos enormes: prefira a lista paginada para não trafegar megabytes numa só resposta.
• Para um produto específico com todos os detalhes (incluindo variantes), não liste — use Consultar.
• Para listar variantes, veja Variantes.

Requisição

Headers

Listagens são apenas leitura (GET) e não usam corpo nem X-Idempotency-Key.

Parâmetros de query

Os dois endpoints aceitam os mesmos filtros. A única diferença é o teto de limit.

Lista paginada

GET /v1/products

curl -X GET "https://api.selectwin.io/v1/products?limit=20&offset=0&enabled=true&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Filtrando por categoria e nome:

curl -X GET "https://api.selectwin.io/v1/products?category=saas&name=Premium" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta (200)

{
  "offset": 0,
  "limit": 20,
  "total": 5,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 }
  },
  "data": [
    {
      "id": "prd_01hqzvabc",
      "name": "Plano Premium",
      "slug": "plano-premium",
      "salesPage": "https://example.com/sales",
      "category": "saas",
      "salesQty": 42,
      "language": "pt-BR",
      "enabled": true,
      "images": ["https://example.com/img1.png"],
      "type": "digital",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ]
}

Campos do envelope de paginação:

Campos de cada item em data[] (projeção leve):

Lista completa (array direto)

GET /v1/products/listall

Retorna um array com os produtos, sem envelope de paginação. Aceita os mesmos filtros e ordenação, com limit de até 999999.

curl -X GET "https://api.selectwin.io/v1/products/listall?enabled=true&sort=ascending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta (200)

[
  {
    "id": "prd_01hqzvabc",
    "name": "Plano Premium",
    "slug": "plano-premium",
    "images": ["https://example.com/img1.png"],
    "salesPage": "https://example.com/sales",
    "salesQty": 42,
    "language": "pt-BR",
    "enabled": true,
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-12T17:56:33.000Z"
  }
]

Campos de cada item:

Erros

A API sinaliza falhas pelo error.code estável (não pela message). Para a estrutura do envelope de erro, veja Tratamento de Erros; para a lista completa, o Catálogo de Códigos de Erro.

Boas práticas

• Itere com page.offset.next/hasMore. Avance enquanto hasMore for true, usando o offset sugerido em page.offset.next em vez de calcular offsets na mão.
• Escolha o endpoint certo pelo volume. Catálogo pequeno e precisa de tudo: listall. Catálogo grande ou paginação na tela: GET /v1/products com limit ≤ 100.
• Filtre no servidor, não no cliente. Use category, enabled, name, slug e os daterange* para reduzir a resposta — é mais rápido e poupa rate limit.
• Trate os IDs como opacos. Armazene a string id inteira; não faça parsing do prefixo prd_. Veja Convenções.
• Não confie na projeção leve para detalhes. Se precisar de variants, description ou warrantyDays, busque o produto com Consultar.
• Respeite o rate limit ao varrer páginas. Em loops longos, adicione um pequeno intervalo entre as requisições e trate tooManyRequests com backoff.
• Use externalreference para correlacionar. Filtrar pela referência do seu sistema evita guardar o mapeamento de IDs internos.

Veja também

• Visão geral de Produtos — modelo do objeto e todas as operações
• Consultar produto — objeto completo com variantes
• Criar produto e Atualizar produto
• Variantes — listar e gerenciar variantes
• Paginação · Convenções · Autenticação