FAQ — Developer & API

Pertanyaan teknis seputar integrasi REST API IsiKuota, autentikasi, webhook, dan penanganan error.

---

API Key & Autentikasi

Di mana saya mendapatkan API key?

Login ke Dashboard IsiKuota → Pengaturan → API. Di sana Anda menemukan api_id, api_key, dan secret_key.

Rahasiakan kredensial

Jangan pernah membagikan api_key dan secret_key. Simpan di environment variables atau konfigurasi server, bukan di kode frontend/publik.

---

Parameter apa yang wajib di setiap request?

Setiap request menyertakan 3 parameter di body:

Parameter	Keterangan
api_id	API ID Anda
timestamp	Waktu request dalam UNIX timestamp (detik)
signature	Tanda tangan HMAC untuk validasi request

---

Bagaimana cara membuat signature?

Signature dibuat dengan HMAC-SHA256:

signature = hash_hmac('sha256', "api_id|api_key|timestamp|body_hash", secret_key)

Langkah singkat:

1. Urutkan parameter bisnis A → Z (ksort).
2. Encode jadi JSON tanpa spasi tambahan → hitung body_hash = sha256(json). Jika tidak ada parameter bisnis (mis. cek saldo), gunakan sha256('').
3. Gabung api_id|api_key|timestamp|body_hash dengan pemisah pipe (|).
4. HMAC-SHA256 string tersebut dengan secret_key.

→ Contoh kode lengkap (PHP, JS, Python, cURL, Java, C#) ada di Autentikasi & Signature.

---

Signature saya ditolak. Apa yang salah?

Error	Penyebab Umum
INVALID_SIGNATURE	Parameter tidak diurutkan A–Z, atau secret_key salah
UNAUTHORIZED	api_id tidak ditemukan
INVALID_API_KEY	api_key salah
TIMESTAMP_EXPIRED	Timestamp sudah lewat 5 menit

Checklist debugging:

• Parameter bisnis diurutkan A→Z
• Pakai api_key (bukan api_id) di stringToSign
• timestamp dalam detik, bukan milidetik
• JSON tanpa spasi/escape tambahan

---

Mode Testing

Apakah ada sandbox untuk testing?

Ya. Tambahkan parameter "testing": true pada request untuk menjalankan transaksi tanpa memproses transaksi nyata dan tanpa memotong saldo real. Cocok untuk menguji integrasi sebelum go-live.

→ Detail di Mode Testing.

---

Format & Limit

Format nomor HP apa yang diterima API?

API menerima 08xx dan 628xx (kode negara Indonesia):

• 081234567890 ✅
• 6281234567890 ✅
• +6281234567890 ❌ (tanda + tidak diterima)

---

Berapa rate limit API?

Tier	Limit
Standard	60 req/menit
Pro	300 req/menit
Enterprise	Custom

Jika melebihi limit, Anda akan menerima respons error rate limit — terapkan backoff/antrian di sisi Anda.

---

Bagaimana cara menghindari transaksi ganda (double order)?

Selalu sertakan ref_id unik per transaksi. Jika Anda kirim ulang request dengan ref_id yang sama, sistem mengenalinya sebagai transaksi yang sama sehingga mencegah double charge. Jika request timeout, jangan langsung retry — cek status dulu via endpoint status menggunakan ref_id.

---

Webhook

Apa itu webhook dan kenapa saya butuh?

Webhook membuat IsiKuota mengirim notifikasi real-time ke server Anda setiap status transaksi berubah, sehingga Anda tidak perlu polling berulang.

---

Bagaimana cara memverifikasi webhook benar dari IsiKuota?

Setiap request menyertakan header X-Isikuota-Signature: sha256=<hex>. Hitung HMAC-SHA256 dari raw body dengan secret_key Anda lalu bandingkan secara timing-safe:

X-Isikuota-Signature == "sha256=" + hash_hmac('sha256', raw_body, secret_key)

→ Contoh PHP/Node/Flask di Webhook Overview.

---

Apa persyaratan server webhook saya?

Persyaratan	Detail
Protokol	HTTPS (wajib di production)
Method	POST
Response	HTTP 2xx dalam 15 detik

Jika gagal, IsiKuota retry hingga 3 kali dengan jeda bertahap (10s, 30s, 60s).

---

Bagaimana mencegah memproses webhook yang sama dua kali?

Gunakan event_id (ULID) atau ref_id sebagai kunci idempotensi — simpan yang sudah diproses dan abaikan duplikat sebelum update database.

---

Error API Umum

401 Unauthorized — Invalid API key

• Pastikan kredensial benar dan tidak ada spasi di depan/belakang.
• Generate API key baru bila perlu.

201 — Insufficient balance (saldo tidak cukup)

• Top up saldo di Dashboard → Deposit.
• Cek harga produk via endpoint products sebelum order.

Request timeout

1. Jangan langsung buat transaksi baru.
2. Cek status via endpoint status menggunakan ref_id.
3. Jika transaksi tidak ditemukan → aman untuk retry. Jika processing → tunggu.

→ Daftar lengkap di Kode Error.

---

Mulai integrasi

Baca Pengenalan → Cara Kerja → Autentikasi, lalu coba dengan Postman.