onlinesim-python-api

Typed, zero-dependency Python client for the OnlineSim API — SMS numbers, rent, account and free numbers.

Install

Python 3.9 or newer. The PyPI package is onlinesimru; it uses only the standard library (urllib, json) and ships type hints (py.typed).

pip install onlinesimru

Quick start

Check the balance, order a number, wait for the SMS code.

import os

from onlinesimru import OnlineSim

client = OnlineSim(os.environ["ONLINESIM_KEY"])

b = client.user.balance()
print(f"available: {b['balance'] - max(b['zbalance'], 0)} USD")

order = client.numbers.get_with_number("google", 44)
print(f"enter {order['number']} in the app")

# Polls every 5 s for up to 10 min, then closes the operation.
code = client.numbers.wait_code(order["tzid"])
print(f"code: {code}")

The client is synchronous. Results are plain dicts typed as TypedDicts (Balance, NumberOrder, …), so editors and mypy know the keys.

Client options

from onlinesimru import OnlineSim

client = OnlineSim("your-api-key", lang="en", timeout=15)
OptionTypeDefaultDescription
api_keystr | NoneNoneFirst positional argument. Sent as Authorization: Bearer <api_key>, never in the URL. Not needed for tariffs and free numbers.
base_urlstrhttps://onlinesim.host/api/API base; trailing slash optional.
langstrenLanguage of server texts (lang query parameter).
dev_idstr | int | NoneNonePartner developer id (dev_id), sent only when set.
timeoutfloat30Per-request timeout, seconds.
transportTransporturllib_transportSends the HTTP requests: a custom TLS setup, a proxy, or a fake in tests.

Sections: client.numbers, client.rent, client.user, client.free. Webhook bodies are parsed by the standalone parse_webhook.

Returned dicts keep the server's snake_case field names. Two things are normalised: money that the server sends as a decimal string (balance, rent sum in rent.state) becomes a number, and maps that arrive as an empty PHP array [] become {}. payment_history()["paylist"] is left as sent: a JSON array when its ids are 0, 1, 2…

Transport

A transport is any callable (HttpRequest) -> HttpResponse. HttpRequest has method, url, headers, body (bytes or None) and timeout (seconds); HttpResponse has status and body (bytes). Return the response for every HTTP status and raise OSError on network errors. The default urllib_transport takes an optional ssl.SSLContext:

import functools
import ssl

from onlinesimru import OnlineSim, urllib_transport

ctx = ssl.create_default_context(cafile="/etc/ssl/corp-ca.pem")
client = OnlineSim("your-api-key", transport=functools.partial(urllib_transport, context=ctx))

Error handling

Every error extends OnlineSimError.

ClassWhenAttributes
ApiErrorThe API answered with an error code (also a wrong key, HTTP 456, and the rate limit, HTTP 429 TRY_AGAIN_LATER).code, message
NoNumberErrorNO_NUMBER: no number right now. Subclass of ApiError.code, message
TransportErrorNetwork error, request timeout, or a body that is not JSON.status (None without a response), body (first 500 chars)
TimeoutErrorwait_code got no code within its timeout. Also a built-in TimeoutError.—
from onlinesimru import ApiError, NoNumberError, TransportError

try:
    client.numbers.get("google", 44)
except NoNumberError:
    pass  # try another country or later
except ApiError as error:
    print(error.code, error.message)  # e.g. WARNING_LOW_BALANCE
except TransportError as error:
    print("network", error.status, error.body)

message is the server's text when it sends one, otherwise a short English description of the code (ERROR_MESSAGES), otherwise the code itself. Profile validation failures become ApiError with code VALIDATION_ERROR.