Visão geral

O SDK oficial da Selectwin para Node.js e TypeScript — pagamentos (cartão, Pix, boleto), assinaturas e webhooks com uma API tipada, ergonômica e pronta para produção.

O pacote @selectwin/sdk é um núcleo gerado a partir do spec OpenAPI da API somado a uma casca de DX escrita à mão: cliente tipado, erros tipados, retries automáticos, idempotência, paginação e verificação de assinatura de webhook. É baseado em fetch, então roda em Node 18+, edge/workers, Bun e Deno.

Destaques

• Namespaces por recurso — sw.transactions.create(...), sw.customers.list(...), sw.subscriptions.pause(...).
• Erros tipados por error.code (nunca pela mensagem): CardError, ValidationError, RateLimitError, AuthenticationError, …
• Idempotência automática em toda mutação (header X-Idempotency-Key), com override por requisição.
• Retries com backoff em 429/5xx/erros de rede — seguros graças à idempotência.
• Paginação automática — for await (const tx of sw.transactions.list()).
• Webhooks — constructEvent(...) valida o HMAC X-Selectwin-Signature e devolve um evento tipado.
• Escape hatch — todo namespace expõe .raw com os métodos gerados por operationId.

Exemplo rápido

import { Selectwin } from '@selectwin/sdk';

const sw = new Selectwin(process.env.SELECTWIN_API_KEY!);

const tx = await sw.transactions.create({
  amount: 5000, // centavos = R$ 50,00
  payment: { method: 'pix', currency: 'BRL' },
  customer: {
    firstName: 'João',
    lastName: 'Silva',
    email: '[email protected]',
    document: { type: 'cpf', number: '12345678901' },
  },
});

console.log(tx.id, tx.status); // tra_… pending

Próximos passos

• Instalação — instalar e configurar o cliente.
• Quickstart — primeira cobrança, erros, paginação e webhooks.
• Referência da API — todos os endpoints e modelos.

Código-fonte no GitHub · pacote no npm.