SDK .NET

Use o pacote Raims para integrar uma aplicação de servidor em C# à API pública. O SDK oferece serviços por recurso, entradas e respostas tipadas, paginação por cursor e validação de assinaturas de webhook. Os métodos têm versões síncronas e assíncronas, com sufixo Async.

A integração exige uma aplicação x64 em .NET Framework 4.8/4.8.1 ou .NET 10. Não distribua a chave de API em aplicações de navegador, desktop ou mobile entregues aos seus clientes. Ela deve permanecer no backend da integração.

Instalar o pacote

No diretório da aplicação:

dotnet add package Raims

Sem informar a versão, o NuGet instala a versão estável mais recente compatível com o projeto e registra a referência na aplicação.

Os destinos do pacote são netstandard2.0 e net10.0. O NuGet seleciona o destino adequado; os consumidores suportados são validados em .NET Framework 4.8 e .NET 10, x64.

Configurar o cliente

Obtenha a chave em Chaves de API e armazene-a em uma variável de ambiente protegida ou no cofre da aplicação. Empresa, ambiente e permissões são determinados pela credencial validada na API. Sandbox e Produção usam https://api.raims.com.

O exemplo abaixo é um trecho para um método async:

using System;
using Raims;

string apiKey = Environment.GetEnvironmentVariable("RAIMS_API_KEY")
    ?? throw new InvalidOperationException("Configure RAIMS_API_KEY.");

using (var raims = new RaimsClient(apiKey))
{
    var customers = await raims.Customers.ListAsync(new ListCustomersOptions
    {
        PageSize = 20,
    });

    foreach (var customer in customers)
    {
        Console.WriteLine(customer.Id);
    }
}

Reutilize o cliente durante a vida da integração para aproveitar as conexões HTTP e encerre-o quando não for mais necessário. Os próximos trechos consideram uma instância raims configurada pela aplicação.

Criar um cliente e uma cobrança

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

var customer = await raims.Customers.CreateAsync(new CreateCustomerOptions
{
    TaxId = customerTaxId,
}, new RequestOptions { IdempotencyKey = customerIdempotencyKey });

var charge = await raims.Charges.CreateAsync(new CreateChargeOptions
{
    CustomerId = customer.Id,
    AmountCents = 15000,
    DueDate = chargeDueDate,
    Title = "Pedido 1234",
}, new RequestOptions { IdempotencyKey = chargeIdempotencyKey });

int? httpStatus = charge.LastResponse?.StatusCode;
var requestId = charge.LastResponse?.RequestId;

Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro do cliente é atualizado e mantém seu identificador. 15000 representa R$ 150,00. Consulte os campos e condições em Criar cobrança. Para repetir a mesma intenção após perder a resposta, conserve a chave e todos os parâmetros, inclusive o vencimento. A referência externa de um pedido não substitui a idempotência.

Paginação e resultados pendentes

Enumerar uma página não faz novas requisições. Use NextPageAsync() e PreviousPageAsync() para navegar pelos cursores; o SDK conserva os filtros da consulta. GetAutoPagingEnumerable() e GetAutoPagingAsyncEnumerable() carregam as próximas páginas durante a enumeração e podem fazer várias requisições. Limite o trabalho da aplicação e use cancelamento quando necessário.

Uma resposta HTTP 202 mantém o significado de 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 sua aplicação.

Idempotência e erros

O SDK envia Idempotency-Key somente quando a aplicação o informa em um endpoint que aceita esse header. Ele não cria chaves nem repete POST, PATCH ou DELETE automaticamente. Retries de leitura são opcionais; o padrão é zero.

Decida o tratamento pelo status HTTP e por ApiErrorException.ErrorCode. RequestId ajuda a identificar a tentativa. ErrorMessage é um diagnóstico humano e não deve ser comparado como código de controle. Não registre a resposta completa, credenciais, documentos pessoais ou links temporários. Consulte Idempotência e a referência do SDK.

As opções usam Optional<T> para distinguir um campo omitido de um valor explícito. Em atualizações, omitir preserva o valor; null limpa somente os campos cujo contrato permite essa ação. Veja as condições de cada endpoint.

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. As regras e condições de cada simulação estão 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

Leia os bytes originais do corpo e os headers recebidos pelo seu servidor:

using System.Collections.Generic;
using Raims;

var headers = new Dictionary<string, string>
{
    ["webhook-id"] = receivedDeliveryId,
    ["webhook-timestamp"] = receivedTimestamp,
    ["webhook-signature"] = receivedSignature,
};

var webhookEvent = WebhookUtility.ConstructEvent(rawBodyBytes, headers, webhookSecret);

webhookSecret é o secret_key retornado ao criar ou rotacionar o webhook, e não a chave Bearer da API. Não reserialize o JSON antes de autenticar. Uma falha gera SignatureVerificationException; não processe o corpo nesse caso.

A assinatura válida não elimina duplicidades. 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 e não substitui o identificador do evento. Consulte Receber eventos.

Atualizar o SDK

Para buscar a versão estável mais recente no NuGet, execute novamente o comando sem informar um número de versão:

dotnet add package Raims

O NuGet atualiza a referência do projeto. Confira as releases e teste os fluxos usados pela sua integração. A versão do SDK é independente da versão HTTP /v1 da API.

Os guias completos de configuração, paginação, erros e webhooks estão no repositório do SDK.