Integrasikan API eSIM

Gunakan API eSIM untuk membeli paket data dan mengirimkan detail instalasi dari aplikasi Anda. Anda memerlukan workspace, kunci API, dan dana wallet organisasi untuk pembelian dalam mode live. Ikuti panduan autentikasi dan gunakan region API yang sesuai dengan kunci Anda.

Berikan kunci izin esim:read untuk memeriksa penawaran dan sumber daya, dan esim:write untuk membeli atau mengelola layanan. Kredensial instalasi memiliki izin tersendiri: esim_credentials:read untuk mengambilnya dan esim_credentials:write untuk membuat atau mengirim tautan instalasi. Simpan kunci API di aplikasi server Anda.

1. Pilih penawaran

Daftar penawaran untuk tujuan, lalu ambil penawaran yang dipilih. Periksa zone.countries, kuota dan masa berlaku di pricing, ketentuan kecepatan, dan layanan telepon yang disertakan. Untuk eSIM yang sudah ada, gunakan Daftar penawaran yang kompatibel; ketersediaan katalog umum tidak menjamin kompatibilitas top-up.

Ambil persyaratan identifikasi penawaran sebelum mengumpulkan informasi pelanggan. Respons berisi JSON Schema untuk setiap negara cakupan, yang mewajibkan nama depan, nama belakang, dan email, beserta field tambahan lainnya. Aktifkan validasi format email dan tanggal. Anda yang mengumpulkan dan memvalidasi informasi ini; API eSIM tidak menerima atau memverifikasi jawaban tersebut, dan validasi yang berhasil tidak mengotorisasi pembelian.

Untuk eSIM baru, ambil opsi checkout. Tampilkan harga sekali bayar atau kuotasi berulang yang tersedia sebelum menerima pembelian. Harga checkout belum termasuk pajak. Perpanjangan memiliki harga dan jadwal tersendiri; ikuti panduan paket berulang jika pelanggan memilihnya.

Untuk contoh sekali bayar di bawah ini, instal curl dan jq. Atur BIRD_API_URL ke base URL regional Anda, BIRD_API_KEY ke kunci Anda, dan ESIM_OFFER_ID ke ID penawaran yang dipilih:

Contoh kode

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Tinjau harga dan ketentuan penawaran sebelum melanjutkan. Kuotasi tidak mencadangkan ketersediaan.

2. Buat pembelian

Buat order dengan offer_id. Kosongkan esim_id untuk profil baru; sertakan untuk top-up. Untuk pembelian sekali bayar, kirim offer_revision dan expected_price dari kuotasi yang diterima. Field ini menolak ketentuan yang berubah dengan 409 sebelum menagih; ambil dan tinjau kuotasi terbaru sebelum menerima harga yang berubah.

Atur ESIM_ORDER_KEY ke nilai unik untuk pembelian ini dan simpan bersama permintaan. Contoh ini membeli eSIM baru yang belum ditetapkan dan menyalin harga yang dipublikasikan tanpa mengubah jumlah atau mata uangnya:

Contoh kode

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Untuk menetapkan profil baru saat pengiriman selesai, sertakan subscriber_id workspace; ikuti panduan penyiapan pelanggan. Top-up mempertahankan penetapan yang ada, jadi kosongkan subscriber_id saat mengirim esim_id. Kirim detail instalasi secara terpisah setelah pengiriman.

Simpan ID order yang dikembalikan. Periksa status meskipun setelah HTTP 201, yang dapat berisi order yang selesai atau gagal. HTTP 202 berarti pemrosesan masih berlanjut. Ambil order hingga statusnya completed atau failed. Order yang selesai mengidentifikasi esim_id dan package_id; instalasi perangkat tetap merupakan langkah terpisah.

3. Berikan detail instalasi

Setelah pembelian, baca kredensial instalasi, buat tautan instalasi yang dihosting, atau kirim tautan melalui email atau SMS. Jauhkan detail aktivasi dan tautan instalasi dari analitik dan log publik.

Untuk tautan yang dikirim, simpan ID pengiriman dan periksa riwayat pengiriman. Respons 202 mengonfirmasi penerimaan untuk dikirim; delivered mengonfirmasi pengiriman pesan, dan instalasi perangkat perlu diperiksa secara terpisah. Ikuti panduan instalasi untuk metode yang didukung, kedaluwarsa tautan, dan pemulihan.

4. Pulihkan pembelian yang terputus

Jika respons pembuatan hilang atau mengembalikan 503, ulangi permintaan yang disimpan dengan Idempotency-Key aslinya; lihat permintaan idempoten. Jika Anda memiliki ID order, baca order tersebut terlebih dahulu. Membuat pembelian lain saat hasilnya belum pasti dapat menyebabkan tagihan tambahan.

Untuk order dalam charging, periksa funding dan saldo wallet Anda. funding.required_amount adalah total saldo yang dibutuhkan, termasuk pajak; bandingkan dengan dana yang ada sebelum menambahkan uang. Order sekali beli mencoba ulang pendanaan secara otomatis. Setelah pembelian berulang awal ditolak karena dana tidak mencukupi, tambahkan dana dan coba ulang permintaan pembuatan yang sama secara eksplisit dengan kunci aslinya.

Periksa status order saat ini meskipun setelah funding.lapses_at: timestamp tersebut tidak menjamin pembatalan. Order masih dapat selesai jika menerima dana sebelum percobaan dana-tidak-mencukupi berikutnya menggagalkannya.

Untuk menghentikan pembelian tanpa dana yang tidak diinginkan, batalkan order. Pembatalan tanpa dana yang berhasil mengembalikan status: failed dan failure_code: canceled. Order sekali beli yang sudah didanai mengembalikan 409 dan tetap berlanjut. Untuk pembelian berulang awal, pembayaran yang terpulihkan selama pembatalan dapat menyebabkan pembelian berbayar tetap berlanjut sementara perpanjangan di masa mendatang berhenti. Periksa order dan langganan yang dikembalikan sebelum melaporkan pembatalan atau pengembalian dana.

Untuk pembelian yang gagal, periksa failure_code dan failure_reason. Setiap tagihan dikreditkan secara otomatis; refund_transaction_id mengidentifikasi kredit yang diterbitkan. Simpan ID order untuk dukungan jika pembayaran, pengiriman, atau kredit tetap belum terselesaikan.

5. Tampilkan saldo dan status layanan

Dapatkan eSIM untuk status, kondisi instalasi, paket, dan available_actions. Tampilkan kuota, konsumsi, dan waktu observasi paket menggunakan panduan penggunaan. Konsumsi yang tidak diketahui harus tetap ditampilkan sebagai tidak diketahui di aplikasi Anda.

Periksa ulang ketersediaan tindakan saat pelanggan bertindak; operasi memeriksa izin dan status kembali. Gunakan panduan operasi untuk menyelidiki pembelian yang belum selesai, masalah instalasi, atau kegagalan konektivitas.

Langkah selanjutnya

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Dapatkan ringkasan implementasi