SDK Node.js

Use o pacote @raimshq/raims no backend Node.js. O SDK inclui módulos ESM e CommonJS, declarações TypeScript, serviços por recurso, paginação por cursor e autenticação de webhooks.

Instalar o pacote

O SDK requer Node.js 22 ou superior e inclui módulos ESM, CommonJS e tipos TypeScript. No diretório da aplicação:

npm install @raimshq/raims

O pacote @raimshq/raims inclui o runtime e as declarações de tipos. Preserve o lockfile da aplicação para reproduzir as versões instaladas.

As releases do GitHub também oferecem raims-node.tgz e SHA256SUMS. Para instalar o arquivo, baixe ambos para uma pasta raims-node-release, confira o hash e execute:

npm install ./raims-node-release/raims-node.tgz

Configurar o cliente

Obtenha uma chave em Chaves de API e guarde-a no cofre ou em uma variável de ambiente protegida da aplicação. Mantenha a credencial no backend, fora do navegador, de aplicações distribuídas aos seus clientes e dos logs.

Empresa, ambiente e permissões são determinados pela chave validada na API. Sandbox e Produção usam https://api.raims.com.

import Raims from '@raimshq/raims';

const apiKey = process.env.RAIMS_API_KEY;
if (!apiKey) throw new Error('Set RAIMS_API_KEY on the server.');

const raims = new Raims(apiKey, { maxNetworkRetries: 0 });
const customers = await raims.customers.list({ page_size: 20 });
for (const customer of customers.list) {
  console.log(customer.id);
}

Reutilize a instância para aproveitar as conexões HTTP. Em CommonJS, importe com const Raims = require('@raimshq/raims'). Os próximos trechos consideram raims configurado pela aplicação.

Criar um cliente e uma cobrança

customerTaxId é o CPF ou CNPJ válido do cliente autorizado. customerIdempotencyKey e chargeIdempotencyKey são chaves distintas criadas e persistidas antes das requisições. chargeDueDate é o vencimento escolhido e persistido, em segundos Unix UTC.

const customer = await raims.customers.create(
  {
    tax_id: customerTaxId,
  },
  { idempotencyKey: customerIdempotencyKey },
);

const charge = await raims.charges.create(
  {
    customer_id: customer.id,
    amount_cents: 15000,
    due_date: chargeDueDate,
    title: 'Pedido 1234',
  },
  { idempotencyKey: chargeIdempotencyKey },
);

const { statusCode, requestId } = charge.lastResponse;

Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu identificador. 15000 representa R$ 150,00. Preserve a chave e todos os parâmetros, inclusive o vencimento, ao recuperar a mesma intenção após perder uma resposta. Consulte Criar cobrança.

undefined omite uma propriedade; null é enviado como null. Consulte o contrato antes de limpar um campo. Valores inteiros devem caber em Number.MAX_SAFE_INTEGER, sem conversão por números fracionários.

Paginação e resultados pendentes

await list() busca uma página em list; nextPage() e previousPage() preservam os filtros e retornam null quando não há continuação. for await carrega as próximas páginas conforme o consumo; sair do loop impede novas buscas. processCustomer representa o tratamento da aplicação.

for await (const customer of raims.customers.list({ page_size: 50 })) {
  await processCustomer(customer.id);
}

Copie os cursores recebidos e mantenha os filtros; não envie after e before juntos. Consulte Listagem e paginação.

Uma resposta HTTP 202 indica resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na aplicação.

Idempotência e erros

Os erros HTTP expõem statusCode, code e requestId. ConnectionError indica falha de transporte e pode deixar uma escrita inconclusiva. maxNetworkRetries configura retries somente de GET; o padrão é zero.

O SDK envia a chave de idempotência somente quando a aplicação a informa em um endpoint que aceita Idempotency-Key. Ele não gera chaves nem repete escritas automaticamente. Um timeout não prova que a escrita foi recusada.

Decida pelo status HTTP e pelo código estruturado; error.message é um diagnóstico humano que pode mudar. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Veja Idempotência e o guia de erros do SDK.

Usar o Sandbox

Use uma chave Sandbox para as simulações em raims.simulations.charges e raims.simulations.refunds. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. Confira as condições na referência de Simulações.

Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração.

Receber webhooks

rawBody contém os bytes originais, como Buffer ou Uint8Array. receivedHeaders contém os headers recebidos. persistEvent e rejectDelivery representam o tratamento da aplicação; uma falha de persistência deve retornar erro HTTP para permitir nova entrega.

import { SignatureVerificationError, Webhook } from '@raimshq/raims';

try {
  const event = Webhook.constructEvent(rawBody, receivedHeaders, webhookSecret);
  await persistEvent(event);
} catch (error) {
  if (error instanceof SignatureVerificationError) rejectDelivery();
  else throw error;
}

Use o secret_key retornado ao criar ou rotacionar o webhook, diferente da chave Bearer da API. Leia o corpo antes do parser JSON e preserve seus bytes: não reserialize o conteúdo antes de autenticar.

Depois da autenticação, confira tipo e ambiente, deduplique pelo id do evento e grave o trabalho de forma durável antes de responder com sucesso. O header webhook-id identifica a entrega, não o evento. Consulte Receber eventos.

Atualizar o SDK

Para instalar a versão estável atual, execute no diretório da aplicação:

npm install @raimshq/raims@latest

Revise as notas de versão e teste os fluxos usados pela integração. Atualizações futuras não são instaladas automaticamente. Se você usa o TGZ, baixe novamente os arquivos da release estável atual, confira o hash e instale o novo arquivo.

Ao migrar de um TGZ anterior, substitua a dependência raims por @raimshq/raims e ajuste os imports e as chamadas de require.

A versão do SDK é independente da versão HTTP /v1 da API. Os guias completos e a referência de métodos estão no repositório do SDK.