Integração

A Zhex é uma API HTTP REST com OpenAPI 3.1 publicado em prometheus.zhex.io/v1/openapi.json. Você integra de dois jeitos:

1. @zhex/node — SDK oficial em TypeScript. Tipos completos, idempotência automática, retry com backoff, auto-paginação, helper de webhook.
2. HTTP puro — fetch nativo do Node 18+ ou curl. Zero dependência, mesma API.

Os dois caminhos batem na mesma API e expõem os mesmos recursos. Use SDK quando estiver em Node; use HTTP quando estiver em qualquer outra linguagem ou quiser controle total do transporte.

Caminho rápido — SDK

npm install @zhex/node

import Zhex from '@zhex/node';

const zhex = new Zhex(process.env.ZHEX_SECRET_KEY!);

const customer = await zhex.customers.create({
  email: 'jane@acme.com',
  name: 'Jane Doe',
});

const intent = await zhex.paymentIntents.create({
  amount: 19900,
  currency: 'brl',
  customer: customer.id,
});

Caminho rápido — HTTP

const res = await fetch('https://prometheus.zhex.io/v1/payment_intents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZHEX_SECRET_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Zhex-Version': '2026-04-25',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 19900,
    currency: 'brl',
    customer: 'cus_…',
  }),
});

if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.error.code}: ${err.error.message}`);
}

const intent = await res.json();

O que o SDK te dá

• Tipos completos — autocomplete em todos os recursos e parâmetros, narrowing por status de PaymentIntent.
• Idempotência automática — todo POST recebe Idempotency-Key UUIDv4 sem você pensar; retries replay a mesma key, sem dupla cobrança.
• Retry com backoff — 429 / 5xx retentam até 3 vezes com jitter exponencial; você só vê a falha quando ela for real.
• Auto-paginação — for await (const x of zhex.customers.list({}).autoPagingEach()) itera tudo.
• Verificação de webhook — Zhex.webhooks.constructEvent(rawBody, signature, secret) em uma linha, com tolerância de timestamp e timingSafeEqual por baixo.
• Erros tipados — ZhexCardError, ZhexNotFoundError, ZhexIdempotencyError etc., todos com code, requestId, statusCode.

Quando ir direto via HTTP

• Não está em Node — Python, Go, PHP, Ruby. Use fetch/requests/net/http/etc. com o OpenAPI como guia.
• Edge runtime sem suporte a node:crypto — Cloudflare Workers, Deno Deploy. O SDK precisa de Node ≥18; em runtimes alternativos, fetch direto é mais portável.
• Você quer ver/controlar tudo — proxy corporativo, telemetria custom, mTLS, OTel manual. SDK abstrai um pedaço; HTTP é integral seu.

Próximos passos