onlinesim-rs-api

Typed async and blocking Rust client for the OnlineSim API — SMS numbers, rent, account and free numbers.

Install

Rust 1.85 or newer. The async client runs on reqwest + tokio; the blocking one is behind a feature.

[dependencies]
onlinesim-rs-api = "0.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
FeatureDefaultWhat
asyncyesClient: async methods.
blockingnoblocking::Client: the same methods without .await.
mock-transportnomock::MockOnlineSim: an in-process fake OnlineSim API for your own tests, no extra dependencies (Testing).
mocknomock-transport plus MockOnlineSim::start(), the same fake over local HTTP (wiremock).

Without features the crate has only the types, the errors and parse_webhook — enough for a webhook receiver.

Quick start

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

use onlinesim_rs_api::{Client, WaitCodeOptions};

#[tokio::main]
async fn main() -> onlinesim_rs_api::Result<()> {
    let client = Client::new(std::env::var("ONLINESIM_KEY").unwrap_or_default())?;

    let balance = client.user().balance().await?;
    println!("available: {} USD", balance.balance - balance.zbalance.max(0.0));

    let order = client.numbers().get_with_number("google", 44, &[]).await?;
    println!("enter {} in the app", order.number);

    // Polls every 5 s for up to 10 min, then closes the operation.
    let code = client.numbers().wait_code(order.tzid, WaitCodeOptions::default()).await?;
    println!("code: {code}");
    Ok(())
}

Blocking: onlinesim_rs_api::blocking::Client::new(key)? and the same calls without .await (feature blocking).

Client options

use std::time::Duration;
use onlinesim_rs_api::Client;

let client = Client::builder()
    .api_key("your-api-key")
    .lang("en")
    .timeout(Duration::from_secs(15))
    .build()?;
Builder methodTypeDefaultDescription
api_keyimpl Into<String>—Sent as Authorization: Bearer <key>, never in the URL. Not needed for tariffs and free numbers.
base_urlimpl Into<String>https://onlinesim.host/api/API base; trailing slash optional.
langimpl Into<String>enLanguage of server texts (lang query parameter).
dev_idimpl Display—Partner developer id (dev_id), sent only when set.
timeoutDuration30 sPer-request timeout, also applied to an injected reqwest client.

Finish with build() (async, default reqwest::Client), build_with(transport) (your reqwest::Client — proxy, TLS — or any Transport, e.g. a fake in tests), build_blocking() or build_blocking_with(transport). Clients are cheap to clone.

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

Returned structs keep the server's snake_case field names. Money that the server sends as a decimal string (balance, rent sum in rent().state) becomes f64, numbers sent as strings are parsed, and maps that arrive as an empty PHP array [] become empty maps. payment_history().paylist arrives as a JSON array when its ids are 0, 1, 2…; it is kept, keyed "0", "1", ….

Error handling

Every call returns onlinesim_rs_api::Result<T>; the error is the enum Error.

VariantWhenData
Error::Api(ApiError)The API answered with an error code (also a wrong key, HTTP 456, and the rate limit, HTTP 429 TRY_AGAIN_LATER). is_no_number() for NO_NUMBER.code, message
Error::TransportNetwork error, request timeout, an HTTP error without an API code, or a body that is not JSON.message, status (None without a response), body (first 500 chars)
Error::Timeoutwait_code got no code within its timeout.message
Error::DecodeThe JSON does not have the expected shape.message
Error::ConfigThe client could not be built (bad base URL).message
use onlinesim_rs_api::Error;

match client.numbers().get("google", 44, &[]).await {
    Ok(tzid) => println!("ordered {tzid}"),
    Err(e) if e.is_no_number() => println!("no numbers now, try another country"),
    Err(Error::Api(e)) => eprintln!("{} {}", e.code, e.message), // e.g. WARNING_LOW_BALANCE
    Err(Error::Transport { status, body, .. }) => eprintln!("network: {status:?} {body}"),
    Err(e) => return Err(e),
}

message is the server's text when it sends one, otherwise a short English description of the code (error_message(code)), otherwise the code itself. Profile validation failures become ApiError with code VALIDATION_ERROR. Error::code() gives the API code of any error.