
Mitra bisa memakai API eSIM Atli yang sama dengan yang menjalankan heyatli.com dan widget Atli. Anda bisa membangun sendiri tampilan daftar destinasi, pemilihan paket, checkout, dan pemasangan untuk situs web, aplikasi, atau bot. Atli menyediakan katalog paket, memproses pembayaran lewat akun Stripe-nya, dan menerbitkan eSIM.
API ini tidak memakai API key tingkat aplikasi. Autentikasi ditangani melalui token milik tiap pengguna. Server Anda login atas nama setiap pengguna dengan ID perangkat yang unik atau lewat OAuth, lalu mengirim permintaan API sebagai pengguna tersebut. Setiap akun tamu memerlukan ID perangkatnya sendiri, dan aplikasi Anda harus menyimpannya dengan aman.
Sandbox, produksi, dan file OpenAPI
| Sandbox | Produksi | |
|---|---|---|
| API | https://api-staging.heyatli.com | https://api.heyatli.com |
| File OpenAPI | https://api-staging.heyatli.com/openapi.yaml | https://api.heyatli.com/openapi.yaml |
| Halaman pembayaran | https://staging.heyatli.com/pay | https://heyatli.com/pay |
Sandbox memakai akun terpisah dan pembayaran uji, sehingga tidak ada tagihan sungguhan. eSIM Sandbox berasal dari operator uji, jadi tidak bisa dipasang di ponsel, dan penjualan di Sandbox tidak pernah menghasilkan komisi. Semua contoh pembuatan akun dan pesanan di panduan ini memakai endpoint Sandbox. Untuk produksi, ganti base URL API ke https://api.heyatli.com. Referensi di partners.heyatli.com/id/dev/api bisa berpindah di antara keduanya.

