Гид

Как интегрировать API Atli eSIM в свой сайт или приложение

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

Запрос curl к эндпоинту покупки в API Atli рядом с телефоном, на котором открыта страница оплаты Atli, и крылатый синий талисман Atli с телефоном возле чемодана

Партнёры могут пользоваться тем же API Atli eSIM, на котором работают heyatli.com и виджет Atli. Для сайта, приложения или бота вы можете сделать собственные экраны: список направлений, выбор тарифа, оформление заказа и установку. Atli предоставляет каталог тарифов, обрабатывает платежи через свой аккаунт Stripe и выпускает eSIM.

API не использует API-ключи на уровне приложения. Аутентификация выполняется с помощью токенов отдельных пользователей. Ваш сервер входит в аккаунт каждого пользователя по уникальному ID устройства или через OAuth, а затем отправляет запросы к API от его имени. Каждому гостевому аккаунту нужен собственный ID устройства, и ваше приложение должно надёжно его хранить.

Sandbox, рабочая среда и файл OpenAPI

SandboxРабочая среда
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
Файл OpenAPIhttps://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
Страница оплатыhttps://staging.heyatli.com/payhttps://heyatli.com/pay

Sandbox работает с отдельными аккаунтами и тестовыми платежами, так что реальных списаний не происходит. eSIM в Sandbox выпускает тестовый оператор, поэтому установить их на телефон нельзя, а продажи в Sandbox никогда не приносят комиссии. Все примеры в этом гиде, которые создают аккаунты и заказы, используют эндпоинты Sandbox. Для рабочей среды смените базовый URL API на https://api.heyatli.com. Справочник на partners.heyatli.com/ru/dev/api переключается между двумя средами.

Карта основных сценариев API Atli: создать пользователя, получить расчёт цены, купить и оплатить, получить eSIM, установить и следить за расходом, с необязательными ветками для настоящего аккаунта, сохранённых и групповых карт, пополнений, скидок и передачи eSIM другим людям

Ошибки API приходят в едином формате: code, message на английском и trace_id, который поможет службе поддержки Atli разобраться в проблеме. По code определяйте, как ваше приложение обработает ошибку и какое сообщение покажет. Поле message можно сохранять в логах.

Вход, расчёт цены, погашение ваучеров и синхронизация eSIM ограничены по частоте запросов, а отклонённый запрос возвращает 429 с Retry-After в секундах.

Вместо того чтобы писать отдельные HTTP-запросы, можно сгенерировать типизированный клиент API из спецификации OpenAPI:

Bash
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 ещё не видел, создаёт гостевой аккаунт, а уже знакомый снова входит в существующий:

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "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: привяжите пользователя к партнёрскому коду

Привяжите каждого нового пользователя к своему коду до первого расчёта цены:

Bash
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):

Bash
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'

id пакета и есть product_id, который вы покупаете. Запросите расчёт цены с store: true, чтобы получить quote_id:

Bash
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 }'
JSON
{
  "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 вместо сохранённого расчёта.

Bash
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" }'
JSON
{
  "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 отклоняет:

JavaScript
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:

Bash
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» на языке, который вы указали в запросе:

JavaScript
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 не появятся данные для установки. На время обработки заказа показывайте подходящее сообщение о статусе:

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "order_id": "…",
  "status": "completed",
  "esim": {
    "id": "…",
    "iccid": "…",
    "lpa_address": "…",
    "activation_code": "…",
    "qr_string": "…"
  }
}

Статус paid подтверждает оплату, а completed означает, что eSIM и связанный с ней тариф подготовлены. Отрисуйте qr_string в виде QR-кода для установки с помощью второго устройства. Пользователям, которые устанавливают eSIM прямо на телефон, дайте ссылки для установки на iPhone или Android, которые открывают встроенную в телефон настройку eSIM:

JavaScript
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 из метаданных сервера авторизации, а не прописывайте их в коде:

Bash
curl https://api.heyatli.com/.well-known/oauth-authorization-server

Access-токены живут 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-ключ?
Нет. Токены идентифицируют человека, а не приложение. Ваш сервер входит в аккаунт каждого пользователя по ID устройства или через OAuth, а затем вызывает API от его имени.
Нужен ли мне собственный аккаунт Stripe?
Нет. Заказы оплачиваются на аккаунт Stripe компании Atli. Ваша форма использует публикуемый ключ Atli из GET /stripe/config, а данные карты уходят прямо в Stripe и не попадают ни на ваши серверы, ни в API.
Можно ли платить через Apple Pay или Google Pay?
Да. Страница оплаты Atli предлагает оба способа. Чтобы включить их в собственной форме Stripe, напишите на [email protected], когда у вашей интеграции будут реальные продажи.
Как добавить трафик на eSIM, которая уже есть у пользователя?
Запросите расчёт нового пакета с target_esim_id, указывающим на эту eSIM, и купите его как обычно. Тариф встанет на уже имеющуюся у пользователя eSIM, так что устанавливать ничего нового не придётся. Если сеть этой eSIM такой пакет не продаёт, API откажет с кодом incompatible_esim.
Что, если платёж прошёл, а мой вызов на выдачу eSIM не сработал?
Не списывайте деньги повторно. Atli сам доводит оплаченный заказ до конца, поэтому продолжайте опрашивать GET /fulfillment/status-updates, пока не появится eSIM.
Где тестировать без настоящих денег?
В Sandbox по адресу api-staging.heyatli.com. Платите тестовой картой Stripe 4242 4242 4242 4242 с любой будущей датой и любым CVC. Аккаунты в Sandbox свои.