API v1

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

Каталог на 200+ стран и регионов. От вас — только запрос на выпуск: в ответ сразу приходит ссылка на страницу eSIM для вашего клиента и цена, по которой её продать. Установку, поддержку и продление берём на себя мы. Никаких договоров с операторами и своей биллинговой обвязки.

200+

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

1

запрос на выпуск — всё, что нужно от вас

$0

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

1. Как это устроено

  1. Ваш клиент покупает eSIM у вас — на сайте, в приложении или в офисе — по цене продажи, которую мы отдаём в каталоге (sale_price).

  2. Ваша программа отправляет один запрос POST /orders. Мы списываем вашу цену (price) с кошелька и сразу отвечаем ссылкой link.

  3. Вы отдаёте ссылку клиенту — письмом, в мессенджере, на экране. Пока профиль выпускается, страница пишет «готовится», потом показывает QR-код и инструкцию.

  4. Дальше всё на нашей стороне: установка, поддержка в чате на той же странице, продление трафика. Клиент по любым вопросам о своей eSIM пишет нам.

Разница между sale_price и price — ваш заработок. Обе цены задаём мы по договорённости с вами; считать у себя ничего не нужно.

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

Оставьте заявку — мы заведём вам доступ в консоль. Ключи вы выпускаете там сами, на странице «Ключи»: начните с песочницы, боевой выпустите, когда интеграция готова. Ключ показывается один раз — у нас он хранится только в виде хеша; потеряли — отзовите и выпустите новый. В консоли же меняются почта для входа и пароль, видны заказы, профили и счёт.

Все суммы в API — в долларах США (USD). Цены приходят уже посчитанными: price — сколько спишем с вашего кошелька, sale_price — за сколько продать клиенту. Кошелёк пополняется заранее, в консоли на странице «Счёт» — банковской картой, Apple Pay или Google Pay; деньги зачисляются сразу.

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

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

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

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

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

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

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

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

GET /ping Проверка ключа и режима
GET /balance Остаток на счёте
GET /countries Направления, по которым есть тарифы
GET /packages Каталог с ценой (price) и ценой продажи (sale_price)
GET /packages/{slug} Один тариф
POST /orders Выпустить eSIM — в ответе ссылка для клиента
GET /orders Ваши заказы
GET /orders/{id} Статус заказа и профиль, когда он готов
GET /esims Выпущенные профили
GET /esims/{iccid} Профиль: ссылка, данные для установки, расход
GET /esims/{iccid}/usage Свежий расход трафика
POST /esims/{iccid}/cancel Отменить неустановленный профиль
GET /webhook Текущий адрес уведомлений
PUT /webhook Задать адрес уведомлений — в ответе секрет подписи
POST /webhook/test Пробное уведомление
DELETE /webhook Отключить уведомления

Списки (/packages, /orders, /esims) отдаются страницами: параметры page и per_page (по умолчанию 25, не больше 100), сведения о страницах — в meta. Ключ песочницы видит только тестовые заказы и профили, боевой — только боевые.

{ "data": [ … ], "meta": { "page": 1, "per_page": 25, "total": 140, "last_page": 6 } }

5. Каталог и цены

GET /countries — направления (iso2, name, flag). GET /packages — тарифы; фильтры country (ISO2), region, type (local, regional, global). Тариф заказывается по slug.

curl "https://aloesim.am/api/v1/packages?country=GE&per_page=50" \ -H "Authorization: Bearer alo_test_…"
{ "data": [{ "slug": "esimaccess-ge-1-7", "title": "Грузия · 1 GB на 7 дн.", "type": "local", "country": { "iso2": "GE", "name": "Грузия" }, "data_bytes": 1073741824, "data_label": "1 GB", "is_unlimited": false, "is_daily": false, "validity_days": 7, "price": { "currency": "USD", "amount_cents": 673, "amount": 6.73, "per": "package" }, "sale_price": { "currency": "USD", "amount_cents": 990, "amount": 9.9, "per": "package" }, "network": { "speed": "4G/5G", "apn": "internet", "supports_topup": true, "operators": [ … ] } }], "meta": { "page": 1, "per_page": 50, "total": 12, "last_page": 1 } }

