Criar um produto

POST /v1/products

Cria um produto e suas variantes na mesma requisição (variants[] é obrigatório, com pelo menos uma variante). A precificação de cada variante vai em pricing (veja o modelo de precificação).

Escopo requerido: products:create. Suporta chave de idempotência (X-Idempotency-Key).

Requisição

curl -X POST "https://api.selectwin.io/v1/products" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Course",
    "salesPage": "https://loja.com/premium",
    "description": "Curso completo",
    "enabled": true,
    "type": "digital",
    "language": "pt-BR",
    "category": "courses",
    "warrantyDays": 30,
    "externalReference": "SKU-EXT-1",
    "images": ["https://example.com/img1.png"],
    "variants": [
      {
        "name": "Plano Anual",
        "sku": "SKU-001",
        "description": "Acesso por 12 meses",
        "enabled": true,
        "externalReference": "VAR-EXT-1",
        "pricing": {
          "unitPrice": 49900,
          "currency": "BRL",
          "schema": "unit",
          "type": "oneTime",
          "oldPrice": 69900,
          "costPerItem": 12000
        }
      }
    ]
  }'

O slug não é aceito na requisição — a API o gera automaticamente a partir do name (tanto para o produto quanto para cada variante).

Campos do produto

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do produto (máx. 40 caracteres)
`category`	string	Sim	Categoria de negócio (1–100 caracteres)
`warrantyDays`	integer	Sim	Dias de garantia (7–3650)
`type`	string	Sim	`physical`, `digital` ou `other`
`variants[]`	array	Sim	Variantes do produto (1 a 100), cada uma com `pricing`
`language`	string	Não	Idioma, até 10 caracteres (default `pt-BR`)
`enabled`	boolean	Não	Ativo (default `true`)
`salesPage`	string (url)	Não	Página de vendas (até 255 caracteres)
`description`	string	Não	Descrição (até 400 caracteres)
`externalReference`	string	Não	Sua referência externa (até 255 caracteres)
`images[]`	array	Não	URLs de imagens (até 10)

Campos da variante (variants[])

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da variante (1–255 caracteres)
`pricing`	object	Sim	Veja campos de `pricing`. `type` e `schema` são imutáveis depois de criados
`description`	string	Não	Descrição (até 255 caracteres)
`sku`	string	Não	SKU (até 50 caracteres)
`images[]`	array	Não	URL de imagem (no máximo 1)
`metadata`	object	Não	Pares chave/valor livres
`attributes`	object	Não	Atributos livres da variante
`externalReference`	string	Não	Sua referência externa (até 255 caracteres)
`enabled`	boolean	Não	Ativo (default `true`)

A primeira variante do array é marcada como primary: true na resposta.

Resposta 201 Created

Retorna o produto completo com suas variantes (mesmo formato de Consultar):

{
  "id": "prd_01hqzvabc",
  "name": "Premium Course",
  "slug": "premium-course",
  "salesPage": "https://loja.com/premium",
  "description": "Curso completo",
  "language": "pt-BR",
  "enabled": true,
  "salesQty": null,
  "type": "digital",
  "category": "courses",
  "externalReference": "SKU-EXT-1",
  "warrantyDays": 30,
  "images": ["https://example.com/img1.png"],
  "imageAssetIds": null,
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "variants": [
    {
      "id": "var_01hqzvabc",
      "productId": "prd_01hqzvabc",
      "name": "Plano Anual",
      "slug": "plano-anual",
      "description": "Acesso por 12 meses",
      "sku": "SKU-001",
      "primary": true,
      "enabled": true,
      "pricing": {
        "unitPrice": 49900,
        "oldPrice": 69900,
        "costPerItem": 12000,
        "currency": "BRL",
        "schema": "unit",
        "type": "oneTime"
      },
      "images": null,
      "metadata": null,
      "attributes": null,
      "externalReference": "VAR-EXT-1",
      "checkoutUrl": null,
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z"
    }
  ]
}

Erros

`error.code`	HTTP	Quando
`invalidParameters`	400	Corpo inválido (campo obrigatório ausente, fora de faixa etc.)
`invalidPricing`	422	Configuração de `pricing` inconsistente com o `schema`/recorrência

Catálogo completo: Códigos de Erro.