SDK Node

Biblioteca oficial para Node.js.

Instalação

Requer Node.js 20 ou superior, não tem dependências e inclui tipos TypeScript. baseUrl é opcional se a variável GATEWAY_BASE_URL estiver definida. A opção timeoutMs muda o tempo máximo de cada requisição, que por padrão é de 30 segundos.

Terminal

npm install @gateway/sdk

index.ts

import { Gateway } from '@gateway/sdk';

const gateway = new Gateway(process.env.GATEWAY_API_KEY, {
  baseUrl: 'https://api.sacipix.com',
});

const charge = await gateway.charges.create({
  amount: 15000,
  reference: 'PEDIDO-0001',
});

console.log(charge.checkoutUrl);

Métodos

Método	Rota
`charges.create(params, options?)`	POST /v1/charges
`charges.retrieve(id)`	GET /v1/charges/{id}
`charges.list(params?)`	GET /v1/charges
`payouts.create(params, options?)`	POST /v1/payouts
`payouts.retrieve(id)`	GET /v1/payouts/{id}
`payouts.list(params?)`	GET /v1/payouts
`payouts.cancel(id)`	POST /v1/payouts/{id}/cancel
`crypto.quote(params)`	GET /v1/crypto/quote
`crypto.createPayout(params, options?)`	POST /v1/crypto/payouts
`balance.retrieve()`	GET /v1/balance
`balance.transactions(params?)`	GET /v1/balance/transactions
`customers.list(params?)`	GET /v1/customers
`sandbox.payCharge(id)`	POST /v1/sandbox/charges/{id}/pay
`sandbox.refundCharge(id)`	POST /v1/sandbox/charges/{id}/refund

Idempotência

Em payouts.create e crypto.createPayout, o SDK gera uma Idempotency-Key quando você não informa. Ela protege uma chamada, não o seu fluxo: se o seu processo reiniciar e criar o saque de novo, será outra chave. Para operações reais, passe uma chave derivada do seu pedido.

Chave informada

await gateway.payouts.create(
  { amount: 50000, pixKey: 'financeiro@example.com', pixKeyType: 'email' },
  { idempotencyKey: `saque-${pedido.id}` },
);

Erros

GatewayApiError: a API respondeu com erro. Traz code, status, message e details.
GatewayConnectionError: sem resposta, como queda de rede ou timeout. Traz idempotencyKey para repetir com segurança.

O SDK não repete requisições sozinho. Você decide quando repetir.

Tratamento

import { GatewayApiError, GatewayConnectionError } from '@gateway/sdk';

try {
  await gateway.payouts.create(params, { idempotencyKey });
} catch (err) {
  if (err instanceof GatewayApiError) {
    console.error(err.status, err.code, err.message, err.details);
  } else if (err instanceof GatewayConnectionError) {
    // Resultado desconhecido: repita com err.idempotencyKey
  }
}

Webhooks

Gateway.webhooks.verify(rawBody, signatureHeader, secret, toleranceSeconds = 300) confere a assinatura em tempo constante e devolve o evento. Se a assinatura for inválida ou expirada, lança GatewayWebhookError. rawBody precisa ser o corpo cru, em string ou Buffer. Veja Webhooks.

Verificação

import { Gateway, GatewayWebhookError } from '@gateway/sdk';

try {
  const event = Gateway.webhooks.verify(
    rawBody,
    req.headers['x-webhook-signature'],
    process.env.WEBHOOK_SECRET,
  );
} catch (err) {
  if (err instanceof GatewayWebhookError) res.sendStatus(400);
}