Open API & Integrasi
IndoRadius menyediakan Open API v1 (Server-to-Server REST API) yang dirancang khusus bagi ISP dan operator jaringan untuk mengintegrasikan portal pelanggan mandiri (Customer Self-Service Portal), bot WhatsApp/Telegram, aplikasi mobile pelanggan, hingga automasi sistem pembayaran pihak ketiga.
Seluruh request API bersifat multi-tenant scoped (data antar-tenant terisolasi total), diproteksi oleh API Key dengan hak akses granular (scoped permissions), dan dilengkapi pembatasan laju pemanggilan (rate limiting).
1. Autentikasi & Kredensial
Section titled “1. Autentikasi & Kredensial”Setiap panggilan API wajib menyertakan token API Key pada header Authorization dengan skema Bearer.
Authorization: Bearer irk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxContent-Type: application/jsonAccept: application/jsonFormat Token
Section titled “Format Token”Token API Key Indoradius memiliki format baku:
- Awalan:
irk_live_ - Isi: 64 karakter hex acak
- Plaintext token hanya ditampilkan satu kali saat pertama kali dibuat. Simpan token di environment variable atau secret manager backend Anda.
2. Hak Akses (Scopes)
Section titled “2. Hak Akses (Scopes)”Saat membuat API Key, Anda dapat memilih izin akses (least-privilege) yang sesuai dengan fungsi aplikasi Anda:
| Scope | Keterangan | Contoh Penggunaan |
|---|---|---|
customers:read |
Mencari identitas pelanggan dan melihat status koneksi/diagnosa | Bot cek status akun / portal login |
customers:write |
Mendaftarkan calon pelanggan baru dan merestart koneksi PPPoE/Hotspot | Form pendaftaran online & tombol reconnect |
invoices:read |
Membaca daftar tagihan belum lunas, detail invoice, dan riwayat pembayaran | Bot tagihan / halaman bayar portal |
payments:create |
Membuat atau mengambil Payment Link gateway online (Duitku, Xendit, Midtrans) | Otomatisasi link bayar di WhatsApp/portal |
devices:read |
Membaca status perangkat CPE / ONT (SN, model, redaman optik dBm) | Diagnosa mandiri di portal pelanggan |
devices:write |
Mengirim perintah reboot remote ONT via TR-069 | Tombol reboot router pelanggan mandiri |
tickets:read |
Membaca daftar tiket pengaduan gangguan dan riwayat komentar | Portal helpdesk pelanggan |
tickets:write |
Mengirim tiket pengaduan baru dan mengirim balasan pelanggan | Form lapor gangguan di bot atau portal |
plans:read |
Membaca katalog paket internet publik yang sedang aktif | Menampilkan daftar paket di website publik |
3. Rate Limiting & Format Respons
Section titled “3. Rate Limiting & Format Respons”- Limit Standar: Maksimum 120 request per menit per API Key / IP.
- Setiap respons menyertakan header indikator kuota:
X-RateLimit-Limit: Kuota maksimum per jendela waktu (120)X-RateLimit-Remaining: Sisa kuota pada jendela saat iniX-RateLimit-Reset: Unix timestamp saat kuota di-reset kembali
Format Standar JSON Envelope
Section titled “Format Standar JSON Envelope”Semua respons dikemas dalam format JSON terstandarisasi:
{ "success": true, "data": { /* payload data respons */ }}{ "success": false, "error": "invoice is already paid", "request_id": "req-9b3f12a8"}4. Katalog Endpoint Lengkap
Section titled “4. Katalog Endpoint Lengkap”A. Pelanggan & Koneksi
Section titled “A. Pelanggan & Koneksi”1. Lookup Pelanggan
Section titled “1. Lookup Pelanggan”Mencari akun pelanggan berdasarkan ID Pelanggan (code), username PPPoE/Hotspot (username), atau nomor telepon/WhatsApp (phone).
- Metode:
GET /api/v1/customers/lookup - Scope Diperlukan:
customers:read - Query Parameters:
code(string, opsional): Nomor / ID Pelanggan (contoh:CUST-0001)username(string, opsional): Username akun PPPoE atau Hotspotphone(string, opsional): Nomor telepon pelanggan (contoh:08123456789)
curl -X GET "https://app.indoradius.com/api/v1/customers/lookup?username=budi.wifi" \ -H "Authorization: Bearer irk_live_xxxx" \ -H "Accept: application/json"Contoh Respons:
{ "success": true, "data": { "customer": { "id": "7a35dae6-7788-466d-89eb-2fb53cb64449", "code": "CUST-0001", "name": "Budi Santoso", "email": "budi@example.com", "phone": "08123456789", "whatsapp_phone": "08123456789", "address": "Jl. Mawar No. 12, Jakarta", "is_active": true }, "active_subscription": { "id": "e229e0ce-8716-43b6-9bbd-e30aa396f437", "status": "active", "plan_name": "Paket Home 20 Mbps", "price_amount": 165000, "account_username": "budi.wifi", "billing_model": "postpaid", "current_period_end": "2026-10-31T23:59:59Z", "next_billing_date": "2026-11-01" } }}2. Status Koneksi & Diagnosa Live
Section titled “2. Status Koneksi & Diagnosa Live”Mengambil status koneksi langsung dari server RADIUS (sesi aktif, IP address, MAC address, uptime, pemakaian kuota) dan status ONT via TR-069 (redaman optik dBm).
- Metode:
GET /api/v1/customers/{id}/connection-status - Scope Diperlukan:
customers:read
Contoh Respons:
{ "success": true, "data": { "customer_id": "7a35dae6-7788-466d-89eb-2fb53cb64449", "customer_name": "Budi Santoso", "customer_code": "CUST-0001", "is_online": true, "session": { "session_id": "81a00042", "username": "budi.wifi", "ip_address": "10.10.20.14", "mac_address": "48:8F:5A:12:34:56", "service_kind": "pppoe", "uptime_seconds": 86450, "uptime_human": "1d 0h 0m", "download_bytes": 15420000000, "upload_bytes": 2150000000, "download_human": "14.36 GB", "upload_human": "2.00 GB", "router_ip": "10.0.0.1", "started_at": "2026-09-30T13:00:00Z" }, "cpe_device": { "id": "3c02d992-d7b1-4c74-90aa-9a5cf7f2824e", "serial_number": "ZTEGC8123456", "manufacturer": "ZTE", "model": "F670L", "provision_status": "provisioned", "is_active": true, "is_online": true, "optical_power_rx_dbm": "-19.2", "external_ip": "10.10.20.14" } }}3. Reconnect Koneksi Pelanggan
Section titled “3. Reconnect Koneksi Pelanggan”Memutus sesi aktif pelanggan di Mikrotik via RADIUS Disconnect (CoA/PoD) agar router pelanggan melakukan panggilan ulang (reconnect) secara otomatis untuk merefresh koneksi.
- Metode:
POST /api/v1/customers/{id}/reconnect - Scope Diperlukan:
customers:write - Body JSON (Opsional):
{ "force": false}Contoh Respons:
{ "success": true, "data": { "success": true, "session_id": "81a00042", "username": "budi.wifi", "router_ip": "10.0.0.1", "message": "Customer session successfully terminated for auto-reconnect", "reconnected_at": "2026-10-01T13:40:00Z" }}4. Pendaftaran Calon Pelanggan Baru (Lead Capture)
Section titled “4. Pendaftaran Calon Pelanggan Baru (Lead Capture)”Mendaftarkan prospek atau pelanggan baru dari form pemesanan portal publik.
- Metode:
POST /api/v1/customers/register - Scope Diperlukan:
customers:write - Body JSON:
{ "name": "Siti Nurhaliza", "phone": "08567891234", "whatsapp_phone": "08567891234", "email": "siti@example.com", "address": "Komplek Melati Blok B3 No. 4", "notes": "Pemasangan hari Sabtu pagi", "plan_id": "9b15e45a-c60f-4886-9dc7-66a9c1bd568d"}B. Tagihan & Pembayaran (Billing)
Section titled “B. Tagihan & Pembayaran (Billing)”1. Daftar Tagihan Belum Lunas
Section titled “1. Daftar Tagihan Belum Lunas”Menampilkan seluruh invoice pelanggan yang belum lunas (unpaid / overdue) beserta nominal total.
- Metode:
GET /api/v1/customers/{id}/unpaid-invoices - Scope Diperlukan:
invoices:read
curl -X GET "https://app.indoradius.com/api/v1/customers/7a35dae6-7788-466d-89eb-2fb53cb64449/unpaid-invoices" \ -H "Authorization: Bearer irk_live_xxxx"Contoh Respons:
{ "success": true, "data": { "customer_id": "7a35dae6-7788-466d-89eb-2fb53cb64449", "customer_name": "Budi Santoso", "total_unpaid_amount": 165000, "count": 1, "invoices": [ { "id": "e305e7ba-bf1e-450a-9d93-1b072e59df95", "invoice_number": "INV/2026/10/0001", "status": "sent", "amount": 150000, "tax_amount": 15000, "total_amount": 165000, "period_start": "2026-10-01", "period_end": "2026-10-31", "due_date": "2026-10-10", "payment_url": "https://app.indoradius.com/pay/inv_e305e7ba", "created_at": "2026-10-01T00:00:00Z" } ] }}2. Buat / Ambil Payment Link Invoice
Section titled “2. Buat / Ambil Payment Link Invoice”Mengambil tautan pembayaran online resmi (Duitku, Midtrans, atau Xendit). Jika tautan sebelumnya sudah kadaluarsa atau belum dibuat, sistem otomatis meng-generate tautan pembayaran baru.
- Metode:
POST /api/v1/invoices/{id}/payment-link - Scope Diperlukan:
payments:create - Body JSON (Opsional):
{ "force": false}(Gunakan "force": true bila ingin memaksa regenerasi order ID baru ke payment gateway).
Contoh Respons:
{ "success": true, "data": { "invoice_id": "e305e7ba-bf1e-450a-9d93-1b072e59df95", "order_id": "ORDER-INV-202610-001", "payment_url": "https://passport.duitku.com/web/checkout.aspx?reference=...", "provider": "duitku", "expires_at": "2026-10-02T13:40:00Z" }}3. Cek Status Pembayaran Invoice Ringkas
Section titled “3. Cek Status Pembayaran Invoice Ringkas”- Metode:
GET /api/v1/invoices/{id}/status - Scope Diperlukan:
invoices:read
Contoh Respons:
{ "success": true, "data": { "id": "e305e7ba-bf1e-450a-9d93-1b072e59df95", "invoice_number": "INV/2026/10/0001", "status": "paid", "total_amount": 165000, "paid_at": "2026-10-01T14:15:22Z", "due_date": "2026-10-10", "pg_provider": "duitku" }}4. Riwayat Pembayaran Pelanggan
Section titled “4. Riwayat Pembayaran Pelanggan”Menampilkan riwayat invoice yang telah dibayar beserta metode dan nomor referensi pembayaran.
- Metode:
GET /api/v1/customers/{id}/payment-history?page=1&limit=10 - Scope Diperlukan:
invoices:read
C. Perangkat CPE / ONT (TR-069)
Section titled “C. Perangkat CPE / ONT (TR-069)”1. Informasi CPE Pelanggan
Section titled “1. Informasi CPE Pelanggan”- Metode:
GET /api/v1/customers/{id}/cpe - Scope Diperlukan:
devices:read
Mengembalikan serial number, tipe pabrikan, status provisi TR-069, status online, dan nilai redaman optik penerima (optical_power_rx_dbm).
2. Reboot CPE Pelanggan
Section titled “2. Reboot CPE Pelanggan”- Metode:
POST /api/v1/customers/{id}/cpe/reboot - Scope Diperlukan:
devices:write
Mengirimkan RPC Reboot via TR-069 ACS ke ONT pelanggan.
D. Tiket Pengaduan Gangguan (Helpdesk)
Section titled “D. Tiket Pengaduan Gangguan (Helpdesk)”1. Buat Tiket Baru
Section titled “1. Buat Tiket Baru”- Metode:
POST /api/v1/tickets - Scope Diperlukan:
tickets:write - Body JSON:
{ "customer_id": "7a35dae6-7788-466d-89eb-2fb53cb64449", "subject": "Lampu LOS merah berkedip pada modem", "description": "Sejak pukul 11 siang lampu indikator LOS merah dan internet terputus.", "priority": "high", "category": "technical"}2. Kirim Komentar / Pesan pada Tiket
Section titled “2. Kirim Komentar / Pesan pada Tiket”- Metode:
POST /api/v1/tickets/{id}/comments - Scope Diperlukan:
tickets:write - Body JSON:
{ "body": "Sudah saya coba matikan dan nyalakan kembali modem tapi tetap merah."}E. Katalog Paket Internet Publik
Section titled “E. Katalog Paket Internet Publik”Mengambil daftar paket layanan internet yang berstatus aktif dan publik. Paket privat B2B (is_public = false) maupun paket discontinued (is_legacy = true) secara otomatis difilter sehingga aman ditampilkan ke calon pelanggan umum.
- Metode:
GET /api/v1/service-plans - Scope Diperlukan:
plans:read - Query Parameters:
plan_kind(string, opsional):subscription,voucherservice_kind(string, opsional):pppoe,hotspotpage(int, opsional): default1limit(int, opsional): default20
Contoh Respons:
{ "success": true, "data": { "total": 3, "plans": [ { "id": "9b15e45a-c60f-4886-9dc7-66a9c1bd568d", "name": "Paket Home Fiber 20 Mbps", "description": "Internet unlimited cocok untuk 3-5 perangkat", "plan_kind": "subscription", "service_kind": "pppoe", "billing_model": "postpaid", "price_amount": 150000, "price_human": "Rp 150.000" }, { "id": "7fa120e8-0931-41e9-9be9-a1b756910ce2", "name": "Paket Home Fiber 50 Mbps", "description": "Streaming 4K & gaming bebas lag", "plan_kind": "subscription", "service_kind": "pppoe", "billing_model": "postpaid", "price_amount": 250000, "price_human": "Rp 250.000" } ] }}5. Ringkasan Kode Status HTTP
Section titled “5. Ringkasan Kode Status HTTP”| HTTP Status | Kondisi | Solusi |
|---|---|---|
200 OK |
Panggilan berhasil | Data ada pada data |
201 Created |
Sumber daya baru berhasil dibuat | Data ada pada data |
400 Bad Request |
Parameter URL atau payload JSON tidak valid | Periksa validitas ID UUID atau parameter wajib |
401 Unauthorized |
API Key tidak dikirim, format salah, expired, atau revoked | Buat API Key baru di dashboard Settings |
403 Forbidden |
API Key tidak memiliki scope yang diwajibkan oleh endpoint | Edit atau tambahkan scope pada API Key |
404 Not Found |
Pelanggan, invoice, atau tiket tidak ditemukan | Pastikan ID sesuai dan milik tenant Anda |
422 Unprocessable |
Kondisi bisnis tidak terpenuhi (misal invoice sudah lunas) | Cek isi pesan pada properti error |
429 Too Many Requests |
Melebihi kuota 120 req/menit | Implementasikan delay atau backoff pada script pemanggil |
500 Server Error |
Terjadi kendala internal server | Hubungi tim support dengan menyertakan request_id |