API и SDK

API и SDK

Встройте Atli в своё приложение или сайт, на своих экранах.

Документация API

Atli eSIM API

v1.0.0

Buy and manage travel eSIMs: browse the catalogue, quote and buy a plan, install and track an eSIM, share one as a gift, and run a group account.

Paths are unversioned and the version of this document is in info.version, as on heyatli.com's published API. A breaking change will arrive under a new base URL rather than by changing what a path here means.

Базовый URL
https://api.heyatli.com
Файл OpenAPI
https://api.heyatli.com/openapi.yaml

Основные сценарии

Основные сценарии APIПользователь создаётся, получает расчёт цены, покупает и платит, получает eSIM, устанавливает её и следит за расходом. Необязательные ветки: настоящий аккаунт, сохранение карты, групповая карта, пополнение, скидки и покупка, чтобы поделиться, а затем ссылка, по которой кто-то получает eSIM.
Создать пользователяPOST /login
Получить расчёт ценыPOST /plan/quote
Купить и оплатитьPOST /plan/purchase
Получить eSIMGET /fulfillment/…
УстановитьGET /esims
Следить за расходомPOST /esims/{id}/sync
Настоящий аккаунтЭл. почта, Telegram, WhatsApp
Сохранить картуStripe SetupIntent
Групповая картаgroup_id
Пополнитьtarget_esim_id
СкидкиВаучеры, кредиты, рефералы
Купить, чтобы поделитьсяis_gift, max_claims
Поделиться ссылкойGET /public/gifts/{code}
ПолучитьМожет понадобиться настоящий аккаунт
Основной сценарийНеобязательно

Выберите сценарий на карте, чтобы увидеть его шаги.

SDK

Создайте готовый клиент для своего языка из нашего файла 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

Authentication

Most routes need a bearer token, issued by signing in through /login, /register or one of the /oauth/* flows, and refreshed at /refresh. Each operation states whether a token is required, read when sent, or ignored. Tokens identify a person, not an application; there is no application API key yet.

Enums

A field with a listed set of values may gain new ones: that ships as a minor version, never a new base URL. Treat a value you do not recognise as one you do not handle yet, not as invalid, and never let it fail parsing.

Errors

Every failed request answers with the same body: a stable code, an English message, a trace_id to quote when reporting a problem, and sometimes params. Branch on code and never on message.

Показать частые коды ошибок
400

Запрос недействителен

401

Нет входа в аккаунт, или срок его действия истёк

402

Платёж не прошёл

403

Этому пользователю это не разрешено

404

Этого нет, или это принадлежит не ему

429

Слишком много запросов: подождите время из Retry-After

500

На нашей стороне что-то пошло не так

Rate limits

Sign-in, registration, token refresh, email codes, voucher redemption, quotes, reviews and eSIM sync are throttled per caller. A refused request answers 429 with Retry-After in whole seconds, alongside X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Wait out Retry-After rather than retrying in a loop.

Language and currency

Send X-Locale (or Accept-Language, or ?lang=) to choose the language; the language answered in comes back as Content-Language, falling back to English. Prices follow the signed-in person's currency, or the currency a quote asks for.

Buying a plan

Quote first at /plan/quote, then pass the quote_id to /plan/purchase so the price you showed is the price charged. Send an idempotency_key on every purchase: the same key never buys twice.