API と SDK
自分のアプリやサイトの画面に Atli を組み込めます。
Atli eSIM API
v1.0.0Buy 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
主な流れ
マップで流れを選ぶと手順が表示されます。
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-sdkAuthentication
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.