API billing: kunci, autentikasi dan endpoint

Hubungkan aplikasi billing atau sistem Anda sendiri ke iCONFIG: kirim daftar paket, tautkan pelanggan ke ONU-nya, ambil pemakaian trafik per pelanggan, isolir pelanggan yang belum bayar, baca status ONU, sampai otorisasi ONU lewat API.

1. Membuat API key

1. Buka Pengaturan → API key. Hanya pengguna dengan hak Kelola API key (biasanya Administrators) yang bisa membukanya.
2. Di kartu Buat key (1), isi nama, misalnya Aplikasi billing.
3. Biarkan Hanya baca tercentang jika sistem Anda cukup membaca data. Hilangkan centangnya jika sistem perlu mengirim paket, menautkan pelanggan, reboot atau otorisasi ONU.
4. Klik Buat. Key hanya ditampilkan sekali: salin dan simpan di pengaturan aplikasi billing Anda.

2. Cara memanggil API

• Alamat: https://<akun-anda>.iconfig.id/api.php/<endpoint>, misalnya https://netmaju.iconfig.id/api.php/stats.
• Autentikasi: kirim key di header X-API-Key.
• Data POST dikirim sebagai JSON dengan header Content-Type: application/json.
• Jawaban selalu JSON: {"status": true, "response": …}. Jika gagal, status bernilai false dan response berisi pesan kesalahan.

curl -H "X-API-Key: dno_xxxxxxxx" https://netmaju.iconfig.id/api.php/stats

{
    "status": true,
    "response": { "total": 963, "online": 794, "los": 4, "pwrfail": 34, "offline": 131, "unconfigured": 0 }
}

3. Integrasi billing

Alur yang disarankan: kirim paket → tautkan pelanggan ke ONU → ambil pemakaian setiap akhir periode → isolir pelanggan yang belum bayar.

a. Kirim daftar paket

POST /api.php/packages (key tulis). Paket dengan code yang sama diperbarui, yang baru dibuat. fair_usage_gb adalah kuota pemakaian wajar per bulan; kosongkan untuk memakai kuota default (lihat Pemakaian trafik dan kuota wajar).

curl -X POST -H "X-API-Key: dno_xxxxxxxx" -H "Content-Type: application/json" \
  https://netmaju.iconfig.id/api.php/packages -d '{
  "packages": [
    {"code": "HOME20", "name": "Home 20 Mbps", "download_mbps": 20, "upload_mbps": 20, "price": 150000, "fair_usage_gb": 700},
    {"code": "BIZ50", "name": "Bisnis 50 Mbps", "download_mbps": 50, "upload_mbps": 50, "price": 400000, "fair_usage_gb": 2000}
  ]
}'

Jawaban: {"saved": 2, "errors": []}. Daftar paket beserta jumlah ONU-nya bisa dibaca kembali dengan GET /api.php/packages.

b. Tautkan pelanggan ke ONU

POST /api.php/billing/customers (key tulis). Setiap pelanggan butuh customer_id (ID pelanggan di billing Anda) dan salah satu penanda ONU. Pencocokan dicoba berurutan: onu_id, sn, pppoe_user, lalu external_id. Nama, alamat dan telepon ikut diperbarui jika dikirim.

curl -X POST -H "X-API-Key: dno_xxxxxxxx" -H "Content-Type: application/json" \
  https://netmaju.iconfig.id/api.php/billing/customers -d '{
  "customers": [
    {"customer_id": "PLG-1042", "pppoe_user": "pel1042@netmaju.id", "package_code": "HOME20", "name": "Budi Santoso", "phone": "081200001111"},
    {"customer_id": "PLG-1043", "sn": "ZTEGC4D1D9DA", "package_code": "BIZ50"}
  ]
}'

{
    "status": true,
    "response": {
        "linked": 1,
        "not_found": [ { "customer_id": "PLG-1043", "reason": "not found" } ],
        "errors": []
    }
}

