SDK Java

Use com.raims:raims-java para integrar seu backend Java à API pública. O SDK oferece serviços por recurso, builders tipados, respostas tipadas, paginação por cursor e autenticação de webhooks.

Instalar o pacote

O SDK requer Java 11 ou superior e está no Maven Central como com.raims:raims-java. Consulte a versão estável atual nesse link e substitua SDK_VERSION nos exemplos abaixo por essa versão. Mantenha a versão escolhida na configuração da aplicação.

Maven

Adicione a dependência ao pom.xml:

<dependency>
  <groupId>com.raims</groupId>
  <artifactId>raims-java</artifactId>
  <version>SDK_VERSION</version>
</dependency>

Gradle

No build.gradle, use o repositório Maven Central e declare a dependência:

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.raims:raims-java:SDK_VERSION'
}

Com Kotlin DSL, no build.gradle.kts:

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.raims:raims-java:SDK_VERSION")
}

Maven e Gradle resolvem o SDK e suas dependências transitivas pelo Maven Central. As releases do GitHub também fornecem JAR, POM, fontes, Javadoc e SHA256SUMS. Para usar esses arquivos, consulte a instalação pelo GitHub.

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 com.raims.RaimsClient;
import com.raims.param.ListCustomersParams;

try (RaimsClient raims = RaimsClient.builder()
        .setApiKey(System.getenv("RAIMS_API_KEY"))
        .setMaxNetworkRetries(0)
        .build()) {
    var customers = raims.customers().list(
        ListCustomersParams.builder().setPageSize(20).build());
    customers.getList().forEach(customer -> System.out.println(customer.getId()));
}

Reutilize uma instância de RaimsClient entre chamadas e threads. O cliente implementa AutoCloseable; use try-with-resources para um escopo curto ou close() ao encerrar o cliente compartilhado. Os próximos trechos consideram raims configurado e aberto 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 é um long com o vencimento escolhido e persistido, em segundos Unix UTC.

import com.raims.RequestOptions;
import com.raims.param.CreateCustomerParams;
import com.raims.param.CreateChargeParams;

var customer = raims.customers().create(
    CreateCustomerParams.builder().setTaxId(customerTaxId).build(),
    RequestOptions.builder().setIdempotencyKey(customerIdempotencyKey).build());

var charge = raims.charges().create(
    CreateChargeParams.builder()
        .setCustomerId(customer.getId())
        .setAmountCents(15000)
        .setDueDate(chargeDueDate)
        .setTitle("Pedido 1234")
        .build(),
    RequestOptions.builder().setIdempotencyKey(chargeIdempotencyKey).build());

int httpStatus = charge.getLastResponse().getStatusCode();
String requestId = charge.getLastResponse().getRequestId();

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.

Omitir um setter mantém o campo ausente. Os setters com sufixo Null enviam null nos campos que permitem essa ação. Consulte o contrato antes de limpar um valor.

Paginação e resultados pendentes

list() busca uma página tipada, com getList(). nextPage() e previousPage() preservam filtros e retornam null quando não há continuação. autoPagingIterable() avança conforme o consumo; mantenha o cliente aberto durante a enumeração. processCustomer representa o tratamento da aplicação.

for (var customer : raims.customers().list().autoPagingIterable()) {
    processCustomer(customer.getId());
}

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

As falhas usam exceções em com.raims.exception. Use getStatusCode(), getCode() e getRequestId() para tratar erros HTTP. Uma falha de conexão pode deixar uma escrita inconclusiva. setMaxNetworkRetries configura retries de leitura; 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

rawBodyBytes contém os bytes recebidos. receivedDeliveryId, receivedTimestamp e receivedSignature são os valores dos headers do servidor. Rejeite a entrega se constructEvent lançar uma exceção de verificação de assinatura.

import com.raims.WebhookUtility;
import com.google.gson.JsonObject;
import java.util.Map;

Map<String, String> headers = Map.of(
    "webhook-id", receivedDeliveryId,
    "webhook-timestamp", receivedTimestamp,
    "webhook-signature", receivedSignature);

JsonObject event = WebhookUtility.constructEvent(rawBodyBytes, headers, webhookSecret);

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

Consulte a versão estável atual de com.raims:raims-java no Maven Central, atualize a versão da dependência no pom.xml, build.gradle ou build.gradle.kts e execute os testes da integração.

Se a aplicação instalava o JAR pelo GitHub, as coordenadas com.raims:raims-java continuam iguais. Use a versão disponível no Maven Central na dependência da aplicação.

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.