Produtos

Product é a unidade que você vende. Tudo o que cobra na Zhex — pagamento único, assinatura, parcelamento, físico ou digital — começa aqui. Um produto agrupa preço, assinaturas, cupons, imagens, upsells, pixels de tracking e programa de afiliados sob uma identidade única.

Modelo mental

Um Product responde três perguntas:

1. O quê? — productClass: DIGITAL (curso, software, infoproduto) ou PHYSICAL (entregue por correios).
2. Como cobra? — type: ONE_TIME (um pagamento), RECURRING (assinatura recorrente) ou INSTALLMENT (parcelado).
3. Em qual estado? — status: ACTIVE, INACTIVE, PENDING, REJECTED ou BLOCKED. Veja Lifecycle.

A combinação productClass × type define o fluxo de checkout:

Criar produto

Endpoint: POST /v1/products

curl -X POST https://prometheus.zhex.io/v1/products \
  -H "Authorization: Bearer $ZHEX_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso Avançado de Node",
    "description": "12 módulos · 60h de vídeo",
    "payment": "unico",
    "type": "digital",
    "category": "education",
    "landing_page": "https://meusite.com/node-avancado",
    "base_currency": "BRL",
    "price": 49700
  }'

Mapeamento dos campos:

A criação retorna o Product já com ProductPrice aninhado. As moedas habilitadas para conversão automática (enabled_currencies) começam em ["BRL", "USD", "EUR"] — você pode editar depois em /v1/products/:id/price.

Listar e filtrar

Endpoint: GET /v1/products?limit=20&starting_after=prd_...&status=ACTIVE

const url = new URL('https://prometheus.zhex.io/v1/products');
url.searchParams.set('status', 'ACTIVE');
url.searchParams.set('limit', '20');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ZHEX_SECRET_KEY}` },
});
const { data, has_more } = await res.json();

Cada item vem enriquecido com product_images (incluindo a is_default: true) — útil para listar no dashboard sem N+1.

Atualizar

Endpoint: POST /v1/products/:id

Atualiza campos texto do produto. Atualizações de imagem são feitas em endpoint separado (em desenvolvimento, ver Imagens).

import { randomUUID } from 'node:crypto';

await fetch(`https://prometheus.zhex.io/v1/products/${productId}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZHEX_SECRET_KEY}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Curso Avançado de Node 2026',
    description: 'Atualizado para Node 22 + ESM puro',
    status: 'ACTIVE',                  // ou 'INACTIVE' para pausar
    category: 'education',
    landing_page: 'https://meusite.com/node',
  }),
});

Campos aceitos: name, description, status (ACTIVE | INACTIVE), category, landing_page.

Manipulação de imagens (upload, reordenação, remoção) será exposta via endpoint dedicado /v1/files em iteração próxima — esta fase mantém o contrato JSON-only.

Boas práticas

• name curto e claro — aparece em SMS de cobrança, fatura e statement. Limite de 60 chars.
• landing_page precisa estar acessível pública — usamos para fetch de OG image e validação anti-phishing.
• Não mude type depois de ativar. Crie um produto novo. ONE_TIME → RECURRING quebra qualquer Subscription ou CustomerSubscription ativa.
• category — usado para roteamento de adquirente (smart routing). Algumas categorias (high-risk) têm fluxo separado.

Próximos passos