Consultar um produto

Busca um produto do catálogo pelo seu ID e devolve a representação completa, incluindo todas as variantes embutidas com seus preços (pricing). Use quando precisar exibir o produto num checkout, painel administrativo ou integração, ou simplesmente confirmar como ele está configurado.

GET /v1/products/{productId}

Como funciona

A leitura é uma operação somente de leitura (idempotente, sem efeitos colaterais): você informa o productId no caminho da URL e a API devolve o objeto inteiro daquele produto. Diferente de uma listagem — que retorna uma projeção leve de cada item —, a leitura individual entrega a representação completa, com campos que não aparecem na lista.

O que vem embutido:

• Dados do produto: name, description, type, category, slug, language, warrantyDays, images, enabled, externalReference e os timestamps.
• Variantes (variants[]): cada variante traz seu pricing (preço unitário, moeda, recorrência, trial, ciclos…), além de sku, metadata, attributes, images e timestamps próprios.

Quando usar

• Carregar a página de um produto (checkout, vitrine, painel) com todas as suas variantes de uma vez.
• Conferir a configuração atual antes de um Update (por exemplo, ver o warrantyDays ou o pricing vigente).
• Resolver um productId recebido de outro recurso (uma transação, uma assinatura) para mostrar nome, imagens e preço.

Quando não usar:

• Para descobrir/buscar produtos por nome, slug, categoria ou data, ou paginar o catálogo — use Listar.
• Para ler uma variante específica com costPerItem e productId — use Variantes (GET /v1/variants/{variantId}).

Requisição

Headers

Por ser um GET, não há corpo nem Content-Type. A autenticação é sempre via header SelectKey — nunca Authorization: Bearer/Basic.

Parâmetros de caminho

Este endpoint não aceita parâmetros de query.

Exemplo curl

curl -X GET "https://api.selectwin.io/v1/products/prd_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

200 OK — o corpo é o objeto completo do produto.

{
  "id": "prd_01hqzvabc",
  "enabled": true,
  "name": "Plano Premium",
  "description": "Full access plan",
  "type": "digital",
  "language": "pt-BR",
  "category": "saas",
  "slug": "plano-premium",
  "images": ["https://cdn.selectwin.io/p/img1.png"],
  "warrantyDays": 30,
  "variants": [
    {
      "id": "var_01hqzvabc",
      "name": "Mensal",
      "enabled": true,
      "description": "Monthly billing",
      "sku": "SKU-M",
      "pricing": {
        "oldPrice": 14900,
        "unitPrice": 9900,
        "currency": "BRL",
        "schema": "unit",
        "type": "recurring",
        "daysTrial": 7,
        "billingType": "prepaid",
        "billingFrequency": "monthly",
        "billingFrequencyCount": 1,
        "billingExactDay": 10,
        "cycles": 12,
        "trialInterval": "day",
        "trialIntervalCount": 7
      },
      "images": ["https://cdn.selectwin.io/v/var.png"],
      "metadata": { "tier": "pro" },
      "externalReference": "VAR-EXT-1",
      "attributes": {},
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "externalReference": "PROD-EXT-1",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Campos do produto

Campos de cada variante (variants[])

Campos de pricing

Todos os valores monetários são inteiros em centavos (9900 = R$ 99,00). Veja Convenções.

Erros

A API sinaliza falhas com um envelope padrão; trate sempre pelo error.code, não pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Exemplo de resposta 404:

{
  "error": {
    "code": "productIdNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Product not found"
  }
}

Boas práticas

• Trate o productId como opaco. Armazene a string inteira; não confie no comprimento nem construa IDs manualmente.
• Distinga 400 de 404. productIdIsInvalid (400) indica um ID malformado (provável bug no seu código); productIdNotFound (404) indica um produto que não existe (pode ter sido removido). Trate-os de forma diferente.
• Para custo e margem, leia a variante individual. pricing.costPerItem e productId não vêm embutidos aqui; use GET /v1/variants/{variantId} (veja Variantes).
• Sempre converta dinheiro dividindo por 100 só na exibição. Os valores chegam em centavos; nunca use ponto flutuante para cálculos monetários.
• Mostre apenas o que está enabled. Tanto o produto quanto cada variante têm o flag enabled; respeite-o em vitrines e checkouts.
• Não fique repetindo GET para detectar mudanças (polling). Para reagir a alterações de catálogo ou de assinatura, prefira Webhook Events.

Veja também

• Visão geral de Produtos — modelo do objeto, ciclo de vida e todas as operações.
• Listar produtos — buscar e paginar o catálogo (projeção leve).
• Criar produto — criar um produto com variantes.
• Atualizar produto — alterar dados do produto.
• Variantes — ler uma variante isolada (com costPerItem e productId).
• Convenções e Códigos de Erro.