Metadata-Version: 2.4
Name: openroam
Version: 0.1.0rc2
Summary: OpenRoam Partner API
Home-page: https://openroam.com
Author: OpenRoam Support
Author-email: OpenRoam Support <support@openroam.com>
Project-URL: Repository, https://github.com/OpenRoamHQ/openroam-sdks
Keywords: OpenAPI,OpenAPI-Generator,OpenRoam Partner API
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3<3.0.0,>=2.7.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# OpenRoam SDK for Python

Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights.
Python 3.9+.

## Install

```bash
pip install openroam==0.1.0-rc.2
```

> This is a **release candidate**: install it by its exact version, as above; a plain install does not pick it up. Before 1.0 the API can change between minor versions; every change is listed in the [changelog](https://github.com/OpenRoamHQ/openroam-sdks/blob/main/CHANGELOG.md).

## Quick start

```python
import os
import openroam
from openroam.webhooks import OPENROAM_ENVIRONMENTS

config = openroam.Configuration(
    host=OPENROAM_ENVIRONMENTS["sandbox"],  # or "production"
    api_key={"PartnerApiKey": os.environ["OPENROAM_API_KEY"]},
)

with openroam.ApiClient(config) as client:
    result = openroam.EsimsApi(client).esims_search(country_code="JP")
```

Every product has its own class (`AirtimeApi`, `EsimsApi`, `GiftCardsApi`, `HotelsApi`, `FlightsApi`, `UtilityApi`, `OrdersApi`, `WalletsApi`...) and each follows search, quote, order.

## Webhooks

```python
from openroam import verify_webhook, WebhookSignatureError

verify_webhook(
    secret=os.environ["OPENROAM_WEBHOOK_SECRET"],
    timestamp=headers["X-OpenRoam-Timestamp"],
    event_id=headers["X-OpenRoam-Event-Id"],
    signature=headers["X-OpenRoam-Signature"],
    raw_body=request_body,  # the body exactly as received, before JSON parsing
)  # raises WebhookSignatureError when invalid or older than 5 minutes
```

## Good to know

- **Orders need an `Idempotency-Key`** (a new UUID per purchase). After a timeout or a `5xx`, retry with the same key and the same body: it never charges twice.
- **Amounts** are `{ amount, currency }`. `price` is what OpenRoam charges you, `value` what your customer receives.
- **Errors** carry `code`, `name`, `message`, `requestId` and `details`; quote `requestId` when you contact support.
- Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.

This SDK is generated from the OpenRoam Partner API description; `webhooks` is hand-written. MIT licensed.
