Dokumentasi API

Mulai cepat

Beli akses API dari dompet, buat key, lalu lakukan panggilan pertama. Seluruh alurnya sekitar satu menit.

1. 1Buka konsol developer dan beli paket. Kedua paket langsung memotong dompet Sentadu kamu.
2. 2Buat key. Pilih Live untuk pembelian nyata, atau Test untuk memakai sandbox. Key lengkap hanya tampil sekali.
3. 3Panggil API dengan key sebagai bearer token. Setiap respons adalah JSON dengan field data, atau objek error.

URL dasar

https://api.sentadu.com/v1

Panggilan pertama

curl https://api.sentadu.com/v1/me \
  -H "Authorization: Bearer $SENTADU_API_KEY"

Agent SkillsSerahkan dokumentasi ini ke agen coding kamu. Satu bundel berisi SKILL.md, referensi endpoint, error, webhook, sandbox, dan dua skrip. Bisa diunduh sebagai .zip atau .tar.gz.

Autentikasi

Setiap permintaan membawa bearer token. Tidak ada kredensial lain dan tidak ada bentuk query string.

Authorization: Bearer sdk_live_ab12cd34.<secret>

Autentikasi

Key berbentuk sdk_live_ab12cd34.<rahasia>. Bagian sebelum titik mengidentifikasi key; semua setelahnya adalah rahasianya.

Kami hanya menyimpan hash key. Kalau hilang, cabut dan buat yang baru.

Key live memindahkan uang nyata. Key test memakai saldo sandbox dan tidak pernah menyentuh penyedia.

Key tidak punya masa berlaku sendiri. Key bekerja selama langganan akun aktif atau dalam masa tenggang.

Mencabut key bersifat langsung dan permanen.

Paket

Katalognya sama dengan yang dijual toko publik. Harga dikembalikan dalam satuan minor USD dan IDR; angka IDR adalah yang akan ditagih.

• Harga per paket tergantung tier kamu. Key Reseller melihat harga toko publik. Key Enterprise melihat harga pokok penyedia, tanpa markup.
• Paket DAILY adalah data tak terbatas per hari dengan throttle setelah kuota harian. duration_days-nya hanya placeholder 1; kirim validity_days saat memesan.
• country_count dan countries menjelaskan cakupan. Paket SINGLE mencakup satu negara; REGIONAL dan MULTI mencakup beberapa.

{
  "data": [{
    "package_code": string,
    "slug": string,
    "name": string,
    "coverage": "SINGLE" | "MULTI" | "REGIONAL",
    "plan_type": "FIXED" | "DAILY",
    "duration_days": number,
    "volume_bytes": number,
    "speed": string | null,
    "fup_policy": string | null,
    "support_top_up": boolean,
    "country_count": number,
    "countries": [{ "code": string, "name": string }],
    "price": { "usd_minor": number, "idr_minor": number, "currency": "USD" },
    "wholesale": boolean
  }],
  "meta": { "page": number, "perPage": number, "total": number, "totalPages": number }
}

The same object as one element of `GET /v1/packages`.

Pesanan

Satu pesanan memotong dompet dan menyediakan eSIM dalam satu panggilan. Tidak ada langkah pembayaran yang perlu dipoll: responsnya sudah membawa status pesanan dan eSIM-nya begitu fulfillment cukup cepat.

• Kirim header Idempotency-Key. Percobaan ulang dengan key yang sama mengembalikan pesanan yang sama, bukan membeli dua kali. Key unik per akun, jadi dua developer boleh sama-sama memakai 'order-1'.
• quantity menyediakan sebanyak itu eSIM dalam satu pesanan, dengan satu pemotongan dompet. Maksimal 10.
• Kalau saldo dompet tidak cukup, API menjawab 402 sebelum pesanan apa pun ada, jadi pembelian gagal tidak mengotori daftar pesanan kamu.
• Pembatalan mengikuti aturan toko: eSIM yang belum pernah diaktivasi, di dalam jendela pembatalan. Dompet dikembalikan.

{
  "package_code": "JP-5GB-30D",
  "validity_days": 30,
  "quantity": 1,
  "idempotency_key": "9f2c-order-1"
}

{
  "data": {
    "id": string,
    "order_number": "SUD-...",
    "status": "PAID" | "FULFILLMENT" | "ACTIVE",
    "package_code": string,
    "quantity": number,
    "validity_days": number | null,
    "amount_idr_minor": number,
    "pricing_mode": "STORE" | "WHOLESALE",
    "created_at": string,
    "paid_at": string | null,
    "esims": [{ "id": string, "iccid": string, "lpa": string, "status": string }]
  }
}

A list of order objects, with `meta`.

One order object.

The order, now `CANCELLED`.

eSIM

Satu eSIM milik satu paket dan satu pesanan. Membacanya memberi detail pemasangan; aksi siklus hidup mengubah apa yang penyedia lakukan dengannya.

