SDK Ruby

O SDK oficial Ruby integra aplicações de servidor à API pública da Raims. Ele oferece serviços por recurso, respostas tipadas, paginação por cursor e verificação de webhooks. Mantenha a chave de API no backend, fora do código distribuído aos seus clientes e dos logs.

A referência do SDK lista os métodos e parâmetros de cada recurso.

Instalar o SDK

Use Ruby 3.3 ou superior. A gem raims está no RubyGems. Instale no ambiente da aplicação:

gem install raims

Com Bundler, adicione a dependência ao Gemfile, usando o RubyGems como fonte:

source 'https://rubygems.org'
gem 'raims'

Instale as dependências:

bundle install

RubyGems e Bundler resolvem as dependências declaradas pela gem. Preserve o Gemfile.lock da aplicação para manter as versões escolhidas. O SDK é carregado com require 'raims'.

As releases estáveis do GitHub também fornecem raims.gem e SHA256SUMS. Para instalar por arquivo, baixe ambos em um diretório novo, pela página da release ou pelo GitHub CLI:

gh release download --repo raimshq/raims-ruby --pattern raims.gem --pattern SHA256SUMS --dir raims-ruby-release

Confira a origem do download e compare o SHA-256 de raims.gem com sua entrada em SHA256SUMS. Instale o arquivo local:

gem install ./raims-ruby-release/raims.gem

Configurar o cliente

Obtenha uma credencial em Chaves de API e armazene-a em RAIMS_API_KEY ou no cofre da aplicação. A chave define empresa, ambiente e permissões. Sandbox e Produção usam https://api.raims.com.

require 'raims'

raims = Raims::RaimsClient.new(ENV.fetch('RAIMS_API_KEY'))
begin
  balance = raims.balances.retrieve
  request_id = balance.last_response.request_id
ensure
  raims.close
end

Reutilize o cliente e feche-o ao encerrar seu uso. RaimsClient.open com bloco também garante fechamento. Os trechos seguintes pressupõem uma instância raims aberta. Timeouts usam segundos; retries de leitura ficam desativados por padrão.

Criar um cliente e uma cobrança

Defina customer_tax_id com o CPF ou CNPJ válido do cliente autorizado. Crie e persista customer_key e charge_key, distintas para cada intenção, antes de enviar. due_date_unix é o vencimento escolhido para a cobrança, em segundos Unix UTC; preserve-o quando repetir a mesma intenção.

customer = raims.customers.create(
  {tax_id: customer_tax_id},
  {idempotency_key: customer_key}
)

charge = raims.charges.create(
  {customer_id: customer.id, amount_cents: 15000,
   due_date: due_date_unix, title: 'Pedido 1234'},
  {idempotency_key: charge_key}
)

pending = charge.last_response.status_code == 202

15000 representa R$ 150,00. As entradas usam hashes com nomes JSON; campos omitidos ficam ausentes e nil envia JSON null quando permitido. Por exemplo, raims.customers.update(customer.id, {external_reference: nil}) limpa essa referência; omiti-la preserva o valor. Respostas oferecem leitores como customer.id; use key? para distinguir ausência de null.

Paginação e resultados pendentes

page = raims.customers.list({page_size: 50})
page.auto_paging_each do |customer|
  process_customer(customer)
end

process_customer pertence à aplicação. each percorre apenas a página recebida; auto_paging_each busca as seguintes e preserva filtros e opções. next_page e previous_page retornam outra página ou nil. Não combine after e before nem interprete os cursores.

HTTP 202 indica resultado pendente. Consulte o recurso ou processe o webhook adequado antes de confirmar um pagamento, estorno ou cancelamento.

Idempotência e erros

begin
  customer = raims.customers.retrieve(customer_id)
rescue Raims::RaimsError => error
  handle_failure(error.http_status, error.code, error.request_id)
end

handle_failure representa seu tratamento de falhas. Use status, código e Request-Id; mensagens humanas não são códigos de controle. ArgumentError indica argumentos locais inválidos. Não registre credenciais, corpos completos ou links temporários.

O SDK não gera chaves de idempotência nem repete escritas automaticamente. Após perder uma resposta, consulte o recurso e, quando o endpoint permitir repetir a requisição, reutilize chave e parâmetros originais. Configure max_network_retries no cliente ou nas opções para repetir somente leituras GET/HEAD elegíveis. O padrão é zero; Retry-After é respeitado dentro da política de espera do SDK. Veja Idempotência.

Usar o Sandbox

Use uma chave Sandbox e uma cobrança desse ambiente:

Raims::RaimsClient.open(ENV.fetch('RAIMS_SANDBOX_API_KEY')) do |sandbox|
  result = sandbox.simulations.charges.confirm_payment(sandbox_charge_id)
end

O SDK não transforma uma chave de Produção em Sandbox e não oferece seletor de ambiente. Consulte as condições em Simulações. Pedidos de envio por e-mail e entregas de webhook podem alcançar destinos externos mesmo no Sandbox; use destinos autorizados.

Receber webhooks

Preserve raw_body, a string com os bytes originais recebidos pelo servidor, e signing_headers, o hash com webhook-id, webhook-timestamp e webhook-signature. Preserve ocorrências repetidas para rejeitar ambiguidade.

begin
  event = Raims::Webhook.construct_event(
    raw_body, signing_headers, ENV.fetch('RAIMS_WEBHOOK_SECRET')
  )
  persist_event(event)
rescue Raims::SignatureVerificationError
  reject_delivery
end

persist_event e reject_delivery são responsabilidades da aplicação. RAIMS_WEBHOOK_SECRET contém o secret_key do webhook, não a chave da API. Não reserialize o JSON antes da verificação. Em falha, não processe o evento.

A tolerância padrão é de 300 segundos; mantenha o relógio sincronizado. Uma assinatura válida não elimina reentregas: confira tipo e ambiente, deduplique pelo id do evento e grave o trabalho de forma durável antes de responder com sucesso. webhook-id identifica a entrega. Veja Receber eventos.

Atualizar o SDK

Em aplicações com Bundler, atualize a gem e suas dependências conforme as restrições do Gemfile:

bundle update raims

Revise e preserve o Gemfile.lock atualizado. Em uma instalação gerenciada diretamente pelo RubyGems, use:

gem update raims

Se o Gemfile usava os fontes baixados do GitHub, substitua a declaração com path: ou git: por gem 'raims', com a fonte https://rubygems.org, e execute bundle update raims. O require 'raims' permanece igual.

Confira o histórico de versões e teste os fluxos usados pela integração antes de atualizar a aplicação. A instalação não ativa atualizações automáticas futuras.