• not_found: ONU tidak ditemukan. Jika reason berisi ambiguous …, artinya ada lebih dari satu ONU dengan nilai itu; pakai penanda lain seperti sn.
• errors: misalnya package_code belum dikirim ke /packages.
• Aman dikirim ulang: kirim semua pelanggan setiap kali ada perubahan di billing.

c. Ambil pemakaian trafik

GET /api.php/billing/usage?period=month. Pilihan period: today, yesterday, week, month, last_month, year, atau period=custom&from=2026-10-01&to=2026-10-15. Tambahkan customer_id=PLG-1042,PLG-1043 untuk pelanggan tertentu saja. Hanya ONU yang sudah ditautkan ke pelanggan yang muncul.

curl -H "X-API-Key: dno_xxxxxxxx" "https://netmaju.iconfig.id/api.php/billing/usage?period=last_month&customer_id=PLG-1042"

{
    "status": true,
    "response": {
        "period": "last_month", "from": "2026-09-01", "to": "2026-09-30",
        "customers": [
            {
                "customer_id": "PLG-1042", "sn": "ZTEGC4D1D9DA", "name": "BUDI SANTOSO", "status": "online",
                "package_code": "HOME20", "quota_gb_month": 700,
                "download_bytes": 412316860416, "upload_bytes": 38654705664, "total_bytes": 450971566080,
                "quota_bytes": 751619276800, "quota_used_pct": 60
            }
        ]
    }
}

d. Isolir pelanggan yang belum bayar

POST /api.php/billing/suspend menonaktifkan ONU pelanggan di OLT, sehingga internetnya putus. POST /api.php/billing/resume mengaktifkannya kembali setelah membayar. Keduanya butuh key tulis. Semua ONU yang tertaut ke customer_id itu ikut diubah. Maksimal 100 pelanggan per request.

curl -X POST -H "X-API-Key: dno_xxxxxxxx" -H "Content-Type: application/json" \
  https://netmaju.iconfig.id/api.php/billing/suspend -d '{"customers": ["PLG-1042", "PLG-1077"]}'

{
    "status": true,
    "response": {
        "done": [ { "customer_id": "PLG-1042", "sn": "ZTEGC4D1D9DA" } ],
        "skipped": [ { "customer_id": "PLG-1077", "sn": "ZTEG7A21B0C4", "reason": "already disabled" } ],
        "not_found": [],
        "errors": []
    }
}

• skipped: ONU sudah dalam keadaan yang diminta. Aman dipanggil berulang kali.
• not_found: belum ada ONU yang tertaut ke customer_id itu. Tautkan dulu lewat /billing/customers.
• errors: OLT menolak atau tidak bisa dihubungi. Coba lagi nanti; ONU lain dalam request yang sama tetap diproses.
• Untuk satu ONU berdasarkan SN: POST /api.php/onu/{sn}/disable dan /enable.

4. Endpoint lainnya

Nilai status ONU: online, los, pwrfail, offline, unknown (N/A) dan disabled.

Otorisasi ONU lewat API

Wajib: olt_id, board, port, sn, name, vlan. Opsional: mode (routing / bridging), onu_type, zone, sector, odb, odb_port, download dan upload (nama profil kecepatan), pppoe_user, pppoe_pass, address, phone, external_id, latitude, longitude, comment. Zona, wilayah, ODP, tipe ONU dan profil ditulis dengan nama seperti di aplikasi. Ambil board, port dan sn dari GET /api.php/unconfigured.

curl -X POST -H "X-API-Key: dno_xxxxxxxx" -H "Content-Type: application/json" \
  https://netmaju.iconfig.id/api.php/authorize -d '{
  "olt_id": 7, "board": 2, "port": 4, "sn": "ZTEGC4D1D9DA",
  "name": "BUDI SANTOSO", "vlan": 1024, "mode": "routing", "onu_type": "ZTE-F609",
  "pppoe_user": "pel1042@netmaju.id", "pppoe_pass": "rahasia",
  "zone": "POP PUSAT", "download": "Tanpa batas", "upload": "Tanpa batas"
}'

Jawaban: {"onu_id": 1312, "onu": 6}, yaitu ID ONU di iCONFIG dan nomor ONU di port PON.