API và SDK

API và SDK

Tích hợp Atli vào ứng dụng hoặc trang web của bạn, trên màn hình của riêng bạn.

Tài liệu 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 cơ sở
https://api.heyatli.com
Tệp OpenAPI
https://api.heyatli.com/openapi.yaml

Các luồng chính

Các luồng chính của APINgười dùng được tạo, nhận báo giá, mua và thanh toán, nhận eSIM, cài đặt và theo dõi mức sử dụng. Các nhánh tùy chọn: tài khoản thật, lưu thẻ, thẻ nhóm, nạp thêm, giảm giá và mua để chia sẻ, rồi chia sẻ liên kết để người khác nhận.
Tạo người dùngPOST /login
Nhận báo giáPOST /plan/quote
Mua và thanh toánPOST /plan/purchase
Nhận eSIMGET /fulfillment/…
Cài đặtGET /esims
Theo dõi mức sử dụngPOST /esims/{id}/sync
Tài khoản thậtEmail, Telegram, WhatsApp
Lưu thẻStripe SetupIntent
Thẻ nhómgroup_id
Nạp thêmtarget_esim_id
Giảm giáVoucher, tín dụng, giới thiệu
Mua để chia sẻis_gift, max_claims
Chia sẻ liên kếtGET /public/gifts/{code}
NhậnCó thể cần tài khoản thật
Luồng chínhTùy chọn

Chọn một luồng trên bản đồ để xem các bước.

SDK

Tạo ứng dụng khách sẵn dùng cho ngôn ngữ của bạn từ tệp OpenAPI của chúng tôi.

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.

Xem các mã lỗi thường gặp
400

Yêu cầu không hợp lệ

401

Chưa đăng nhập hoặc phiên đã hết hạn

402

Thanh toán không thành công

403

Người dùng này không được phép làm việc này

404

Không tồn tại hoặc không thuộc về họ

429

Quá nhiều yêu cầu, hãy chờ hết thời gian Retry-After

500

Đã xảy ra lỗi từ phía chúng tôi

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.