Panduan

Cara mengintegrasikan API eSIM Atli ke situs atau aplikasi

Tanpa API key: tiap pengguna mendapat akun tamu Atli. Cara menghubungkannya ke kode mitra, meminta penawaran harga, menerima pembayaran, dan mengirim eSIM.

Permintaan curl ke endpoint pembelian API Atli di samping ponsel yang menampilkan halaman pembayaran Atli, dengan maskot biru Atli bersayap yang memegang ponsel di dekat koper

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

SandboxProduksi
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
File OpenAPIhttps://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
Halaman pembayaranhttps://staging.heyatli.com/payhttps://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.

Peta alur utama API Atli: membuat pengguna, meminta penawaran harga, membeli dan membayar, mendapatkan eSIM, lalu memasang dan memantau pemakaian, dengan cabang opsional untuk akun sungguhan, kartu tersimpan dan kartu grup, isi ulang, diskon, dan berbagi

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:

Bash
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

Ganti 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:

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "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:

Bash
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):

Bash
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:

Bash
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 }'
JSON
{
  "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.

Bash
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" }'
JSON
{
  "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:

JavaScript
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:

Bash
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:

JavaScript
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, dan options_signature persis seperti yang dikembalikan API, dan URLSearchParams menangani encoding-nya. options adalah pengecualiannya: encode dulu dengan base64url tanpa mengubah JSON-nya. Jangan pernah memasukkan client_secret polos ke dalam tautan.
  • Nilai Sandbox hanya bisa dibuka di staging.heyatli.com/pay, dan nilai produksi hanya bisa dibuka di heyatli.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=none menyembunyikan logo Atli. lang dan theme mengatur bahasa dan tampilan halaman. Parameter redirect hanya menerima alamat https di 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:

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "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:

JavaScript
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:

Bash
curl https://api.heyatli.com/.well-known/oauth-authorization-server

Access 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?
Tidak. Token mengidentifikasi orang, bukan aplikasi. Server Anda login atas nama setiap pengguna dengan ID perangkat atau lewat OAuth, lalu memanggil API sebagai pengguna tersebut.
Apakah saya perlu akun Stripe sendiri?
Tidak. Pesanan ditagih lewat akun Stripe Atli. Formulir Anda memakai publishable key Atli dari 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?
Bisa. Halaman pembayaran Atli menyediakan keduanya. Untuk formulir Stripe milik Anda sendiri, kirim email ke [email protected] setelah integrasi Anda menghasilkan penjualan nyata.
Bagaimana cara menambah kuota ke eSIM yang sudah dimiliki pengguna?
Minta penawaran harga untuk paket baru dengan 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?
Jangan menagih lagi. Atli menyelesaikan pesanan yang sudah dibayar dengan sendirinya, jadi teruskan polling GET /fulfillment/status-updates sampai eSIM muncul.
Di mana saya bisa menguji tanpa uang sungguhan?
Di Sandbox, pada alamat 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.