Criar um produto

Cria um produto no seu catálogo e, na mesma requisição, pelo menos uma variante com preço. O produto é o "guarda-chuva" comercial (nome, tipo, garantia); a variante é o item vendável de fato, com pricing. Use este endpoint sempre que cadastrar uma nova oferta — um curso, um plano de assinatura ou um produto físico.

POST /v1/products

Como funciona

Um produto agrupa informações de apresentação e regras de negócio (nome, descrição, tipo, garantia, categoria). Mas quem carrega o preço é a variante (variant): cada produto tem uma ou mais variantes, e é a variante que o cliente compra. Por isso a criação é atômica — você envia o produto e ao menos uma variante no mesmo corpo, e a API cria tudo de uma vez.

Pontos importantes do mecanismo:

• Atômico: se qualquer variante for inválida, nada é criado — você recebe 422 e nenhum prd_* é gerado.
• pricing.type e pricing.schema são definidos na criação e tratados como imutáveis. Para trocar entre oneTime (cobrança única) e recurring (assinatura), crie uma nova variante em vez de editar a existente — tentar alterar retorna pricingTypeImmutable / pricingSchemaImmutable (422).
• Dinheiro em centavos. unitPrice: 9900 = R$ 99,00. Veja Convenções.
• IDs opacos. A resposta traz id do produto (prd_*) e de cada variante (var_*). Guarde a string inteira; não faça parsing.

Quando usar

• Cadastrar uma nova oferta no catálogo (produto + sua(s) variante(s) de preço).
• Subir um catálogo do seu sistema externo, usando externalReference para correlacionar.

Quando não usar:

• Para adicionar uma variante a um produto que já existe, use o endpoint de criação de variante (POST /v1/products/{productId}/variants) — veja Variants. Não recrie o produto.
• Para alterar dados do produto (nome, categoria, flags), use Update.

Requisição

Headers

A autenticação é sempre pelo header SelectKey — nunca Authorization: Bearer/Basic. Veja Autenticação. Como criar é uma operação de escrita, envie um X-Idempotency-Key: se a requisição for repetida (timeout, retry), o produto não é duplicado. Veja Idempotência.

Corpo — produto

Corpo — variants[]

Corpo — variants[].pricing

¹ Aplica-se apenas quando type=recurring. ² Obrigatório quando type=recurring. ³ Usado quando billingType=exactday.

Exemplo — produto digital com variante de cobrança única

curl -X POST "https://api.selectwin.io/v1/products" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 9c1f2a8e-create-premium-course" \
  -d '{
    "name": "Premium Course",
    "slug": "premium-course",
    "description": "Curso completo",
    "type": "digital",
    "language": "pt",
    "category": "courses",
    "warrantyDays": 30,
    "enabled": true,
    "externalReference": "SKU-EXT-1",
    "variants": [
      {
        "name": "Plano Anual",
        "description": "Acesso por 12 meses",
        "sku": "SKU-001",
        "enabled": true,
        "externalReference": "VAR-EXT-1",
        "pricing": {
          "unitPrice": 49900,
          "currency": "BRL",
          "schema": "unit",
          "type": "oneTime",
          "oldPrice": 69900
        }
      }
    ]
  }'

Exemplo — variante recorrente (assinatura)

Para uma assinatura, use type: "recurring" e informe os campos de cobrança (billingType, billingFrequency, billingFrequencyCount). Opcionalmente, um período de teste:

{
  "name": "SaaS Pro",
  "type": "digital",
  "category": "saas",
  "warrantyDays": 7,
  "variants": [
    {
      "name": "Mensal",
      "sku": "SKU-M",
      "pricing": {
        "unitPrice": 9900,
        "currency": "BRL",
        "schema": "unit",
        "type": "recurring",
        "billingType": "prepaid",
        "billingFrequency": "monthly",
        "billingFrequencyCount": 1,
        "trialInterval": "day",
        "trialIntervalCount": 7,
        "cycles": 12
      }
    }
  ]
}

Resposta

201 Created. O corpo é o produto completo, com cada variante criada (incluindo seus id e timestamps). O pricing na resposta usa daysTrial (campo derivado, em dias) além dos campos de configuração que você enviou.

{
  "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-chave da resposta

Erros

Trate sempre pelo error.code (estável), não pela message. Catálogo completo: Códigos de Erro; estrutura do envelope: Tratamento de Erros.

Boas práticas

• Sempre envie X-Idempotency-Key ao criar. Um retry após timeout não deve gerar dois produtos.
• Decida type e schema da variante com cuidado — eles são imutáveis. Se precisar de cobrança única e recorrente, crie duas variantes no mesmo produto.
• Converta para centavos antes de enviar unitPrice e oldPrice. R$ 99,00 → 9900. Respeite a faixa mínima (500 = R$ 5,00).
• Para assinaturas (type=recurring), lembre que billingType, billingFrequency e billingFrequencyCount são obrigatórios; sem eles a criação falha na validação.
• Use externalReference no produto e na variante para amarrar ao seu catálogo e reconciliar depois sem depender do ID interno.
• Guarde os var_*, não só o prd_*: é a variante que entra no checkout e na transação.
• Defina oldPrice apenas para exibir o preço "de/por"; ele deve ser maior que unitPrice para fazer sentido comercial.

Veja também

• Overview — modelo do objeto, ciclo de vida e todas as operações.
• Read — recuperar o produto completo pelo prd_*.
• Update — alterar nome, categoria e flags do produto.
• List — listar e filtrar produtos do catálogo.
• Variants — criar/atualizar variantes de um produto existente.
• Convenções · Idempotência · Autenticação