API v1

Продавайте eSIM под своим брендом

Каталог из 3000 тарифов по 199 направлениям, выпуск профиля за секунды и статусы в реальном времени. Никаких договоров с операторами и своей биллинговой обвязки: вы отдаёте клиенту QR-код, остальное на нас.

199

направлений в каталоге

~15 с

от заказа до готового профиля

$0

стоит песочница

1. С чего начать

Напишите нам — мы заведём вас как партнёра и выпустим два ключа: для песочницы и боевой. Ключи приходят письмом и показываются один раз: у нас они хранятся только в виде хеша.

Цены в каталоге — ваши: они заводятся по договорённости и приходят уже посчитанными. Ничего умножать у себя не нужно.

Начинайте с песочницы. Она выпускает настоящие по формату профили, но не обращается к поставщику и не списывает деньги, поэтому пробовать можно сколько угодно.

Базовый адрес: https://aloesim.am/api/v1

2. Аутентификация

Ключ передаётся заголовком. В строке запроса его передавать нельзя — адреса оседают в журналах прокси и в отчётах об ошибках.

curl https://aloesim.am/api/v1/ping \ -H "Authorization: Bearer alo_live_…"

Режим виден прямо в ключе: alo_live_ — боевой, alo_test_ — песочница. Это не украшение: самая частая авария интеграции — боевой ключ, случайно оставшийся в тестовом стенде.

{ "data": { "status": "ok", "mode": "sandbox", "partner": { "id": 42, "company": "Travel Co" }, "key": { "name": "основной сервер", "prefix": "alo_test_9f2c1ab4" }, "server_time": "2026-09-20T10:15:00+00:00" } }

3. Что можно вызывать

GET /ping Проверка ключа и режима
GET /balance Остаток на счёте и ваша наценка
GET /countries Направления, по которым есть тарифы
GET /packages Каталог с вашими ценами. Фильтры: country, region, type
GET /packages/{slug} Один тариф
POST /orders Выпустить eSIM
GET /orders Ваши заказы
GET /orders/{id} Статус заказа и профиль, когда он готов
GET /esims Выпущенные профили
GET /esims/{iccid} Профиль: LPA, адрес SM-DP+, код активации
GET /esims/{iccid}/usage Свежий расход трафика
POST /esims/{iccid}/cancel Отменить неустановленный профиль
PUT /webhook Куда слать уведомления
POST /webhook/test Пробное уведомление

4. Выпуск eSIM

Выпуск асинхронный. Заказ создаётся сразу, профиль появляется через несколько секунд — забирайте его уведомлением или опросом заказа.

Заголовок Idempotency-Key обязателен. Запрос двигает деньги, а связь рвётся именно на таких запросах: повтор с тем же ключом вернёт тот же заказ, а не выпустит вторую eSIM.

curl -X POST https://aloesim.am/api/v1/orders \ -H "Authorization: Bearer alo_test_…" \ -H "Idempotency-Key: 7f3a9c02-order-1183" \ -H "Content-Type: application/json" \ -d '{"package":"esimaccess-ge-1-7","reference":"my-order-1183"}'
{ "data": { "id": "01a0bbc2-1341-7298-a018-b1d28cfa1e0e", "status": "paid", "is_ready": false, "mode": "sandbox", "package": { "slug": "esimaccess-ge-1-7", "data_bytes": 1073741824, "validity_days": 7 }, "price": { "currency": "USD", "amount_cents": 673, "charged": false }, "reference": "my-order-1183", "esim": null } }

Когда профиль готов, is_ready становится true, а в esim приходит строка LPA. QR-код рисуйте у себя: картинка с нашего домена — лишняя зависимость вашего приложения от нашей доступности.

"esim": { "iccid": "8944084435147973198", "status": "issued", "activation": { "lpa": "LPA:1$rsp.example.com$K2-9F3A-71BC", "smdp_address": "rsp.example.com", "matching_id": "K2-9F3A-71BC", "apn": "internet" }, "usage": { "total_bytes": 1073741824, "used_bytes": 0, "remaining_bytes": 1073741824 } }

Для посуточных тарифов (is_daily: true) передавайте days: цена в каталоге указана за день, поле price.per говорит, что именно вы умножаете.

5. Уведомления

Чтобы узнать о готовности за секунды, опрашивать пришлось бы каждую секунду. Вместо этого задайте адрес — и мы сами сообщим.

curl -X PUT https://aloesim.am/api/v1/webhook \ -H "Authorization: Bearer alo_live_…" \ -H "Content-Type: application/json" \ -d '{"url":"https://partner.example/hooks/alo"}'

В ответ придёт секрет — он показывается один раз. Каждое наше сообщение подписано им в заголовке X-Alo-Signature: HMAC-SHA256 от тела запроса. Проверяйте подпись обязательно, иначе на этот адрес сможет написать кто угодно.

{ "event": "esim.ready", "sent_at": "2026-09-20T10:15:31+00:00", "data": { "order_id": "01a0bbc2-…", "reference": "my-order-1183", "mode": "live", "iccid": "8944084435147973198", "lpa": "LPA:1$rsp.example.com$K2-9F3A-71BC", "status": "issued" } }

События: esim.ready, esim.status_changed, order.failed. Отвечайте кодом 2xx: всё остальное мы считаем недоставкой и повторяем пять раз с нарастающей паузой.

Адрес обязан быть https и вести наружу — на внутренние адреса мы не ходим.

6. Ошибки и лимиты

Ошибка всегда приходит одинаково: машинный код в error.code и человеческое пояснение рядом. Разбирайте код, а не текст — текст мы можем переписать.

{ "error": { "code": "insufficient_funds", "message": "Недостаточно средств на счёте." } }
Код HTTP Когда
missing_key / invalid_key / revoked_key 401 Ключ не передан, не найден или отозван
partner_blocked 403 Доступ закрыт — свяжитесь с менеджером
idempotency_key_required 400 Не передан Idempotency-Key при создании заказа
idempotency_key_conflict 409 Тот же ключ с другими данными
insufficient_funds 402 На счёте не хватает денег
package_not_found 404 Тариф не найден или снят с продажи
package_unavailable 409 Тарифа нет у поставщика прямо сейчас
esim_activated 409 Профиль уже установлен — отмена невозможна

Лимит — 120 запросов в минуту на ключ. Превышение отвечает кодом 429 и заголовком Retry-After. Нужно больше — скажите, поднимем.

7. Песочница

Ключ alo_test_ работает с тем же каталогом и теми же ценами, но заказ по нему не уходит поставщику и не списывает деньги. Профиль приходит настоящий по формату — с ICCID и строкой LPA, — так что вы отладите весь путь, включая показ QR-кода клиенту.

Песочница и бой не пересекаются: тестовым ключом не видно боевых заказов, боевым — тестовых. Перепутать ключи и потратить деньги на проверке невозможно.

Нужен ключ?

Напишите нам — заведём партнёра и вышлем ключ песочницы в тот же день. Боевой выдаём после того, как вы отладите интеграцию.

Кабинет партнёра