price — ваша цена: столько спишем с кошелька. sale_price — за сколько продать eSIM клиенту. Витринных скидок в этих ценах нет: они наши, для наших покупателей.

Пока в API только тарифы с лимитом трафика — безлимитные и посуточные появятся позже. Цены в каталоге — за весь пакет (per: "package"), а точные суммы приходят и в ответе на заказ.

6. Выпуск 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"}'
Поле Что это
package Обязательно. slug тарифа из каталога.
days Только для посуточных тарифов: на сколько дней. Сейчас таких в API нет — поле на будущее.
reference Необязательно. Ваш номер заказа, до 64 символов: вернётся в ответах и уведомлениях, по нему удобно сводить наши заказы со своими.
Idempotency-Key Обязательный заголовок, до 191 символа. Повтор с тем же ключом вернёт тот же заказ, а не выпустит вторую eSIM.

Заголовок Idempotency-Key — не формальность: запрос двигает деньги, а связь рвётся именно на таких запросах. Генерируйте ключ один раз на ваш заказ и повторяйте запрос с ним сколько нужно. Ответ — 201 на новый заказ, 200 на повтор:

{ "data": { "id": "01a0bbc2-1341-7298-a018-b1d28cfa1e0e", "status": "paid", "is_ready": false, "mode": "sandbox", "link": "https://aloesim.am/Ab3dE7…", "package": { "slug": "esimaccess-ge-1-7", "title": "Грузия · 1 GB на 7 дн.", "data_bytes": 1073741824, "validity_days": 7 }, "period_days": null, "quantity": 1, "price": { "currency": "USD", "amount_cents": 673, "amount": 6.73, "charged": false }, "sale_price": { "currency": "USD", "amount_cents": 990, "amount": 9.9 }, "reference": "my-order-1183", "esim": null, "failure_reason": null, "created_at": "2026-10-20T10:15:02+00:00", "completed_at": null } }

link — ссылка на страницу eSIM для вашего клиента. Она приходит сразу и не меняется: тот же адрес будет в GET /orders/{id}, в профиле и в уведомлении esim.ready. price — сколько списано с кошелька (в песочнице charged: false), sale_price — за сколько продать eSIM клиенту; обе цены зафиксированы на момент заказа.

Статус заказа: paid, provisioning, awaiting_provider — выпускается; completed — профиль готов; failed — выпустить не удалось, деньги вернулись на кошелёк, причина в failure_reason. Опрашивать не обязательно: ссылка работает сама, а о готовности и провале можно получать уведомления.

Когда профиль готов, is_ready становится true, а в esim приходят данные для установки. Они нужны, только если хотите показать QR-код и у себя — обычно достаточно ссылки. Статус профиля: issued — выпущен, active — установлен и работает, depleted — трафик закончился, expired — срок вышел, cancelled, suspended, revoked.

"esim": { "iccid": "8944084435147973198", "status": "issued", "mode": "sandbox", "link": "https://aloesim.am/Ab3dE7…", "activation": { "lpa": "LPA:1$rsp.example.com$K2-9F3A-71BC", "smdp_address": "rsp.example.com", "matching_id": "K2-9F3A-71BC", "confirmation_code": null, "apn": "internet" }, "usage": { "total_bytes": 1073741824, "used_bytes": 0, "remaining_bytes": 1073741824, "synced_at": null }, "activated_at": null, "expires_at": "2026-10-27T10:15:20+00:00" }

7. Страница eSIM по ссылке

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

  • Пока профиль выпускается — «eSIM готовится»; страница сама обновится, когда он будет готов.
  • Готовый профиль — QR-код, кнопка установки на iPhone в одно касание, данные для ручной установки, видеоинструкции для iPhone и Android, остаток трафика и срок действия.
  • Если выпуск не удался — сообщение, что проблема на нашей стороне, и чат с нашей поддержкой.
  • Чат поддержки — клиент пишет нам прямо со страницы: с установкой, связью и трафиком помогаем мы.
  • Продление — клиент сам докупает трафик или дни к той же eSIM и оплачивает на странице; переустанавливать ничего не нужно.
  • Ваше оформление — логотип, цвета и шрифты вашей компании; настраиваем по вашей просьбе. Ваших контактов на странице нет: по eSIM клиент обращается к нам.
  • Язык — русский, английский или армянский; клиент переключает сам.

