
Партнёры могут пользоваться тем же API Atli eSIM, на котором работают heyatli.com и виджет Atli. Для сайта, приложения или бота вы можете сделать собственные экраны: список направлений, выбор тарифа, оформление заказа и установку. Atli предоставляет каталог тарифов, обрабатывает платежи через свой аккаунт Stripe и выпускает eSIM.
API не использует API-ключи на уровне приложения. Аутентификация выполняется с помощью токенов отдельных пользователей. Ваш сервер входит в аккаунт каждого пользователя по уникальному ID устройства или через OAuth, а затем отправляет запросы к API от его имени. Каждому гостевому аккаунту нужен собственный ID устройства, и ваше приложение должно надёжно его хранить.
Sandbox, рабочая среда и файл OpenAPI
| Sandbox | Рабочая среда | |
|---|---|---|
| API | https://api-staging.heyatli.com | https://api.heyatli.com |
| Файл OpenAPI | https://api-staging.heyatli.com/openapi.yaml | https://api.heyatli.com/openapi.yaml |
| Страница оплаты | https://staging.heyatli.com/pay | https://heyatli.com/pay |
Sandbox работает с отдельными аккаунтами и тестовыми платежами, так что реальных списаний не происходит. eSIM в Sandbox выпускает тестовый оператор, поэтому установить их на телефон нельзя, а продажи в Sandbox никогда не приносят комиссии. Все примеры в этом гиде, которые создают аккаунты и заказы, используют эндпоинты Sandbox. Для рабочей среды смените базовый URL API на https://api.heyatli.com. Справочник на partners.heyatli.com/ru/dev/api переключается между двумя средами.

