Raims Python

Official Python SDK for the Raims public API.

Use the SDK in server applications, with synchronous and asynchronous clients, typed parameters, read-only responses, cursor pagination, and webhook signature verification.

Install

Requires Python 3.10 or later. In your application's virtual environment:

python -m pip install raims

The package and import name are both raims. It uses HTTPX for HTTP transport.

To update to the current stable version:

python -m pip install --upgrade raims

Read the release notes and test your integration after updating. Pin the SDK and its dependencies in your application's dependency configuration to reproduce installations. Future updates are not applied automatically.

GitHub releases also provide wheel and source archives. Verify the downloaded file with SHA256SUMS before installing it. Install the downloaded wheel in your application environment:

python -m pip install /path/to/downloaded-package.whl

First request

import os

from raims import RaimsClient

with RaimsClient(os.environ["RAIMS_API_KEY"]) as raims:
    page = raims.customers.list({"page_size": 20})
    for customer in page:
        process_customer(customer.id)

process_customer represents your application's processing. The base URL is https://api.raims.com for both Sandbox and Production. The key determines the company, environment, and permissions. Keep it on the server and out of version control.

Create a charge

customer_id, due_date, and order_idempotency_key are values your application has already defined and persisted for the order. The due date uses Unix seconds in UTC, and the amount uses integer cents: 15000 represents BRL 150.00.

from raims import RequestOptions

with RaimsClient(os.environ["RAIMS_API_KEY"]) as raims:
    charge = raims.charges.create(
        {
            "customer_id": customer_id,
            "amount_cents": 15000,
            "due_date": due_date,
            "title": "Order 1234",
        },
        options=RequestOptions(idempotency_key=order_idempotency_key),
    )
    response = charge.last_response
    assert response is not None
    request_id = response.request_id

The SDK does not generate idempotency keys or retry writes automatically. If you lose a response, keep the same key and parameters and follow the endpoint's rules for retrieving or retrying the operation. A 202 response means processing is pending; retrieve the resource to follow its outcome.

Asynchronous use

from raims import AsyncRaimsClient

async def load_customers(api_key: str) -> None:
    async with AsyncRaimsClient(api_key) as raims:
        page = await raims.customers.list({"page_size": 50})
        async for customer in page.auto_paging_iter():
            await process_customer_async(customer.id)

process_customer_async represents your application's asynchronous processing. Normal iteration over a page accesses only the items already received. auto_paging_iter() retrieves subsequent pages as you consume them.

Services

Services expose create, retrieve, update, delete, and list according to the operations available. The reference describes each method.

Documentation

• Configuration, responses, and documents
• Pagination
• Errors, idempotency, and retries
• Receiving webhooks
• Contributing and security
• Installation and integration guide
• Public API

Distributed under the MIT license.