API dan SDK

API dan SDK

Bangun Atli ke dalam aplikasi atau situs Anda, di layar 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 dasar
https://api.heyatli.com
File OpenAPI
https://api.heyatli.com/openapi.yaml

Alur utama

Alur utama APIPengguna dibuat, mendapat penawaran harga, membeli dan membayar, mendapat eSIM, memasangnya, dan memantau pemakaian. Cabang opsional: akun sungguhan, menyimpan kartu, kartu grup, isi ulang, diskon, dan membeli untuk dibagikan, lalu membagikan tautan yang diklaim orang lain.
Buat penggunaPOST /login
Dapatkan penawaran hargaPOST /plan/quote
Beli dan bayarPOST /plan/purchase
Dapatkan eSIMGET /fulfillment/…
PasangGET /esims
Pantau pemakaianPOST /esims/{id}/sync
Akun sungguhanEmail, Telegram, WhatsApp
Simpan kartuStripe SetupIntent
Kartu grupgroup_id
Isi ulangtarget_esim_id
DiskonVoucher, kredit, rujukan
Beli untuk dibagikanis_gift, max_claims
Bagikan tautanGET /public/gifts/{code}
KlaimMungkin perlu akun sungguhan
Alur utamaOpsional

Pilih alur di peta untuk melihat langkah-langkahnya.

SDK

Buat klien siap pakai untuk bahasa Anda dari file 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 kode kesalahan umum
400

Permintaan tidak valid

401

Belum masuk atau sesi sudah berakhir

402

Pembayaran gagal

403

Pengguna ini tidak diizinkan melakukannya

404

Tidak ada, 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.