Senarai Semak API eSIM (2026): 12 Ciri yang Mesti Ada pada API eSIM Pelancongan — dan Cara Menguji Setiap Satu

Menghubungkan API eSIM ke aplikasi, platform pelancongan atau enjin tempahan anda tidaklah sukar. Apa yang sukar adalah mendapati, selepas pelancaran, bahawa API tersebut melakukan caj berganda apabila berlaku masa tamat (timeout), tidak dapat memberitahu anda apabila pelanggan kehabisan data, atau tidak memberi anda cara untuk menguji kegagalan.

Senarai semak ini merangkumi 12 ciri yang penting dalam produksi, dan untuk setiap satu, cara untuk mengujinya sebelum anda mendaftar. Kami menggunakan TripoSIM Partner API sebagai contoh kerja, tetapi anda boleh menggunakan senarai semak yang sama untuk membandingkan mana-mana penyedia.

1. Pengesahan token yang selamat

Apa yang perlu dicari: Kredensial klien OAuth 2.0: anda menukar ID klien dan rahsia (secret) untuk token akses jangka pendek. Rahsia tidak akan dihantar bersama setiap permintaan.

Cara menguji: minta token, kemudian semak ia luput. Dalam API TripoSIM, POST /auth/token mengembalikan token akses yang sah selama 15 minit. Pastikan kod anda menyegarkannya secara automatik sebelum ia luput.

2. Kunci idempotency (tiada caj berganda)

Apa yang perlu dicari: pengepala (header) Idempotency-Key pada setiap pesanan dan tambah nilai. Jika permintaan anda mengalami masa tamat dan anda mencuba semula dengan kunci yang sama, API mesti mengembalikan hasil asal dan bukannya mencipta eSIM kedua yang berbayar.

Cara menguji: hantar pesanan yang sama dua kali dengan kunci yang sama dan sahkan anda mendapat satu pesanan sahaja. Kemudian hantar kunci yang sama dengan kandungan (body) yang berbeza — API yang baik akan menolaknya. TripoSIM memerlukan kunci pada pesanan produksi dan tambah nilai serta mengembalikan 409 IDEMPOTENCY_KEY_REUSED jika kunci digunakan semula dengan permintaan yang berbeza.

3. Sebut harga yang mengunci harga

Apa yang perlu dicari: cara untuk mendapatkan harga dan mengekalkannya untuk masa yang singkat, supaya pelanggan anda membayar jumlah yang tepat seperti yang anda tunjukkan kepada mereka.

Cara menguji: buat sebut harga, tunggu, kemudian buat pesanan dengannya. Sebut harga TripoSIM sah selama 10 minit; sebut harga yang telah luput mengembalikan 409 QUOTE_EXPIRED supaya anda boleh membuat sebut harga semula dan bukannya mengenakan harga yang mengejutkan.

4. Suapan katalog yang bersih

Apa yang perlu dicari: satu titik akhir (endpoint) yang menyenaraikan setiap pelan dengan harga, data, tempoh sah, negara liputan, 5G, sokongan tambah nilai — dan untuk pelan tanpa had, had kelajuan penuh harian.

Cara menguji: ambil katalog untuk satu negara dan bandingkan dengan laman web penyedia itu sendiri. Titik akhir TripoSIM /catalog mengembalikan JSON atau CSV, termasuk pelan serantau yang meliputi negara tersebut, dan menambah medan penggunaan adil (fup_daily_mb, fup_throttle_kbps) untuk pelan tanpa had. Lihat [bagaimana had harian tanpa had berfungsi](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Penghantaran pesanan dan QR secara pantas

Apa yang perlu dicari: respons pesanan (atau webhook beberapa saat kemudian) harus menyertakan kod pengaktifan dalam format LPA standard, contohnya LPA:1$smdp.example.com$ACTIVATION_CODE, supaya anda boleh menunjukkan kod QR atau pautan pemasangan satu ketikan.

Cara menguji: buat pesanan sandbox, jana QR daripada rentetan LPA, dan imbas dengan kamera telefon untuk menyemak format tersebut adalah sah.

6. Webhook bertandatangan untuk setiap acara

Apa yang perlu dicari: notifikasi tolak (push notifications) untuk keseluruhan kitaran hayat eSIM, bertandatangan supaya penyerang tidak dapat memalsukannya.

TripoSIM menghantar lapan jenis acara: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted dan esim.expired. Setiap permintaan membawa pengepala X-TripoSIM-Signature — satu HMAC-SHA256 bagi cap masa (timestamp) dan kandungan mentah menggunakan rahsia tandatangan anda:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) &gt; 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

Cara menguji: daftar webhook, cetuskan pesanan, dan sahkan tandatangan dalam kod anda. Kemudian tukar satu bait kandungan dan pastikan semakan anda menolaknya.

7. Sandbox yang mensimulasikan keseluruhan hayat eSIM

Apa yang perlu dicari: eSIM sebenar mengambil masa berhari-hari untuk diaktifkan dan menggunakan data. Sandbox yang baik membolehkan anda memajukan masa dengan pantas.

Cara menguji: dalam sandbox TripoSIM, POST /sandbox/esims/{iccid}/simulate dengan tindakan (action) seperti activate, usage, deplete, expire atau reset. Setiap langkah akan mencetuskan webhook yang sepadan, jadi anda boleh menguji e-mel "data anda hampir habis" anda dalam masa beberapa minit dan bukannya berhari-hari.

