SDK Python

Use o pacote raims no backend da integração, com clientes síncrono e assíncrono, parâmetros tipados, respostas somente leitura, paginação por cursor e autenticação de webhooks.

Instalar o pacote

O SDK requer Python 3.10 ou superior. No ambiente virtual da aplicação:

python -m pip install raims

O pacote raims está no PyPI e mantém o mesmo nome no import. O pip resolve suas dependências. Consulte o histórico de versões e fixe a versão escolhida no requirements.txt ou no arquivo de lock da aplicação.

As releases do GitHub também fornecem wheel e código-fonte. Para instalar o wheel, baixe o arquivo .whl e SHA256SUMS para uma pasta raims-python-release, preserve o nome original e confira o hash. Em um shell Bash, com apenas esse wheel na pasta:

python -m pip install ./raims-python-release/raims-*.whl

No PowerShell, selecione o arquivo baixado:

$wheels = @([System.IO.Directory]::GetFiles((Resolve-Path ./raims-python-release).Path, '*.whl'))
if ($wheels.Count -ne 1) { throw 'Keep exactly one downloaded wheel in this directory.' }
python -m pip install $wheels[0]

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 os

from raims import RaimsClient

api_key = os.environ["RAIMS_API_KEY"]
with RaimsClient(api_key, max_network_retries=0) as raims:
    customers = raims.customers.list({"page_size": 20})
    for customer in customers:
        print(customer.id)

Reutilize o cliente durante seu ciclo de uso. with encerra o cliente síncrono; para o assíncrono, use AsyncRaimsClient com async with e await nas chamadas. Mantenha uma instância assíncrona por ciclo de vida do event loop.

Criar um cliente e uma cobrança

customer_tax_id é o CPF ou CNPJ válido do cliente autorizado. customer_idempotency_key e charge_idempotency_key são chaves distintas criadas e persistidas antes das requisições. charge_due_date é o vencimento escolhido e persistido, em segundos Unix UTC.

from raims import RequestOptions

with RaimsClient(api_key) as raims:
    customer = raims.customers.create(
        {"tax_id": customer_tax_id},
        options=RequestOptions(idempotency_key=customer_idempotency_key),
    )
    charge = raims.charges.create(
        {
            "customer_id": customer.id,
            "amount_cents": 15000,
            "due_date": charge_due_date,
            "title": "Pedido 1234",
        },
        options=RequestOptions(idempotency_key=charge_idempotency_key),
    )
    response = charge.last_response
    if response is not None:
        print(response.status_code, response.request_id)

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.

As entradas mantêm os nomes JSON da API. Omitir uma chave mantém o campo ausente; None envia null. Consulte o contrato antes de limpar um valor. Respostas preservam campos futuros e não devem ser alteradas diretamente.

Paginação e resultados pendentes

list() busca uma página. A iteração normal lê somente os itens recebidos; next_page() e previous_page() preservam os filtros. auto_paging_iter() carrega as próximas páginas conforme o consumo. No cliente assíncrono, use await na consulta e async for no iterador. process_customer representa o tratamento da aplicação.

with RaimsClient(api_key) as raims:
    page = raims.customers.list({"page_size": 50})
    for customer in page.auto_paging_iter():
        process_customer(customer.id)

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

Trate erros HTTP por ApiError, usando status_code, code e request_id. ConnectionError indica falha de transporte e pode deixar uma escrita inconclusiva. max_network_retries configura retries somente 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

raw_body contém os bytes recebidos e received_headers contém webhook-id, webhook-timestamp e webhook-signature. reject_delivery e persist_event representam o tratamento da aplicação. Não processe a entrega cuja assinatura falhou.

from raims import SignatureVerificationError, Webhook

try:
    event = Webhook.construct_event(raw_body, received_headers, webhook_secret)
except SignatureVerificationError:
    reject_delivery()
else:
    persist_event(event)

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

Para instalar a versão estável atual, execute no ambiente da aplicação:

python -m pip install --upgrade raims

Revise as notas da release e teste os fluxos usados pela integração. Fixe a versão e as dependências na configuração da aplicação para reproduzir a instalação. Atualizações futuras não são instaladas automaticamente.

Se instalou pelo GitHub, o import raims permanece igual. Atualize a origem da dependência na configuração da aplicação se ela fixar uma URL Git ou um arquivo local. Para continuar usando o wheel do GitHub, baixe os arquivos da nova release, confira o hash e instale o novo wheel com --upgrade.

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.