• lpa adalah string aktivasi yang dibaca ponsel dari kode QR, dan qr_code_url adalah gambar hosted dari hal yang sama. pin dan puk hanya dikembalikan saat kamu meminta ?include=secrets.
• status diturunkan dari field penyedia ditambah tanggal kedaluwarsa, jadi bisa saja EXPIRED walau penyedia masih melaporkan eSIM itu terpakai.
• Top up butuh paket yang penyedia tawarkan untuk eSIM ini. Picker di halaman akun dan endpoint ini memakai daftar yang sama, jadi kode dari sana selalu bisa dipakai di sini. Kirim Idempotency-Key dan panggilan ulang mengembalikan top-up yang sudah dibeli.
• suspend dan unsuspend hanya bekerja pada eSIM yang sudah aktif. revoke permanen dan tidak mengembalikan apa pun; pakai cancel di pesanan kalau eSIM belum pernah dipakai.

{
  "data": [{
    "id": string,
    "iccid": string | null,
    "package_code": string,
    "status": "READY" | "ACTIVE" | "SUSPENDED" | "EXPIRED" | "USED_UP" | "CANCELLED",
    "total_bytes": number,
    "used_bytes": number,
    "remaining_bytes": number,
    "activated_at": string | null,
    "expires_at": string | null,
    "created_at": string
  }],
  "meta": { ... }
}

The list shape plus `lpa`, `qr_code_url`, `smdp_status`, `esim_status`, `apn`.

{
  "esim_id": string,
  "iccid": string | null,
  "total_bytes": number,
  "used_bytes": number,
  "remaining_bytes": number,
  "percent_used": number,
  "measured_at": string | null
}

{ "package_code": "JP-1GB-7D" }

{
  "id": string,
  "esim_id": string,
  "package_code": string,
  "amount_idr_minor": number,
  "status": string,
  "created_at": string
}

{ "esim_id": string, "status": "SUSPEND" }

{ "esim_id": string, "status": "UNSUSPEND" }

{ "esim_id": string, "status": "REVOKE" }

Dompet

Pembelian dipotong dari dompet Sentadu dalam Rupiah. Top up dari halaman akun, lalu belanja lewat API.

• Dompet hanya IDR. Tidak ada mata uang kedua dan tidak ada konversi di endpoint ini.
• Pembelian lewat API tanpa biaya layanan. Biaya yang kamu bayar saat top up sudah menutup transaksi gateway.
• Setiap kredit dan debit muncul di ledger, terbaru dulu, dengan referensi penyebabnya. Key sandbox mendapat daftar kosong, karena uang sandbox tidak masuk ledger.

{ "balance_idr_minor": number, "currency": "IDR", "sandbox": boolean }

{
  "data": [{
    "id": string,
    "amount_idr_minor": number,
    "balance_after_idr_minor": number,
    "type": "TOPUP" | "PURCHASE" | "REFUND" | "REFERRAL",
    "description": string | null,
    "reference_type": string | null,
    "reference_id": string | null,
    "created_at": string
  }]
}

Webhook

Kami mengirim POST untuk setiap event yang kamu langganan, dan mencoba ulang endpoint yang gagal selama sehari sebelum menyerah.

Setiap permintaan membawa X-Sentadu-Signature: t=<unix>,v1=<hex>. Isinya HMAC-SHA256 atas string '<t>.<raw body>', dengan rahasia endpoint kamu sebagai kunci.

X-Sentadu-Signature: t=1750000000,v1=6f1c...

Verifikasi tanda tangan terhadap body mentah, bukan objek yang diserialisasi ulang, dan tolak timestamp lebih tua dari lima menit.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=")),
  );
  const timestamp = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1),
  );
}

Respons non-2xx dicoba ulang setelah 1 menit, 5, 30, 2 jam, dan 12 jam. Setelah lima kegagalan, pengiriman ditandai FAILED dan tampil di dashboard kamu.

Endpoint harus https dan bisa dijangkau dari internet publik. Alamat privat, loopback, dan link-local ditolak.

Sandbox

Key Test menjalankan seluruh API terhadap akun palsu. Katalog dan harganya asli, jadi angka yang kamu lihat sama dengan produksi.

• Pesanan bernomor TST-, eSIM punya ICCID sintetis dan LPA yang menunjuk test.sentadu.com, dan pemasangannya tidak ke mana-mana. Tidak ada panggilan ke penyedia.
• Sandbox mulai dengan Rp 500.000 dan bisa direset dari konsol. Pembelian yang melebihi saldo mengembalikan insufficient_wallet yang sama dengan key live.
• Key test butuh langganan aktif, sama seperti key live.

Batas laju

Batasnya per key, dihitung per menit. Key Reseller mendapat 60 permintaan/menit; Enterprise mulai dari 300 dan bisa menambah.

• Setiap respons membawa X-RateLimit-Limit dan X-RateLimit-Remaining. Penolakan berupa 429 dengan Retry-After.
• Add-on Enterprise bertumpuk dan berakhir bersama tahun langganan. Dibeli dari konsol developer.
• Batasnya dihitung per key, bukan sebagai kumpulan bersama: setiap key dihitung sendiri.

Maximum self-serve: 4600 requests/minute.

Error

Setiap kegagalan berupa satu objek dengan kode stabil. Cabangkan pada kode, jangan pada pesan.

Bentuk

{
  "error": {
    "code": "insufficient_wallet",
    "message": "Wallet balance Rp 40.000 does not cover Rp 62.000.",
    "details": [{ "path": "package_code", "message": "..." }]
  }
}