8. Simulasi kegagalan

Apa yang perlu dicari: cara untuk memaksa ralat dengan sengaja, supaya anda tahu aplikasi anda dapat menanganinya.

Cara menguji: hantar pengepala X-Sandbox-Simulate dengan mod seperti insufficient_balance, price_changed, rate_limit, provider_unavailable atau timeout, dan semak aplikasi anda menunjukkan mesej yang jelas dan hanya mencuba semula apabila sepatutnya.

9. Tambah nilai pada eSIM yang sama

Apa yang perlu dicari: pelanggan yang kehabisan data sepatutnya boleh menambah lebih banyak tanpa perlu memasang eSIM baru.

Cara menguji: panggil POST /esims/{iccid}/topup dalam sandbox (dengan kunci idempotency), kemudian semak baki data baru. Juga semak pelan mana yang menyokong tambah nilai — katalog akan memberitahu anda.

10. Data penggunaan dan status

Apa yang perlu dicari: satu titik akhir untuk data yang digunakan, data yang berbaki dan tarikh luput, supaya pasukan sokongan dan aplikasi anda boleh menjawab "berapa banyak data yang saya ada?"

Cara menguji: panggil GET /esims/{iccid}/usage selepas acara penggunaan simulasi. TripoSIM menyimpan cache penggunaan selama 5 minit, jadi gunakan webhook (esim.usage_80, esim.depleted) untuk amaran masa nyata.

11. Gantung dan sambung semula

Apa yang perlu dicari: cara untuk menggantung eSIM — contohnya apabila pembayaran dipertikaikan atau pelanggan melaporkan telefon hilang — dan menyambung semula kemudian.

Cara menguji: gantung eSIM sandbox, sahkan webhook esim.suspended tiba, kemudian sambung semula dan sahkan esim.resumed.

12. Had kadar, kod ralat dan log perubahan yang jelas

Apa yang perlu dicari: had yang didokumentasikan, kod ralat yang memberitahu anda sama ada perlu cuba semula, dan log perubahan (changelog) awam supaya kemas kini tidak mengejutkan anda.

Cara menguji: baca senarai ralat dan petakan setiap kod kepada "cuba semula" atau "jangan cuba semula" dalam kod anda. TripoSIM membenarkan 120 permintaan seminit bagi setiap akaun rakan kongsi (anda boleh menetapkan had yang lebih rendah pada kunci API individu), mengembalikan pengepala Retry-After pada respons 429, menandakan setiap kod ralat sebagai boleh dicuba semula atau tidak, dan menerbitkan titik akhir changelog.

Pelan pelancaran ringkas

1. Hari 1: dapatkan kunci sandbox, lakukan pengesahan, ambil katalog.
2. Hari 2: buat pesanan sandbox dengan kunci idempotency dan tunjukkan kod QR.
3. Hari 3: tambah webhook, jalankan simulator kitaran hayat dan kegagalan.
4. Hari 4: tambah fungsi tambah nilai dan penggunaan, kemudian uji pada telefon sebenar dengan satu eSIM live.
5. Hari 5: lancarkan secara langsung (go live).

Kebanyakan pasukan menyambungkan API dalam masa kurang daripada seminggu. Baca [dokumentasi API](https://docs.triposim.com) sepenuhnya atau lihat [panduan integrasi API eSIM](https://docs.triposim.com/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform) langkah demi langkah kami.

Soalan lazim

Apakah yang perlu disertakan oleh API eSIM pelancongan?

Sekurang-kurangnya: pengesahan token, kunci idempotency, sebut harga, suapan katalog, kod QR/pengaktifan pantas, webhook bertandatangan, sandbox dengan simulator kitaran hayat dan kegagalan, tambah nilai, data penggunaan, gantung/sambung semula, serta had kadar dan kod ralat yang didokumentasikan.

Mengapa kunci idempotency penting untuk API eSIM?

Setiap pesanan eSIM melibatkan wang sebenar. Jika permintaan mengalami masa tamat dan sistem anda mencuba semula, kunci idempotency memastikan cubaan semula mengembalikan hasil pertama dan bukannya membeli eSIM kedua.

Bagaimana saya hendak menguji API eSIM tanpa membeli eSIM?

Gunakan sandbox. Sandbox yang baik mensimulasikan pesanan, pengaktifan, penggunaan data, penyusutan dan tamat tempoh — serta membolehkan anda memaksa ralat — tanpa mengenakan caj pada dompet anda.

Berapa lamakah integrasi API eSIM mengambil masa?

Dengan API yang didokumentasikan dengan baik dan sandbox yang lengkap, kebanyakan pasukan boleh melancarkan dalam masa 3–5 hari bekerja.

Adakah API TripoSIM menyokong penghantaran white-label?

Ya. Anda menerima kod pengaktifan dan data QR, jadi anda boleh menghantar eSIM di dalam aplikasi atau e-mel anda sendiri di bawah jenama anda. Lihat [program API](/api-program).

Kesimpulan

Harga adalah penting, tetapi bagi API eSIM, perbezaan sebenar muncul selepas pelancaran: cubaan semula yang tidak pernah mengenakan caj berganda, webhook yang boleh anda percayai, dan sandbox yang membolehkan anda menguji segalanya terlebih dahulu. Jalankan senarai semak ini pada mana-mana penyedia sebelum anda membuat komitmen — dan [mulakan dengan sandbox kami](/api-program) untuk melihat bagaimana TripoSIM Partner API mendapat markah.