Error API selalu memakai format yang sama: code, message berbahasa Inggris, dan trace_id untuk menelusuri masalah bersama tim dukungan Atli. Gunakan code untuk menentukan cara aplikasi Anda menangani error dan pesan yang ditampilkannya. Field message bisa disimpan di log Anda.
Login, penawaran harga, penukaran voucher, dan sinkronisasi eSIM dikenai rate limit. Permintaan yang ditolak dijawab dengan 429 dan Retry-After dalam satuan detik.
Daripada menulis permintaan HTTP satu per satu, Anda bisa membuat typed client untuk API dari spesifikasi 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-sdkGanti typescript-fetch dengan python, java, csharp, php, atau swift6. Untuk Go, gunakan go --additional-properties=enumClassPrefix=true.
Langkah 1: buat pengguna
Anda bisa membuat akun tamu Atli untuk setiap pengguna tanpa mengharuskan mereka mendaftar. Buat satu UUID unik per pengguna, misalnya dengan crypto.randomUUID(), lalu simpan dengan aman di data akun pengguna itu.
Perlakukan ID perangkat sebagai kredensial rahasia, karena siapa pun yang bisa mengaksesnya dapat masuk sebagai pengguna tersebut.
Login dengan ID itu dari server Anda. ID yang belum pernah dilihat Atli akan membuat akun tamu, dan ID yang sudah dikenal masuk kembali ke akun yang sama:
curl https://api-staging.heyatli.com/login \
-H 'Content-Type: application/json' \
-d '{ "device_id": "YOUR_DEVICE_ID" }'{
"token": "eyJhbGci…",
"refresh_token": "…",
"expires_in": 900,
"session_id": "…",
"user": { "id": "…", "email": null }
}Kirim token sebagai Authorization: Bearer YOUR_TOKEN di setiap panggilan yang memerlukan pengguna. Token berlaku 15 menit. Perbarui sesaat sebelum habis dengan POST /refresh dan refresh_token. Respons refresh menamai token barunya access_token, bukan token. Pastikan integrasi Anda membaca field yang benar agar autentikasi tidak gagal saat token pertama kedaluwarsa. Simpan refresh token setiap kali, karena setiap refresh mengembalikan refresh token baru dan menonaktifkan yang lama. Jika keduanya hilang, login lagi dengan ID perangkat.
Tamu bisa membeli dan memakai eSIM. Sebagian eSIM yang dibagikan dan sebagian voucher memerlukan akun sungguhan, dan API menolaknya untuk tamu dengan kode seperti gift_sign_in_required. Untuk menambahkan email ke akun tamu, kirim token tamu itu beserta device_id-nya ke POST /auth/email/otp, lalu konfirmasi dengan POST /auth/email/verify. Login lewat WhatsApp atau Telegram bisa mengubah akun tamu menjadi akun sungguhan dengan cara yang sama. Dalam kedua kasus, eSIM dan data akun yang sudah dimiliki tamu tetap tersimpan. Jika device_id tidak dikirim, atau email yang dipakai sudah punya akun Atli, orang itu akan masuk ke akun yang berbeda.
Langkah 2: hubungkan pengguna ke kode mitra Anda
Hubungkan setiap pengguna baru ke kode Anda sebelum penawaran harga pertamanya:
curl https://api-staging.heyatli.com/user/referral/redeem \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "code": "YOUR_PARTNER_CODE" }'Field result menunjukkan hasilnya: ok berarti pengguna berhasil dihubungkan, already berarti ia sudah punya pemberi referral, notnew berarti ia pernah melakukan pembelian sebelumnya, own menandakan kode referral Anda sendiri, dan notfound berarti kode tidak ditemukan. Hanya orang tanpa pemberi referral dan tanpa pembelian sebelumnya yang bisa dihubungkan, dan hanya sekali. Lakukan panggilan ini tepat setelah Anda membuat pengguna.
Hubungan ini permanen. Jika kode Anda punya diskon, eSIM pertama pengguna itu mendapat diskon tersebut tanpa Anda perlu mengirim kode lagi. Panduan program afiliasi menjelaskan penghasilan dari hubungan ini.
Langkah 3: tampilkan paket dan minta penawaran harga
GET /explore/plans mengembalikan katalog lengkap, termasuk destinasi yang tersedia, paket, harga, dan kuota data. Endpoint ini tidak memerlukan token, jadi server Anda bisa menampilkan paket sebelum ada yang punya akun. Panggil endpoint ini dari server Anda, karena API menolak permintaan browser dari situs web lain dengan 403. Kirim currency, lalu saring dengan destination (JP, europe) atau category (local, regional, global):
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'id sebuah paket adalah product_id yang Anda beli. Minta penawaran harganya dengan store: true untuk mendapatkan quote_id:
curl https://api-staging.heyatli.com/plan/quote \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "product_id": "THE_PACKAGE_ID",
"currency": "EUR",
"store": true }'{
"subtotal_cents": 1500,
"total_discount_cents": 150,
"net_total_cents": 1350,
"currency": "EUR",
"quote_id": "…",
"expires_at": "…"
}Tampilkan net_total_cents sebagai harga akhir. Penawaran tersimpan kedaluwarsa setelah 30 menit, jadi buat penawaran saat pengguna lanjut ke checkout. Setiap pengguna hanya memegang satu penawaran tersimpan dalam satu waktu, dan penawaran baru menggantikan yang terakhir.
target_esim_id mengisi ulang eSIM yang sudah dimiliki pengguna. Tanpa parameter itu, paket masuk ke eSIM default pengguna. Jika ia belum punya eSIM, atau jaringan eSIM default-nya tidak menjual paket itu, paket masuk ke eSIM baru. Untuk orang yang masuk dengan akun Atli miliknya sendiri, new_esim pada penawaran menunjukkan mana yang terjadi. Penawaran untuk tamu tidak menyertakannya. Untuk tamu, bandingkan eSIM pada pesanan yang sudah selesai dengan daftar dari GET /esims sebelum Anda menampilkan langkah pemasangan.
auto_apply_best_voucher menerapkan voucher bernilai tertinggi yang bisa dipakai pengguna, sementara points_to_redeem memungkinkan pengguna menukarkan poinnya, yang di aplikasi Atli tampil sebagai kredit Atli. Satu pesanan hanya memakai satu jenis diskon. Diskon referral dari tautan Anda didahulukan dan mengalahkan voucher apa pun yang akan dipilih penawaran harga dengan sendirinya. Voucher yang disebut lewat voucher_code menggantikannya, dan menyebut voucher sekaligus referral_code akan gagal dengan cannot_combine_voucher_and_referral. Poin hanya dihitung jika voucher maupun diskon referral tidak berlaku.
Langkah 4: buat pesanan dan terima pembayaran
Beli penawaran tersimpan dengan quote_id-nya. Pesanan mengambil paket, diskon, dan harganya dari penawaran itu. Jika total harganya bergeser lebih dari 1% sejak penawaran dibuat, pembelian gagal dengan price_changed dan Anda perlu meminta penawaran baru.
Setiap penawaran hanya bisa dipakai untuk satu pesanan. Jika permintaan pembelian terkirim lagi karena tidak sengaja atau setelah timeout, API mengembalikan pesanan yang sudah ada dan tidak membuat duplikat. Permintaan juga harus menyertakan idempotency_key, yang mencegah pesanan ganda saat Anda membeli langsung dengan product_id tanpa penawaran tersimpan.
curl https://api-staging.heyatli.com/plan/purchase \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "quote_id": "THE_QUOTE_ID",
"idempotency_key": "A_NEW_UUID" }'{
"order_id": "…",
"client_secret": "pi_…_secret_…",
"sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
"key_id": "…",
"seal_signature": "…",
"options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
"options_signature": "…",
"total_amount_cents": 1350,
"status": "pending_payment"
}client_secret itu milik PaymentIntent Stripe di akun Atli. Pasang Payment Element Stripe dengannya. Server Anda membaca publishable key dari GET /stripe/config lalu menyerahkannya ke halaman bersama client_secret. Jangan menuliskan kunci itu langsung di kode, karena kuncinya berbeda antara Sandbox dan produksi, dan jangan mengambilnya dari halaman, karena API menolak permintaan browser dari situs web lain:
const stripe = Stripe(publishable_key);
const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: window.location.href },
redirect: 'if_required',
});Berikan client_secret hanya ke sesi pengguna yang sedang membayar, dan jangan sampai masuk ke log Anda. Setelah Stripe mengonfirmasi pembayaran, minta Atli menerbitkan eSIM:
curl https://api-staging.heyatli.com/plan/fulfill-payment \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "order_id": "THE_ORDER_ID" }'Jika panggilan itu gagal, jangan menagih lagi. Atli menyelesaikan pesanan yang sudah dibayar dengan sendirinya.
Pembayaran ditagih lewat akun Stripe Atli, jadi nama Atli yang tertera di tagihan kartu pelanggan Anda, dan refund serta sengketa pembayaran ditangani Atli. Untuk menawarkan Apple Pay dan Google Pay di formulir Anda sendiri, kirim email ke [email protected] setelah integrasi Anda menghasilkan penjualan nyata. Kartu tersimpan memakai panggilan pembelian yang sama: tambahkan payment_method_id untuk menagih kartu tersimpan, atau save_card: true untuk menyimpan kartu baru bagi pembelian berikutnya.
Membayar di halaman pembayaran Atli
Bot WhatsApp atau Telegram, aplikasi suara, dan asisten AI tidak bisa menampilkan formulir pembayaran Stripe. Untuk integrasi seperti itu, Anda bisa mengarahkan pengguna ke halaman pembayaran yang di-hosting Atli. Susun tautan dari tiga nilai tersegel yang dikembalikan oleh pembelian. Jika pembelian juga mengembalikan options dan options_signature, teruskan keduanya, dan halaman itu menampilkan baris seperti “Plan for Japan” di atas formulir kartu dalam bahasa yang ditentukan oleh permintaan Anda:
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
type: 'payment_intent',
sealed_secret: order.sealed_secret,
key_id: order.key_id,
seal_signature: order.seal_signature,
...(order.options && {
options: Buffer.from(order.options).toString('base64url'),
options_signature: order.options_signature,
}),
}).toString();Halaman pembayaran menampilkan total pesanan dan mendukung pembayaran dengan kartu, Apple Pay, dan Google Pay. Lalu panggil POST /plan/fulfill-payment dengan order_id, dan ulangi sampai pesanan berstatus dibayar. Hanya panggilan itu yang mengonfirmasi pembayaran, karena halaman tersebut menampilkan pembayaran yang masih diproses sebagai berhasil.
Ikuti ketentuan berikut saat membuat tautan pembayaran:
- Teruskan
sealed_secret,key_id,seal_signature, danoptions_signaturepersis seperti yang dikembalikan API, danURLSearchParamsmenangani encoding-nya.optionsadalah pengecualiannya: encode dulu dengan base64url tanpa mengubah JSON-nya. Jangan pernah memasukkanclient_secretpolos ke dalam tautan. - Nilai Sandbox hanya bisa dibuka di
staging.heyatli.com/pay, dan nilai produksi hanya bisa dibuka diheyatli.com/pay. - Tautan itu membayar pesanan milik seseorang. Kirimkan hanya kepada pemilik akun dan jangan sampai masuk ke log.
- Jangan menyimpan tautan untuk dipakai nanti. Pembelian baru membatalkan pesanan tertunda sebelumnya beserta tautannya.
brand=nonemenyembunyikan logo Atli.langdanthememengatur bahasa dan tampilan halaman. Parameter redirect hanya menerima alamathttpsdi heyatli.com atau subdomainnya, jadi minta orang itu kembali ke chat Anda setelah membayar.- Tombol batal di halaman itu membiarkan pesanan tetap terbuka. Untuk membatalkannya, panggil
POST /orders/{id}/cancel.
Halaman yang sama juga bisa menyimpan kartu tanpa pembayaran: buat setup-nya dengan POST /user/payment-methods/setup-intent, susun tautan dengan type bernilai setup_intent, lalu simpan kartunya dengan POST /user/payment-methods/confirm. partners.heyatli.com/id/dev/payment-widget bisa membuka pembayaran uji dengan akun tamu Sandbox yang baru.
Langkah 5: tampilkan eSIM dan tautan pemasangannya
eSIM mungkin belum bisa dipasang tepat setelah pembayaran. Periksa status pesanan sampai objek esim memuat detail pemasangan. Selama pesanan diproses, tampilkan pesan status yang sesuai:
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
-H 'Authorization: Bearer YOUR_TOKEN'{
"order_id": "…",
"status": "completed",
"esim": {
"id": "…",
"iccid": "…",
"lpa_address": "…",
"activation_code": "…",
"qr_string": "…"
}
}Status paid mengonfirmasi pembayaran, sedangkan completed menandakan bahwa eSIM dan paket terkaitnya sudah disiapkan. Tampilkan qr_string sebagai kode QR untuk pemasangan lewat perangkat kedua. Untuk pengguna yang memasang eSIM langsung di ponselnya, berikan tautan pemasangan iPhone atau Android, yang membuka pengaturan eSIM bawaan ponsel:
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);
const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;Atau berikan satu tautan kepada pengguna Anda yang mengurus semuanya: https://heyatli.com/my/esim dengan lpa berisi qr_string dalam base64url dan iccid berisi ICCID eSIM tersebut. Halaman itu menampilkan kode QR, kedua tautan pemasangan sekali ketuk, dan detail manual, dan dengan ICCID halaman itu juga menampilkan paket serta sisa kuota. Halaman ini tidak memerlukan akun Atli. Cantumkan bahasa di path, misalnya /ja/my/esim, dan pakai staging.heyatli.com untuk eSIM Sandbox. Siapa pun yang memegang tautan itu bisa memasang eSIM-nya, jadi kirimkan hanya kepada orang yang akan memakainya.
Panduan kami untuk iPhone dan Android menjelaskan apa yang dilihat pengguna sesudahnya.
GET /esims menampilkan daftar eSIM pengguna beserta detail pemasangan, paket, dan data yang terpakai per sinkronisasi terakhir. POST /esims/{id}/sync meminta angka terbaru dari jaringan. Setiap permintaan sinkronisasi menghubungi operator jaringan dan dikenai rate limit. Minta data pemakaian terbaru saat dibutuhkan, bukan dengan polling otomatis pada interval tetap.
Mengizinkan orang masuk dengan akun Atli mereka
Jika di aplikasi Anda orang memakai akun Atli miliknya sendiri alih-alih akun tamu, Atli menyediakan OAuth 2.1: alur authorization code dengan PKCE (S256), refresh token yang dirotasi, dan pencabutan token. Pengguna melakukan autentikasi dan memberi izin akses di heyatli.com, jadi aplikasi Anda tidak pernah menangani kata sandi Atli mereka.
Daftarkan klien di partners.heyatli.com/id/dev/oauth/clients. Satu akun bisa memiliki 10 klien: klien public untuk aplikasi ponsel, dan klien confidential untuk server yang bisa menjaga secret. Halaman web tidak bisa melakukan panggilan token sendiri, karena API menolak permintaan browser dari situs web lain kecuali Atli sudah menandai klien itu sebagai tepercaya, jadi beri aplikasi web sebuah server dan klien confidential. Hanya klien milik Anda yang bisa mendapatkan token untuk API, dan akun Anda perlu alamat email agar bisa memiliki klien.
Ambil endpoint OAuth dari metadata server otorisasi, jangan menuliskannya langsung di kode:
curl https://api.heyatli.com/.well-known/oauth-authorization-serverAccess token berlaku 15 menit. Setiap refresh mengembalikan refresh token baru, yang harus menggantikan token sebelumnya di penyimpanan aman aplikasi Anda. Orang yang masuk lewat klien Anda bisa terhubung ke Anda secara otomatis setelah Atli mengaktifkan fitur itu untuk akun Anda. Sampai saat itu, hubungkan mereka sendiri dengan POST /user/referral/redeem dan access token milik mereka, seperti di Langkah 2.
Berbagi eSIM, voucher, dan grup
Untuk membeli eSIM yang bisa dibagikan, minta penawaran harga dengan is_gift: true dan atur max_claims ke nilai antara 1 dan 20. Setelah pesanan selesai diproses, ambil claim_url dari GET /gifts/sent. POST /rewards/voucher/redeem menambahkan voucher ke akun pengguna. Anggota sebuah Atli Group bisa meminta penawaran harga dengan group_id dan membeli dengan kartu grup. partners.heyatli.com/id/dev/api memetakan setiap alur ini langkah demi langkah lengkap dengan kodenya.
FAQ
Apakah API Atli memakai API key?
Apakah saya perlu akun Stripe sendiri?
GET /stripe/config, dan detail kartu langsung dikirim ke Stripe tanpa pernah melewati server Anda atau API.Bisakah pelanggan membayar dengan Apple Pay atau Google Pay?
Bagaimana cara menambah kuota ke eSIM yang sudah dimiliki pengguna?
target_esim_id berisi eSIM tersebut, lalu beli seperti biasa. Paketnya masuk ke eSIM yang sudah dimiliki pengguna, jadi tidak ada eSIM baru yang perlu dipasang. Jika jaringan eSIM itu tidak menjual paket tersebut, API menolaknya dengan incompatible_esim.Bagaimana jika pembayaran berhasil tetapi panggilan fulfill saya gagal?
GET /fulfillment/status-updates sampai eSIM muncul.Di mana saya bisa menguji tanpa uang sungguhan?
api-staging.heyatli.com. Pakai kartu uji Stripe 4242 4242 4242 4242, tanggal kedaluwarsa kapan pun di masa depan, dan kode keamanan apa saja. Sandbox punya akun sendiri.


