SDK Rust

O SDK oficial Rust oferece serviços tipados, paginação e verificação de webhooks para integrar servidores à API pública. Mantenha a chave da API no backend, sem distribuí-la em aplicações dos clientes.

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

Instalar o SDK

Use Rust 1.90 ou superior e um runtime Tokio. O crate oficial raims está disponível no crates.io. No diretório da aplicação:

cargo add raims
cargo add tokio --features macros,rt-multi-thread

Cargo consulta o crates.io, seleciona a versão estável compatível e registra as versões resolvidas em Cargo.lock. Preserve o lockfile para repetir a instalação.

As releases no GitHub continuam fornecendo fontes e o arquivo .crate. 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, guardada em RAIMS_API_KEY ou no cofre da aplicação. Ela define empresa, ambiente e permissões. Sandbox e Produção usam https://api.raims.com.

use raims::RaimsClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = RaimsClient::new(std::env::var("RAIMS_API_KEY")?)?;
    let balance = client.balances().retrieve().await?;
    println!("HTTP status: {}", balance.last_response.status_code);
    Ok(())
}

Reutilize o cliente; seus clones compartilham o pool HTTP. Os demais trechos com await pertencem a funções assíncronas que retornam Result. Use RaimsClient::builder com timeout, recebendo std::time::Duration, e max_read_retries para configurar timeout e retries de leitura. O timeout inclui tentativas e esperas; o padrão de retries é zero.

Criar um cliente e uma cobrança

customer_tax_id, customer_key e charge_key são String da aplicação. O primeiro é um CPF ou CNPJ válido e autorizado; as chaves são distintas e persistidas antes de enviar. due_date_unix é um i64 em segundos Unix UTC, escolhido e persistido para essa cobrança.

use raims::{params::{CreateCustomerParams, CreateChargeParams}, Optional, RequestOptions};

let customer_params = CreateCustomerParams {
    tax_id: Optional::Value(customer_tax_id),
    ..Default::default()
};
let customer_options = RequestOptions {
    idempotency_key: Some(customer_key),
    ..Default::default()
};
let customer = client.customers()
    .create_with_options(&customer_params, &customer_options).await?;

let charge_params = CreateChargeParams {
    customer_id: Optional::Value(customer.data.id),
    amount_cents: Optional::Value(15000),
    due_date: Optional::Value(due_date_unix),
    title: Optional::Value("Pedido 1234".to_owned()),
    ..Default::default()
};
let charge_options = RequestOptions {
    idempotency_key: Some(charge_key),
    ..Default::default()
};
let charge = client.charges()
    .create_with_options(&charge_params, &charge_options).await?;
let pending = charge.last_response.status_code == 202;

15000 representa R$ 150,00. Optional::Unset mantém um campo ausente, Optional::Null envia null quando permitido e Optional::Value(...) define um valor. Nos updates, omissão preserva o campo e null pode limpá-lo conforme o contrato. ApiResponse<T> contém data, last_response e raw; use raw quando precisar distinguir ausência de null na resposta.

Paginação e resultados pendentes

use raims::{params::ListCustomersParams, Optional};

let filters = ListCustomersParams {
    page_size: Optional::Value(50),
    ..Default::default()
};
let mut pages = client.customers().list_pages(&filters)?;
while let Some(response) = pages.next_page().await? {
    for customer in response.data.list {
        process_customer(customer);
    }
}

process_customer representa sua aplicação. Criar o pager não envia HTTP; next_page().await busca a primeira página e avança pelos cursores. A lista de uma resposta não busca páginas sozinha. O pager preserva filtros e opções; uma falha não avança o cursor. Use previous_page().await para voltar. Cursores são opacos; não combine after e before.

HTTP 202 mantém resultado pendente. Consulte o recurso ou acompanhe o webhook adequado antes de confirmar pagamento, estorno ou cancelamento.

Idempotência e erros

match client.customers().retrieve(&customer_id).await {
    Ok(response) => process_customer(response.data),
    Err(error) => handle_failure(
        error.kind(), error.status_code(), error.code(), error.request_id()
    ),
}

Os handlers pertencem à aplicação. Requisições retornam Result<ApiResponse<T>, Error>; kind(), status_code(), code() e request_id() ajudam a decidir a ação. Não use a mensagem humana como código nem registre corpos ou segredos.

O SDK não gera chaves nem repete escritas automaticamente. Quando uma resposta se perder, reconcilie a operação e preserve a chave e os parâmetros originais se o endpoint permitir nova tentativa. max_read_retries permite somente retries de leituras elegíveis. Retry-After e as tentativas ficam no orçamento de timeout; um cancelamento local não desfaz trabalho aceito pela API. Consulte Idempotência.

Usar o Sandbox

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

let sandbox = RaimsClient::new(std::env::var("RAIMS_SANDBOX_API_KEY")?)?;
let result = sandbox.simulations().charges()
    .confirm_payment(&sandbox_charge_id).await?;

sandbox_charge_id é uma String obtida na sua integração Sandbox. O SDK não seleciona ambiente por header nem transforma uma credencial de Produção. Veja Simulações. E-mails e webhooks ainda podem alcançar destinos externos; use somente destinos autorizados.

Receber webhooks

Preserve raw_body como &[u8], signing_headers como lista de pares (&str, &str) e webhook_secret como a string secret_key do webhook. Inclua todas as ocorrências de webhook-id, webhook-timestamp e webhook-signature; não as colapse antes de verificar.

use std::time::SystemTime;
use raims::{construct_webhook_event, DEFAULT_WEBHOOK_TOLERANCE};

let event = construct_webhook_event(
    raw_body,
    &signing_headers,
    &webhook_secret,
    DEFAULT_WEBHOOK_TOLERANCE,
    SystemTime::now(),
)?;
persist_event(event);

persist_event pertence à aplicação. A assinatura é conferida antes do JSON; não reserialize o corpo. A tolerância padrão é de cinco minutos nos dois sentidos; mantenha o relógio sincronizado. verify_webhook_signature permite autenticar sem decodificar o evento.

Confira tipo e ambiente, deduplique o id do evento e persista o trabalho antes de retornar sucesso. webhook-id identifica a entrega, não substitui o evento. Veja Receber eventos.

Atualizar o SDK

Confira as notas da release e atualize o SDK dentro do requisito declarado em Cargo.toml:

cargo update -p raims

Esse comando preserva o requisito existente. Para selecionar a versão estável atual fora desse requisito ou migrar de Git ou de um diretório local, anote as opções da dependência usadas pela aplicação. Remova somente a entrada raims do manifesto que a declara e preserve Cargo.lock. Se a dependência vier de um workspace, altere a entrada em [workspace.dependencies].

Se ela for opcional, preserve e remova temporariamente as referências à dependência em [features], como dep:raims, para manter o manifesto válido. Depois da adição, restaure essas declarações junto das opções optional e de features. No diretório da aplicação:

cargo add raims

Reaplique as opções da dependência, como features, e confira a entrada em Cargo.toml: ela deve usar o requisito de versão do registro selecionado pelo Cargo, sem git, path, branch, tag ou rev.

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