onlinesim-java-api

Java 11+ client for the OnlineSim API — SMS numbers, rent, account and free numbers.

Install

Java 11 or newer. HTTP goes through the JDK's java.net.http.HttpClient; the only dependency is Gson.

implementation 'ru.onlinesim:onlinesim-api:2.1.1'

Quick start

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

import ru.onlinesim.Balance;
import ru.onlinesim.NumberOrder;
import ru.onlinesim.OnlineSim;

public class QuickStart {
  public static void main(String[] args) {
    OnlineSim client = new OnlineSim(System.getenv("ONLINESIM_KEY"));

    Balance balance = client.user().balance();
    System.out.println("available: " + (balance.balance() - Math.max(balance.zbalance(), 0)) + " USD");

    NumberOrder order = client.numbers().getWithNumber("google", 44);
    System.out.println("enter " + order.number() + " in the app");

    // Polls every 5 s for up to 10 min, then closes the operation.
    String code = client.numbers().waitCode(order.tzid());
    System.out.println("code: " + code);
  }
}

Client options

import java.time.Duration;
import ru.onlinesim.OnlineSim;

OnlineSim client = OnlineSim.builder()
    .apiKey("your-api-key")
    .lang("en")
    .timeout(Duration.ofSeconds(15))
    .build();
OptionTypeDefaultDescription
apiKeyString—Sent as Authorization: Bearer <apiKey>, never in the URL. Not needed for tariffs and free numbers.
baseUrlStringhttps://onlinesim.host/api/API base; trailing slash optional.
langStringenLanguage of server texts (lang query parameter).
devIdString—Partner developer id (dev_id), sent only when set.
timeoutDuration30 sPer-request timeout.
transportTransportHttpTransportHTTP transport: your own HttpClient (proxy, TLS), or a fake in tests.

new OnlineSim(apiKey) uses the defaults. The client is immutable and thread-safe; share one instance.

Sections: client.numbers(), client.rent(), client.user(), client.free(). Webhook bodies are parsed by the static OnlineSim.parseWebhook.

Durations (timeout, the waitCode interval) are java.time.Duration. Response objects are immutable, with record-style accessors named after the server's fields (webhook_url → webhookUrl()). Two things are normalised: money that the server sends as a decimal string (balance, rent sum in rent().state()) becomes a double, and maps that arrive as an empty PHP array [] become empty maps. paymentHistory().paylist() keeps a paylist that arrives as a JSON array (ids 0, 1, 2…), keyed by index. Collections are never null.

A proxy or a custom TLS setup goes through your own HttpClient:

import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.http.HttpClient;
import ru.onlinesim.HttpTransport;
import ru.onlinesim.OnlineSim;

HttpClient http = HttpClient.newBuilder()
    .proxy(ProxySelector.of(new InetSocketAddress("proxy.local", 3128)))
    .build();
OnlineSim client = OnlineSim.builder().apiKey("your-api-key").transport(new HttpTransport(http)).build();

Error handling

Every exception is unchecked and extends OnlineSimException.

ClassWhenFields
ApiExceptionThe API answered with an error code (also a wrong key, HTTP 456, and the rate limit, HTTP 429 TRY_AGAIN_LATER).getCode(), getMessage()
NoNumberExceptionNO_NUMBER: no number right now. Subclass of ApiException.getCode(), getMessage()
TransportExceptionNetwork error, request timeout, or a body that is not JSON.getStatus() (null without a response), getBody() (first 500 chars)
WaitTimeoutExceptionwaitCode got no code within its timeout.—
import ru.onlinesim.ApiException;
import ru.onlinesim.NoNumberException;
import ru.onlinesim.TransportException;

try {
  client.numbers().get("google", 44);
} catch (NoNumberException e) {
  // try another country or later
} catch (ApiException e) {
  System.err.println(e.getCode() + ": " + e.getMessage()); // e.g. WARNING_LOW_BALANCE
} catch (TransportException e) {
  System.err.println("network " + e.getStatus() + " " + e.getBody());
}

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