API dan SDK

API dan SDK

Bina Atli ke dalam aplikasi atau laman web anda, pada skrin anda sendiri.

Dokumentasi 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 asas
https://api.heyatli.com
Fail OpenAPI
https://api.heyatli.com/openapi.yaml

Aliran utama

Aliran utama APIPengguna dicipta, mendapat sebut harga, membeli dan membayar, mendapat eSIM, memasangnya dan menjejak penggunaan. Cabang pilihan: akaun sebenar, menyimpan kad, kad kumpulan, tambah nilai, diskaun dan membeli untuk dikongsi, kemudian berkongsi pautan yang dituntut oleh orang lain.
Cipta penggunaPOST /login
Dapatkan sebut hargaPOST /plan/quote
Beli dan bayarPOST /plan/purchase
Dapatkan eSIMGET /fulfillment/…
PasangGET /esims
Jejak penggunaanPOST /esims/{id}/sync
Akaun sebenarE-mel, Telegram, WhatsApp
Simpan kadStripe SetupIntent
Kad kumpulangroup_id
Tambah nilaitarget_esim_id
DiskaunBaucar, kredit, rujukan
Beli untuk dikongsiis_gift, max_claims
Kongsi pautanGET /public/gifts/{code}
TuntutMungkin memerlukan akaun sebenar
Aliran utamaPilihan

Pilih aliran pada peta untuk melihat langkahnya.

SDK

Jana klien sedia guna untuk bahasa anda daripada fail OpenAPI kami.

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.

Lihat kod ralat biasa
400

Permintaan tidak sah

401

Log masuk tiada atau telah tamat tempoh

402

Pembayaran gagal

403

Pengguna ini tidak dibenarkan berbuat demikian

404

Ia tidak wujud, atau bukan milik pengguna ini

429

Terlalu banyak permintaan, jadi tunggu selama Retry-After

500

Ada masalah di pihak kami

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.