Device Abstraction
Satu API konsisten untuk berbagai vendor jaringan tanpa logika manual per perangkat.
Documentation / Provisioning API
Provisioning API
Lapisan integrasi untuk mengelola aktivasi layanan, sinkronisasi perangkat, dan otomasi operasional jaringan dari satu endpoint terpadu.
Atomic Provisioning
Eksekusi konfigurasi berurutan dengan rollback otomatis saat validasi gagal.
Billing Sync
Sinkronisasi status layanan dengan engine billing secara near real-time.
Provisioning Sequence
1. Validasi input pelanggan, paket layanan, dan policy akses.
2. Tentukan target device + profile konfigurasi berdasarkan kapasitas node.
3. Push konfigurasi terverifikasi ke infrastruktur (MikroTik/OLT).
4. Commit status ke billing + notifikasi otomatis ke kanal operasional.
Authentication
Provisioning API menggunakan service-to-service authentication via signed JWT dengan scope khusus. Hanya tenant dengan plan Pro atau Enterprise yang memiliki akses langsung ke provisioning endpoint.
# Required Headers
Authorization: Bearer <service_jwt>
X-Tenant-ID: mitra_abc123
X-Idempotency-Key: uuid-v4 # Wajib untuk mutating operations
Content-Type: application/json
# Required JWT Scopes
provision:execute — Jalankan provisioning baru
provision:read — Query status provisioning
provision:rollback — Trigger manual rollback
device:manage — CRUD device registry
API Endpoints
POST
/api/provision/activateAktivasi layanan baru untuk pelanggan. Menjalankan full provisioning sequence.
Request Body
{
"customer_id": "cust_xyz789",
"service_plan": {
"package_id": "pkg_50mbps",
"bandwidth_up": "10Mbps",
"bandwidth_down": "50Mbps",
"ip_mode": "dhcp" | "static",
"static_ip": "10.10.1.100/24" // optional, jika ip_mode=static
},
"target": {
"device_id": "mikrotik_rb750_01", // optional, auto-place jika kosong
"interface": "ether3",
"vlan_id": 100
},
"billing": {
"start_date": "2026-05-19",
"cycle_days": 30,
"amount": 149000
},
"options": {
"dry_run": false,
"notify_channel": "whatsapp" | "telegram" | "both",
"priority": "normal" | "high"
}
}
Response (Success)
{
"id": "prov_abc123",
"status": "completed",
"steps": [
{ "step": "validate", "status": "ok", "duration_ms": 12 },
{ "step": "device_select", "status": "ok", "device": "mikrotik_rb750_01" },
{ "step": "config_push", "status": "ok", "duration_ms": 1840 },
{ "step": "verify", "status": "ok", "ping_ms": 3 },
{ "step": "billing_sync", "status": "ok", "invoice_id": "inv_001" },
{ "step": "notify", "status": "ok", "channel": "whatsapp" }
],
"total_duration_ms": 2340,
"device": {
"id": "mikrotik_rb750_01",
"ip": "192.168.1.1",
"interface": "ether3",
"config_applied": "queue_simple + firewall_filter"
},
"created_at": "2026-05-19T00:00:00Z"
}
POST
/api/provision/deactivateNonaktifkan layanan pelanggan. Menghapus konfigurasi dari device dan menghentikan billing.
{
"customer_id": "cust_xyz789",
"reason": "non_payment" | "request" | "migration",
"effective_immediately": true,
"preserve_config": false // true = soft-disable, false = full removal
}
GET
/api/provision/status/:provision_idQuery status provisioning yang sedang berjalan atau sudah selesai.
{
"id": "prov_abc123",
"status": "completed" | "in_progress" | "failed" | "rolled_back",
"current_step": "config_push",
"progress_pct": 75,
"started_at": "2026-05-19T00:00:00Z",
"completed_at": "2026-05-19T00:00:02.340Z",
"error": null | { "code": "PV-002", "message": "...", "step": "config_push" }
}
GET
/api/provision/devicesList semua device yang terdaftar beserta kapasitas dan health status.
{
"devices": [
{
"id": "mikrotik_rb750_01",
"type": "mikrotik",
"model": "RB750Gr3",
"ip": "192.168.1.1",
"status": "online",
"capacity": { "total": 100, "used": 67, "available": 33 },
"health": { "cpu": 23, "memory": 45, "uptime_days": 142 }
}
],
"total": 12,
"online": 11,
"offline": 1
}
POST
/api/provision/rollback/:provision_idManual rollback provisioning yang sudah selesai. Mengembalikan device ke state sebelumnya.
{
"reason": "customer_complaint" | "config_error" | "testing",
"notify_customer": true
}
Supported Devices
| Vendor | Protocol | Supported Models | Capabilities |
|---|---|---|---|
| MikroTik | SSH / RouterOS API | RB750, RB1100, CCR1036, hAP | Queue, Firewall, DHCP, PPPoE, Hotspot |
| Huawei OLT | SSH / SNMP | MA5608T, MA5683T | ONU Registration, VLAN, Service Profile |
| ZTE OLT | SSH / TL1 | C320, C300 | ONU Auth, Traffic Profile, VLAN Mapping |
| Generic Linux | SSH | Any Linux-based router | iptables, tc, VLAN, Bridge |
Rate Limiting
Provisioning operations dibatasi untuk mencegah overload pada device target.
| Plan | Provisions/jam | Concurrent | Devices Max |
|---|---|---|---|
| Pro | 50 | 3 | 10 |
| Enterprise | 500 | 20 | Unlimited |
Error Codes
| Code | Meaning | Resolution |
|---|---|---|
| PV-001 | Device unreachable — target perangkat tidak merespons SSH/API | Verifikasi konektivitas jaringan dan credential device |
| PV-002 | Config validation failed — konfigurasi tidak lolos pre-check | Review config template dan parameter input |
| PV-003 | Rollback triggered — eksekusi gagal, state dikembalikan | Cek log rollback untuk detail kegagalan |
| PV-004 | Billing sync timeout — engine billing tidak merespons | Retry otomatis aktif, eskalasi jika persisten |
| PV-005 | Capacity exceeded — node target sudah penuh | Gunakan auto-placement atau pilih node lain |
| PV-006 | Duplicate provision — pelanggan sudah aktif di device | Gunakan endpoint update atau deactivate terlebih dahulu |
Observability Metrics
| Metric | Unit | Deskripsi |
|---|---|---|
| pv.provision.duration_ms | ms | Durasi total provisioning end-to-end |
| pv.provision.success_rate | % | Persentase provisioning berhasil |
| pv.rollback.count | count/hr | Jumlah rollback per jam |
| pv.device.response_time | ms | Waktu respons device target |
| pv.billing.sync_lag | ms | Lag sinkronisasi ke billing engine |
| pv.queue.pending | count | Jumlah provisioning dalam antrian |
Webhook Events
Provisioning API mengirim webhook ke URL yang dikonfigurasi tenant untuk setiap perubahan status.
# Event Types
provision.started — Provisioning dimulai
provision.step_completed — Satu step selesai
provision.completed — Seluruh provisioning berhasil
provision.failed — Provisioning gagal
provision.rolled_back — Rollback selesai
device.status_changed — Device online/offline
# Webhook Payload
{
"event": "provision.completed",
"provision_id": "prov_abc123",
"tenant_id": "mitra_abc123",
"timestamp": "2026-05-19T00:00:02.340Z",
"data": { ... }
}