SDK Elixir

O SDK oficial Elixir integra aplicações de servidor à API pública da Raims. Use módulos por recurso, modelos de resposta, paginação e verificação de webhooks. A chave da API deve permanecer no backend, fora de aplicações distribuídas aos clientes e dos logs.

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

Instalar o SDK

Use Elixir 1.18 ou superior com Erlang/OTP 27 ou superior. O pacote oficial raims está disponível no Hex.

Se o Hex ainda não estiver instalado, instale-o uma vez:

mix local.hex

Na raiz do projeto, consulte a versão estável e a configuração atuais:

mix hex.info raims

Copie a linha Config: para a lista devolvida por deps/0 no mix.exs da aplicação. Em seguida, busque as dependências e compile:

mix deps.get
mix compile

O Mix resolve as dependências conforme a configuração e registra as versões em mix.lock. Preserve esse arquivo para repetir a instalação.

As releases do GitHub continuam fornecendo os fontes e o arquivo de distribuição. Para instalar por Git ou por um diretório local, consulte as instruções do repositório.

Configurar o cliente

Obtenha uma chave em Chaves de API e armazene-a em uma variável protegida ou no cofre da aplicação. Ela define empresa, ambiente e permissões. A URL é https://api.raims.com em Sandbox e Produção.

client =
  Raims.Client.new(System.fetch_env!("RAIMS_API_KEY"),
    timeout: 30_000,
    max_network_retries: 0
  )

{:ok, balance} = Raims.Balances.retrieve(client)
request_id = balance.request_id

Timeouts usam milissegundos. O cliente é imutável e pode ser reutilizado; não mantém um processo que precise ser encerrado. Cada tentativa HTTP fecha sua conexão ao terminar. Os exemplos seguintes usam esse client.

Criar um cliente e uma cobrança

customer_tax_id contém o CPF ou CNPJ válido do cliente autorizado. customer_key e charge_key são chaves distintas, persistidas antes das requisições. Persista também due_date_unix, o vencimento em segundos Unix UTC.

with {:ok, customer} <-
       Raims.Customers.create(client, %{tax_id: customer_tax_id},
         idempotency_key: customer_key
       ),
     {:ok, charge} <-
       Raims.Charges.create(
         client,
         %{
           customer_id: customer.data["id"],
           amount_cents: 15000,
           due_date: due_date_unix,
           title: "Pedido 1234"
         },
         idempotency_key: charge_key
       ) do
  {:ok, charge.data["id"], charge.status_code}
else
  {:error, error} -> {:error, error.kind, error.request_id}
end

15000 representa R$ 150,00. Mapas aceitam chaves atom ou string com os nomes JSON. Omitir um campo o mantém ausente; nil envia null onde permitido. Em uma atualização, %{external_reference: nil} pode limpar a referência; omiti-la preserva o valor. As respostas usam response.data; Access.fetch/2 distingue um campo ausente de um campo com nil.

Paginação e resultados pendentes

{:ok, first_page} = Raims.Customers.list(client, %{page_size: 50})

first_page
|> Raims.Page.stream()
|> Stream.map(fn customer -> customer["id"] end)
|> Enum.take(100)

A lista de uma resposta contém só a página recebida. Raims.Page.stream/1 busca novas páginas sob demanda; Enum.take/2 limita a coleta. O stream levanta Raims.Error se uma página falhar. next_page/1 e previous_page/1 retornam {:ok, response}, {:ok, nil} ou {:error, error} e preservam filtros e opções. Não envie after e before juntos.

HTTP 202 aceita trabalho com resultado pendente. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar seu efeito financeiro.

Idempotência e erros

case Raims.Customers.retrieve(client, customer_id) do
  {:ok, response} -> MyApp.process_customer(response.data)
  {:error, error} ->
    MyApp.handle_failure(error.kind, error.status_code, error.code, error.request_id)
end

MyApp representa seu tratamento de negócio. As funções retornam tuplas {:ok, response} ou {:error, %Raims.Error{}}; variantes com ! levantam a exceção. Argumentos locais inválidos geram ArgumentError. Use categoria, status, código e Request-Id, sem registrar corpos ou credenciais.

O SDK não gera idempotência nem repete escritas. Após perder uma resposta, consulte a operação; quando for permitido repetir, use a mesma chave e os mesmos parâmetros. max_network_retries habilita somente retries de leituras GET/HEAD elegíveis, com padrão zero. Esperas, Retry-After e tentativas compartilham o orçamento de timeout. Veja Idempotência.

Usar o Sandbox

Use uma chave Sandbox e um recurso desse ambiente:

sandbox = Raims.Client.new(System.fetch_env!("RAIMS_SANDBOX_API_KEY"))
{:ok, result} = Raims.Simulations.Charges.confirm_payment(sandbox, sandbox_charge_id)

O SDK não seleciona nem troca o ambiente de uma credencial. As simulações financeiras aceitam somente Sandbox; uma chave de Produção continua sendo de Produção em um host local. Consulte Simulações. E-mails e webhooks podem alcançar destinos externos mesmo nesse ambiente; use somente destinos autorizados.

Receber webhooks

Use o binário original raw_body e uma lista de pares de headers recebidos com webhook-id, webhook-timestamp e webhook-signature. A lista preserva duplicidades para que o verificador rejeite ambiguidade.

case Raims.Webhook.construct_event(raw_body, signing_headers, webhook_secret) do
  {:ok, event} -> MyApp.persist_event(event)
  {:error, error} -> MyApp.reject_delivery(error)
end

webhook_secret é o secret_key do webhook mantido no cofre; os handlers MyApp pertencem à aplicação. Não parseie e reconstrua o JSON antes de verificar a assinatura. O padrão de tolerância é 300 segundos, com relógio sincronizado. verify_signature/4 permite verificar sem decodificar o JSON.

Após verificar, confira tipo e ambiente, deduplique pelo id do evento e grave o trabalho de forma durável antes de responder com sucesso. Uma assinatura válida não impede reentregas; webhook-id identifica a entrega. Veja Receber eventos.

Atualizar o SDK

Consulte a versão estável e a configuração atuais:

mix hex.info raims

Se necessário, ajuste a declaração em deps/0 com a linha Config: exibida pelo Hex. Depois atualize o SDK dentro das restrições declaradas:

mix deps.update raims
mix compile

Se a dependência usava github:, git: ou path:, substitua essa declaração pela configuração atual do Hex e execute os mesmos comandos. Remova também as opções exclusivas do Git, como ref:, branch: e tag:. Os módulos Raims continuam iguais.

Revise e preserve o mix.lock atualizado. Confira as notas da release e teste os fluxos usados pela integração antes de atualizar a aplicação. A instalação não aplica atualizações futuras automaticamente.