Цен на странице нет: ни вашей, ни цены продажи. В песочнице на странице плашка «Тестовая eSIM», а продление отключено.

8. Профили

GET /esims и GET /esims/{iccid} — выпущенные профили; обращение — по ICCID. В профиле та же ссылка link, данные для установки и расход.

GET /esims/{iccid}/usage — свежий расход: спрашиваем поставщика прямо сейчас. Если он не ответил, придут последние известные цифры с отметкой synced_at.

POST /esims/{iccid}/cancel — отмена профиля, который ещё не установлен на телефон. Установленный отменить нельзя (esim_activated): у поставщика он уже израсходован. Деньги за отменённый профиль не возвращаются.

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

Необязательно: ссылка для клиента работает и без уведомлений. Задайте адрес, если хотите сразу узнавать, что выпуск не удался (order.failed) — деньги вернулись на ваш кошелёк, верните их клиенту, — и что профиль готов (esim.ready).

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"}'

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

// PHP $ok = hash_equals( hash_hmac('sha256', file_get_contents('php://input'), $secret), $_SERVER['HTTP_X_ALO_SIGNATURE'] ?? '' ); // Node.js (rawBody: the request body as received, before JSON parsing) const expected = Buffer.from(crypto.createHmac('sha256', secret).update(rawBody).digest('hex')); const got = Buffer.from(req.get('X-Alo-Signature') || ''); const ok = got.length === expected.length && crypto.timingSafeEqual(expected, got);

События: esim.ready — профиль выпущен, по ссылке уже QR-код; order.failed — выпуск окончательно не удался, деньги вернулись на кошелёк.

{ "event": "esim.ready", "sent_at": "2026-10-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", "link": "https://aloesim.am/Ab3dE7…", "status": "issued" } }
{ "event": "order.failed", "sent_at": "2026-10-20T10:16:05+00:00", "data": { "order_id": "01a0bbc2-…", "reference": "my-order-1183", "mode": "live", "reason": "…" } }

POST /webhook/test присылает пробное событие ping — так проверяют приём и подпись. GET /webhook показывает текущий адрес, DELETE /webhook отключает уведомления.

Отвечайте кодом 2xx: всё остальное мы считаем недоставкой и повторяем пять раз с нарастающей паузой. Адрес обязан быть https и вести наружу — на внутренние адреса мы не ходим.

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

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

{ "error": { "code": "insufficient_funds", "message": "Недостаточно средств на счёте." } }
Код HTTP Когда
missing_key / invalid_key / revoked_key 401 Ключ не передан, не найден или отозван
partner_blocked 403 Доступ закрыт — свяжитесь с менеджером
validation_failed 422 Поля запроса не прошли проверку — подробности в details
idempotency_key_required 400 Не передан Idempotency-Key при создании заказа
idempotency_key_conflict 409 Тот же Idempotency-Key с другими данными
idempotency_key_in_progress 409 Заказ с этим ключом ещё создаётся — повторите через секунду
insufficient_funds 402 На счёте не хватает денег
package_not_found 404 Тариф не найден или снят с продажи
days_required 422 Для посуточного тарифа не передан days
package_unavailable 409 Тарифа нет у поставщика прямо сейчас
not_found 404 Заказ, профиль или тариф (/packages/{slug}) не найден
esim_activated 409 Профиль уже установлен — отмена невозможна
cancel_refused 409 Поставщик отказал в отмене
provider_error 502 Поставщик не ответил — повторите позже
invalid_webhook_url 422 Адрес уведомлений не https или ведёт во внутреннюю сеть
webhook_not_set 422 Пробное уведомление без заданного адреса
rate_limited 429 Превышен лимит запросов
server_error 5xx Ошибка на нашей стороне — повторите позже

Ошибка проверки полей перечисляет, что не так с каждым полем:

{ "error": { "code": "validation_failed", "message": "…", "details": { "package": ["…"] } } }

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

11. Песочница

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

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

Нужен доступ?

Оставьте заявку — заведём вас как API-партнёра в тот же день. Ключи выпустите сами в консоли: сначала песочницу, потом боевой.

Кабинет API-партнёра Оставить заявку
ALO eSIM