Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. Python 3.11+.
pip install openroam==0.1.0-rc.6This 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.
import os
from openroam import OpenRoam
openroam = OpenRoam(os.environ["OPENROAM_API_KEY"]) # or OpenRoam() with OPENROAM_API_KEY set
found = openroam.esims.search(country_code="JP")
quote = openroam.esims.quote({"currency": "USD", "items": items})
order = openroam.esims.order({"currency": "USD", "items": items})
openroam.esims.get_usage(iccid)
openroam.hotels.search({...})Every product is an attribute of the client: esims, airtime, utilities, gift_cards, hotels, flights, plus orders,
order_items, wallets, currencies, countries and mobile_networks. Buying always reads search, quote, order; get fetches
one thing you own, list_... returns many, everything else starts with a verb. A path id is the first argument, a body is passed as it
is (a dict with the API's field names, or the model, such as openroam.EsimOrderRequest), and query parameters are keyword arguments.
Answers are models: found.items, found.pagination.
Options when you need them:
openroam = OpenRoam(
api_key="key",
environment="sandbox", # default "production"
max_retries=3, # default 0: no retries
# base_url="https://..." to point anywhere else, for example a development host
)
openroam.esims.search(country_code="JP", timeout=10) # every call takes a timeout, in secondsAn idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. order() creates a key for you on every call.
To stay safe even if your own program crashes and asks again, pass a UUID generated once and persisted for that purchase, for example
your order id if it is a UUID:
openroam.esims.order(body, idempotency_key=my_order_id)A failed call raises an OpenRoamError with the error body of the API: status, code (branch on this), name, message, request_id
(keep it for support) and details (a list of dicts with path, reason and message). When no answer arrived (network error,
timeout), status is None and __cause__ is the original error.
from openroam import OpenRoam, OpenRoamError
try:
openroam.esims.order(body)
except OpenRoamError as error:
if error.code == 11002:
... # the price rose above your maxPrice
else:
raisePagination depends on the method. esims.search accepts page and limit and returns items and pagination, while orders.list
returns orders and pagination. esims.list_catalog accepts cursor and limit and returns items and next_cursor; pass
next_cursor as cursor to fetch the next page. Some lists, such as esims.list_compatible_devices, return a plain list.
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 minutesRetries are off by default. Set max_retries to retry network errors, 429, 502/503/504 and "still running" (12002) safely:
a POST is sent again only with its Idempotency-Key, the same key and the same body, and order() always has one.
openroam = OpenRoam(api_key, max_retries=3)The full behaviour: Retries and idempotency. enable_retries and new_idempotency_key (in
openroam.retry) are also exported if you build your own requests.
-
Amounts are
{ amount, currency }.priceis what OpenRoam charges you,valuewhat your customer receives. - Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.
The client is generated from the OpenRoam Partner API description, so it always matches the API; webhooks, retry and the errors are hand-written. MIT licensed.