SDKs

PHP SDK

View as Markdown

The SimJuno PHP SDK provides typed access to the reseller and eSIM APIs. It includes authentication, retries, timeouts, API exceptions, and request and response classes.

The Composer package name is simjuno/sdk, and its source is available on GitHub.

Install

$composer require simjuno/sdk guzzlehttp/guzzle

The SDK requires PHP 8.1 or later and a PSR-18 HTTP client. The example installs Guzzle; you can use another PSR-18 implementation instead.

Create a client

Create an API key, store it in SIMJUNO_API_KEY, and initialize the client. Keep the key in server-side code.

1<?php
2
3use Simjuno\SimjunoClient;
4
5$apiKey = getenv('SIMJUNO_API_KEY');
6if ($apiKey === false || $apiKey === '') {
7    throw new RuntimeException('SIMJUNO_API_KEY is required');
8}
9
10$client = new SimjunoClient(apiKey: $apiKey);
11
12$balance = $client->reseller->balance();
13if ($balance === null) {
14    throw new RuntimeException('The balance request returned no response');
15}
16printf("Balance: $%.2f\n", $balance->balance / 10_000);

The SDK uses https://api.simjuno.com/v1 by default and sends the API key in the x-api-key header.

Work with eSIMs

The SDK follows the standard SimJuno integration flow. This example finds a plan, confirms its current details, and places an order:

1use Simjuno\Esim\Requests\OrderEsimRequest;
2use Simjuno\Esim\Types\OrderEsimRequestOrderListItem;
3
4$packageList = $client->esim->listPackages('spain');
5if ($packageList === null || $packageList->packages === []) {
6    throw new RuntimeException('No packages found');
7}
8$selectedPackage = $packageList->packages[0];
9$currentPackage = $client->esim->getPackage($selectedPackage->slug);
10if ($currentPackage === null) {
11    throw new RuntimeException('Package not found');
12}
13
14$orderRequest = new OrderEsimRequest([
15    'transactionId' => bin2hex(random_bytes(16)),
16    'orderList' => [
17        new OrderEsimRequestOrderListItem([
18            'slug' => $currentPackage->slug,
19            'count' => 1,
20        ]),
21    ],
22]);
23$order = $client->esim->orderEsim($orderRequest);
24if ($order === null) {
25    throw new RuntimeException('The order returned no response');
26}

Ordering eSIMs debits your reseller balance. If you retry the same order, reuse the same OrderEsimRequest so its transaction ID and order list do not change.

After receiving the ORDER_STATUS webhook, retrieve the provisioning details for each returned eSIM ID:

1if ($order->esimIds === []) {
2    throw new RuntimeException('The order returned no eSIM IDs');
3}
4$esim = $client->esim->getEsim($order->esimIds[0]);
5if ($esim === null) {
6    throw new RuntimeException('eSIM not found');
7}
8
9var_dump($esim->qrCodeUrl, $esim->shortUrl, $esim->ac);

Available methods

TaskMethod
Get reseller balance$client->reseller->balance()
List destinations$client->esim->listDestinations()
List plans for a destination$client->esim->listPackages($slug)
Get current plan details$client->esim->getPackage($slug)
Order eSIMs$client->esim->orderEsim($request)
List ordered eSIMs$client->esim->listEsims()
Get an eSIM$client->esim->getEsim($id)
Get current usage$client->esim->checkUsage($id)
List top-up plans$client->esim->listTopupPackages($slug)
Cancel an eligible eSIM$client->esim->cancelEsim($id)

Handle errors

Non-success responses throw SimjunoApiException. Transport and serialization failures throw SimjunoException:

1use Simjuno\Exceptions\SimjunoApiException;
2use Simjuno\Exceptions\SimjunoException;
3
4try {
5    $client->reseller->balance();
6} catch (SimjunoApiException $error) {
7    error_log($error->getCode() . ': ' . $error->getBody());
8    throw $error;
9} catch (SimjunoException $error) {
10    error_log($error->getMessage());
11    throw $error;
12}

Configure retries and timeouts

Requests retry up to two times by default for transport failures and 408, 429, and 5xx responses. Retries count toward your rate limit.

Set defaults when creating the client:

1$client = new SimjunoClient(
2    apiKey: $apiKey,
3    options: [
4        'maxRetries' => 3,
5        'timeout' => 30.0,
6    ],
7);

Override them for one request:

1$destinations = $client->esim->listDestinations(
2    options: [
3        'maxRetries' => 0,
4        'timeout' => 10.0,
5    ],
6);

Timeout options are supported with Guzzle and Symfony HttpClient. Other PSR-18 clients use their own timeout configuration.