Ошибки API приходят в едином формате: code, message на английском и trace_id, который поможет службе поддержки Atli разобраться в проблеме. По code определяйте, как ваше приложение обработает ошибку и какое сообщение покажет. Поле message можно сохранять в логах.
Вход, расчёт цены, погашение ваучеров и синхронизация eSIM ограничены по частоте запросов, а отклонённый запрос возвращает 429 с Retry-After в секундах.
Вместо того чтобы писать отдельные HTTP-запросы, можно сгенерировать типизированный клиент API из спецификации OpenAPI:
docker run --rm -v "$PWD:/out" \
openapitools/openapi-generator-cli generate \
-i https://api.heyatli.com/openapi.yaml \
-g typescript-fetch -o /out/atli-sdkВместо typescript-fetch можно указать python, java, csharp, php или swift6. Для Go нужно go --additional-properties=enumClassPrefix=true.
Шаг 1: создайте пользователя
Для каждого пользователя можно создать гостевой аккаунт Atli без регистрации. Сгенерируйте для каждого из них уникальный UUID, например через crypto.randomUUID(), и надёжно сохраните его в записи этого пользователя.
Обращайтесь с ID устройства как с конфиденциальными учётными данными, потому что любой, у кого есть к нему доступ, может войти от имени этого пользователя.
Используйте его для входа со своего сервера. ID, которого Atli ещё не видел, создаёт гостевой аккаунт, а уже знакомый снова входит в существующий:
curl https://api-staging.heyatli.com/login \
-H 'Content-Type: application/json' \
-d '{ "device_id": "YOUR_DEVICE_ID" }'{
"token": "eyJhbGci…",
"refresh_token": "…",
"expires_in": 900,
"session_id": "…",
"user": { "id": "…", "email": null }
}Передавайте token как Authorization: Bearer YOUR_TOKEN в каждом вызове, которому нужен пользователь. Токен живёт 15 минут. Незадолго до истечения обновите его через POST /refresh с refresh_token. В ответе на обновление новый токен называется access_token, а не token. Убедитесь, что ваша интеграция читает правильное поле, иначе после истечения первого токена начнутся ошибки аутентификации. Сохраняйте refresh-токен после каждого обновления: оно возвращает новый токен и отзывает старый. Если потеряете оба, снова войдите с ID устройства.
Гость может покупать eSIM и пользоваться ими. Для некоторых eSIM, которыми с ним поделились, и некоторых ваучеров нужен настоящий аккаунт, и гостю API в них откажет с кодом вроде gift_sign_in_required. Чтобы добавить гостю адрес электронной почты, отправьте его токен и его device_id в POST /auth/email/otp, затем подтвердите адрес через POST /auth/email/verify. Вход через WhatsApp или Telegram точно так же превращает гостя в полноценный аккаунт. В обоих случаях имеющиеся у гостя eSIM и данные аккаунта сохраняются. Если не передать device_id или указать адрес, у которого уже есть аккаунт Atli, человек окажется в другом аккаунте.
Шаг 2: привяжите пользователя к партнёрскому коду
Привяжите каждого нового пользователя к своему коду до первого расчёта цены:
curl https://api-staging.heyatli.com/user/referral/redeem \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "code": "YOUR_PARTNER_CODE" }'Поле result показывает результат: ok означает, что пользователь успешно привязан, already, что у него уже есть пригласивший, notnew, что он уже совершал покупки, own указывает на ваш собственный реферальный код, а notfound означает, что код не найден. Привязать можно только человека без пригласившего и без прежних покупок, и только один раз. Делайте этот вызов сразу после создания пользователя.
Привязка постоянная. Если у вашего кода есть скидка, она применится к первой eSIM пользователя без повторной отправки кода. Что приносит привязка, рассказывает гид по партнёрской программе.
Шаг 3: покажите тарифы и получите расчёт цены
GET /explore/plans возвращает полный каталог с доступными направлениями, пакетами, ценами и объёмами трафика. Токен ему не нужен, поэтому ваш сервер может получить список тарифов ещё до того, как у кого-то появится аккаунт. Вызывайте его со своего сервера, потому что запросы из браузера с других сайтов API отклоняет с 403. Передайте currency и фильтруйте по destination (JP, europe) или category (local, regional, global):
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'id пакета и есть product_id, который вы покупаете. Запросите расчёт цены с store: true, чтобы получить quote_id:
curl https://api-staging.heyatli.com/plan/quote \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "product_id": "THE_PACKAGE_ID",
"currency": "EUR",
"store": true }'{
"subtotal_cents": 1500,
"total_discount_cents": 150,
"net_total_cents": 1350,
"currency": "EUR",
"quote_id": "…",
"expires_at": "…"
}Показывайте net_total_cents как итоговую цену. Срок действия сохранённого расчёта истекает через 30 минут, поэтому создавайте расчёт, когда пользователь переходит к оформлению заказа. У каждого пользователя одновременно хранится только один расчёт, и новый заменяет предыдущий.
target_esim_id пополняет eSIM, которая у пользователя уже есть. Без него тариф встаёт на eSIM пользователя по умолчанию. Если eSIM у него ещё нет или сеть eSIM по умолчанию такой тариф не продаёт, тариф встанет на новую eSIM. Для того, кто вошёл со своим аккаунтом Atli, поле new_esim в расчёте показывает, какой из вариантов сработает. В расчётах для гостей этого поля нет. Для гостя сравните eSIM в готовом заказе с теми, что перечисляет GET /esims, прежде чем показывать шаги установки.
auto_apply_best_voucher применяет самый ценный из подходящих ваучеров пользователя, а points_to_redeem позволяет пользователям списать баллы, которые в приложениях Atli отображаются как кредиты Atli. К заказу применяется только один вид скидки. Реферальная скидка по вашей ссылке идёт первой и берёт верх над любым ваучером, который расчёт выбрал бы сам. Ваучер, указанный в voucher_code, её заменяет, а если указать и ваучер, и referral_code, запрос завершится ошибкой cannot_combine_voucher_and_referral. Баллы засчитываются, только если не применяется ни ваучер, ни реферальная скидка.
Шаг 4: создайте заказ и примите оплату
Купите сохранённый расчёт по его quote_id. Тариф, скидки и цену заказ берёт из расчёта. Если итоговая сумма с тех пор изменилась больше чем на 1%, покупка завершится ошибкой price_changed, и расчёт придётся сделать заново.
Каждый расчёт можно использовать только для одного заказа. Если запрос на покупку случайно или после тайм-аута отправлен повторно, API вернёт существующий заказ и не создаст дубликат. Запрос также должен содержать idempotency_key, который предотвращает дублирование заказов, когда вы покупаете напрямую по product_id вместо сохранённого расчёта.
curl https://api-staging.heyatli.com/plan/purchase \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "quote_id": "THE_QUOTE_ID",
"idempotency_key": "A_NEW_UUID" }'{
"order_id": "…",
"client_secret": "pi_…_secret_…",
"sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
"key_id": "…",
"seal_signature": "…",
"options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
"options_signature": "…",
"total_amount_cents": 1350,
"status": "pending_payment"
}client_secret принадлежит Stripe PaymentIntent на аккаунте Atli. Смонтируйте с ним Payment Element от Stripe. Публикуемый ключ ваш сервер берёт из GET /stripe/config и передаёт странице вместе с client_secret. Не зашивайте ключ в код, потому что в Sandbox и рабочей среде ключи разные, и не запрашивайте его со страницы, потому что запросы из браузера с других сайтов API отклоняет:
const stripe = Stripe(publishable_key);
const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: window.location.href },
redirect: 'if_required',
});Передавайте client_secret только в сессию пользователя, который платит, и не пишите его в логи. Когда Stripe подтвердит платёж, попросите Atli выпустить eSIM:
curl https://api-staging.heyatli.com/plan/fulfill-payment \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "order_id": "THE_ORDER_ID" }'Если этот вызов не прошёл, не списывайте деньги повторно. Atli сам завершит оплаченный заказ.
Платёж проходит на аккаунт Stripe компании Atli, поэтому в выписке по карте вашего клиента будет имя Atli, а возвраты и споры по платежам обрабатывает Atli. Чтобы предложить Apple Pay и Google Pay в собственной форме, напишите на [email protected], когда у вашей интеграции появятся реальные продажи. Сохранённые карты работают через ту же покупку: добавьте payment_method_id, чтобы списать оплату с сохранённой карты, или save_card: true, чтобы сохранить новую карту на следующий раз.
Оплата на странице Atli
Боты в WhatsApp и Telegram, голосовые приложения и ИИ-ассистенты не могут показать платёжную форму Stripe. В таких интеграциях можно направить пользователей на страницу оплаты на стороне Atli. Соберите ссылку из трёх запечатанных значений, которые вернула покупка. Если покупка вернула ещё и options с options_signature, передайте их тоже, и над формой карты появится строка вроде «Plan for Japan» на языке, который вы указали в запросе:
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
type: 'payment_intent',
sealed_secret: order.sealed_secret,
key_id: order.key_id,
seal_signature: order.seal_signature,
...(order.options && {
options: Buffer.from(order.options).toString('base64url'),
options_signature: order.options_signature,
}),
}).toString();Страница оплаты показывает итоговую сумму заказа и поддерживает оплату картой, Apple Pay и Google Pay. Затем вызовите POST /plan/fulfill-payment с order_id и повторяйте вызов, пока заказ не станет оплаченным. Подтверждает платёж только этот вызов, потому что страница показывает ещё обрабатываемый платёж как успешный.
При создании платёжных ссылок соблюдайте следующие требования:
- Передавайте
sealed_secret,key_id,seal_signatureиoptions_signatureв точности такими, какими их вернул API, а кодирование возьмёт на себяURLSearchParams. Исключение составляетoptions: его нужно сначала закодировать в base64url, ничего не меняя в JSON. Никогда не вставляйте в ссылкуclient_secretв открытом виде. - Значения из Sandbox открываются только на
staging.heyatli.com/pay, а значения из рабочей среды открываются только наheyatli.com/pay. - По ссылке оплачивают чей-то заказ. Отправляйте её только владельцу аккаунта и не пишите в логи.
- Не храните ссылки впрок. Новая покупка отменяет предыдущий неоплаченный заказ вместе с его ссылкой.
brand=noneскрывает логотип Atli.langиthemeзадают язык и оформление страницы. Параметры перенаправления принимают только адресаhttpsна heyatli.com или его поддоменах, поэтому попросите человека вернуться в ваш чат после оплаты.- Кнопка «Отмена» на странице оставляет заказ открытым. Чтобы отменить его, вызовите
POST /orders/{id}/cancel.
Та же страница сохраняет карту без оплаты: подготовьте сохранение через POST /user/payment-methods/setup-intent, соберите ссылку с type, равным setup_intent, затем сохраните карту через POST /user/payment-methods/confirm. На partners.heyatli.com/ru/dev/payment-widget можно открыть тестовую оплату от имени нового гостя в Sandbox.
Шаг 5: покажите eSIM и ссылки для установки
Сразу после оплаты eSIM может быть ещё не готова к установке. Проверяйте статус заказа, пока в объекте esim не появятся данные для установки. На время обработки заказа показывайте подходящее сообщение о статусе:
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
-H 'Authorization: Bearer YOUR_TOKEN'{
"order_id": "…",
"status": "completed",
"esim": {
"id": "…",
"iccid": "…",
"lpa_address": "…",
"activation_code": "…",
"qr_string": "…"
}
}Статус paid подтверждает оплату, а completed означает, что eSIM и связанный с ней тариф подготовлены. Отрисуйте qr_string в виде QR-кода для установки с помощью второго устройства. Пользователям, которые устанавливают eSIM прямо на телефон, дайте ссылки для установки на iPhone или Android, которые открывают встроенную в телефон настройку eSIM:
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);
const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;Или дайте пользователю одну ссылку, которая делает всё это сразу: https://heyatli.com/my/esim, где в lpa стоит qr_string в base64url, а в iccid стоит ICCID этой eSIM. Страница показывает QR-код, обе ссылки для установки в одно касание и данные для ручного ввода, а если передан ICCID, то ещё и тарифы с остатком трафика. Аккаунт Atli для неё не нужен. Язык можно указать в пути, например /ja/my/esim, а для eSIM из Sandbox используйте staging.heyatli.com. Установить eSIM может любой, у кого есть ссылка, поэтому отправляйте её только тому, кто будет этой eSIM пользоваться.
Что пользователь увидит дальше, описано в наших гидах для iPhone и Android.
GET /esims перечисляет eSIM пользователя с данными для установки, тарифами и расходом трафика на момент последней синхронизации. POST /esims/{id}/sync запрашивает у сети актуальные цифры. Каждый запрос на синхронизацию обращается к оператору связи, и частота таких запросов ограничена. Запрашивайте свежие данные о расходе, когда они нужны, а не автоматически через фиксированные интервалы.
Вход через собственный аккаунт Atli
Для приложений, где люди пользуются собственным аккаунтом Atli, а не гостевым, у Atli есть OAuth 2.1: поток с кодом авторизации и PKCE (S256), ротация refresh-токенов и их отзыв. Пользователи проходят аутентификацию и разрешают доступ на heyatli.com, поэтому ваше приложение никогда не работает с их паролями от Atli.
Зарегистрируйте клиент на partners.heyatli.com/ru/dev/oauth/clients. У одного аккаунта может быть до 10 клиентов: public для мобильных приложений и confidential для сервера, который умеет хранить секрет. Веб-страница не может сама запросить токен, потому что API отклоняет запросы из браузера с других сайтов, если только Atli не отметил клиент как доверенный, поэтому дайте веб-приложению сервер и конфиденциальный клиент. Получать токены для API может только клиент, которым вы владеете, а чтобы владеть клиентом, в аккаунте должен быть адрес электронной почты.
Берите эндпоинты OAuth из метаданных сервера авторизации, а не прописывайте их в коде:
curl https://api.heyatli.com/.well-known/oauth-authorization-serverAccess-токены живут 15 минут. Каждое обновление возвращает новый refresh-токен, который должен заменить предыдущий в защищённом хранилище вашего приложения. Люди, которые входят через ваш клиент, смогут привязываться к вам автоматически, когда Atli включит это для вашего аккаунта. До тех пор привязывайте их сами через POST /user/referral/redeem с их access-токеном, как в шаге 2.
eSIM для раздачи, ваучеры и группы
Чтобы купить eSIM для раздачи, запросите расчёт с is_gift: true и задайте для max_claims значение от 1 до 20. Когда заказ будет выполнен, получите claim_url через GET /gifts/sent. POST /rewards/voucher/redeem добавляет ваучер в аккаунт пользователя. Участник Atli Group может запросить расчёт с group_id и купить с карты группы. На partners.heyatli.com/ru/dev/api каждый из этих сценариев разобран по шагам с кодом.
Частые вопросы
Есть ли у API Atli API-ключ?
Нужен ли мне собственный аккаунт Stripe?
GET /stripe/config, а данные карты уходят прямо в Stripe и не попадают ни на ваши серверы, ни в API.Можно ли платить через Apple Pay или Google Pay?
Как добавить трафик на eSIM, которая уже есть у пользователя?
target_esim_id, указывающим на эту eSIM, и купите его как обычно. Тариф встанет на уже имеющуюся у пользователя eSIM, так что устанавливать ничего нового не придётся. Если сеть этой eSIM такой пакет не продаёт, API откажет с кодом incompatible_esim.Что, если платёж прошёл, а мой вызов на выдачу eSIM не сработал?
GET /fulfillment/status-updates, пока не появится eSIM.Где тестировать без настоящих денег?
api-staging.heyatli.com. Платите тестовой картой Stripe 4242 4242 4242 4242 с любой будущей датой и любым CVC. Аккаунты в Sandbox свои.


