API integrasi untuk sistem eksternal

Endpoint eksternal berada di prefix /api/external/v1. Endpoint ini tenant-scoped, artinya token hanya dapat membaca atau menulis data tenant yang tercantum pada ability token.

Semua request external API wajib mengirim header:

Authorization: Bearer <TOKEN_API_INTEGRASI>
Accept: application/json
Content-Type: application/json

Token dibuat dari panel Netadmin/API internal oleh admin tenant. Token hanya ditampilkan satu kali saat dibuat, jadi simpan di secret manager sistem eksternal.

Endpoint ini dipakai oleh admin tenant yang sudah login ke aplikasi. Di UI, admin dapat mengelola token dari Pengaturan → API Integrasi. Jangan dipakai oleh sistem eksternal untuk membuat token sendiri.

Daftar token bersifat tenant-wide: admin tenant dapat melihat dan revoke token integrasi milik tenant aktif, termasuk token yang dibuat admin lain.

Endpoint list memakai pagination Laravel. Parameter umum:

• per_page: jumlah data per halaman, maksimum 100.
• page: halaman yang diminta.
• search: pencarian teks sesuai endpoint.
• updated_since: ambil data yang berubah sejak waktu ISO 8601 tertentu.

Endpoint Netadmin POST /api/tickets/resolve-all menyelesaikan tiket aktif yang sudah memenuhi syarat proses dan dokumentasi penanganan. Request menerima field resolution untuk catatan resolusi massal.

Reopen tiket selesai hanya boleh dilakukan oleh Administrator atau Super Admin. Jika user teknisi mencoba mengubah tiket resolved/closed kembali ke open atau inprogress, API mengembalikan validasi jelas agar reopen dilakukan lewat admin.

Endpoint ini dipakai menu Netadmin Absensi untuk check-in/check-out dengan GPS dan selfie, multi Home Base per staff, jadwal fleksibel, gaji pokok/THP, pengajuan izin/cuti/sakit/koreksi, kuota cuti, notifikasi approval WA/Telegram, payroll Absensi, audit trail, work log jadwal/tiket, approval lembur, export CSV, dan pengaturan jam kerja tenant.

Modul OLT Device mendukung vendor fiberhome untuk FiberHome GPON AN5516/AN5506. Form Netadmin memakai endpoint OLT SNMP existing: GET /api/olt-snmp/profiles, GET /api/olt-snmp, POST /api/olt-snmp, dan PUT /api/olts/{id}/snmp.

Endpoint ini dipakai Netadmin untuk konfigurasi email client per user pada menu Akun Saya. Incoming memakai IMAP/POP3 untuk menarik email ke Inbox lokal, outgoing memakai SMTP akun untuk reply email. Email asli tetap disimpan di server; delete Inbox/Outbox hanya menghapus salinan lokal.

Endpoint ini dipakai Netadmin pada menu Akun Saya > Keamanan untuk mengatur Login Multi Device, batas maksimal device aktif, daftar sesi NetAdmin, dan pencabutan sesi/device lain.

Endpoint ini dipakai Netadmin untuk modul Penjualan. Modul bersifat tenant-scoped dan membutuhkan permission sales.* serta module tenant sales aktif.

Endpoint ini dipakai Netadmin untuk modul Data Keuangan tenant. Akses lihat memakai permission invoices.view, sedangkan input akun, kategori, dan transaksi memakai invoices.manage. Endpoint pelunasan invoice dapat mengirim finance_account_id agar payment record direkonsiliasi ke akun Kas/Bank.

Endpoint ini dipakai Netadmin untuk request dana operasional, reimbursement/claim uang pribadi staff, uang bensin, pembelian barang, dan kasbon/advance. Staff dapat membuat dan melihat request sendiri; Administrator/Super Admin dapat melihat semua request dan melakukan approval/pembayaran.

Endpoint ini dipakai Platform Admin untuk merencanakan provisioning tenant multi-database: database tenant, DNS Cloudflare, mailbox Virtualmin, dan storage prefix.

Versi awal ini bersifat preview/draft. Endpoint tidak membuat database production, tidak mengubah DNS, dan tidak membuat mailbox sampai side effect diaktifkan dengan approval eksplisit.

Endpoint ini dipakai panel Netadmin tenant yang sudah login, bukan token external API. Konfigurasi bersifat tenant-scoped.

Untuk provider Wablas, WatZap, BalesOtomatis.id, dan Pancake, settings.base_url dapat diisi manual oleh tenant. WatZap memakai default https://api.watzap.id/v1 jika Base URL kosong.

Provider WatZap memakai wa_token sebagai API Key dan endpoint kirim POST /send_message dengan payload api_key, number, dan message.

Provider Pancake memakai wa_token sebagai Page Access Token, wa_secret_key sebagai Page ID, dan endpoint https://pages.fm/api/public_api/v1. Test/kirim Pancake memakai Conversation ID, bukan nomor HP biasa.

Default pengiriman WhatsApp Bot adalah settings.max_messages_per_minute = 3 dan settings.message_delay_seconds = 10. Gunakan nilai 0 jika tenant ingin tanpa batas atau tanpa jeda.

WhatsApp Bot mendukung banyak akun per provider melalui settings.accounts. Pengiriman memakai routing otomatis: satu akun aktif memakai akun tersebut, sedangkan beberapa akun aktif dikirim bergantian round-robin. Pesan gagal tidak dialihkan otomatis ke akun lain dan dapat dikirim ulang manual dari Outbox.

Endpoint POST /api/wabot/test menerima account_id opsional agar panel dapat mengetes koneksi dan kirim pesan memakai akun provider tertentu, bukan test global provider aktif. Untuk Wablas, field is_group=true dapat dipakai bersama Group ID sebagai phone untuk test kirim ke grup.

Endpoint POST /api/wabot/sync-status mengecek report realtime Wablas untuk pesan pending tanpa retry. Jika API Wablas sedang membalas error sementara, endpoint tetap mengembalikan HTTP 200 dengan warning=true agar polling halaman tidak terganggu dan sistem bisa mencoba lagi otomatis.

Endpoint POST /api/wabot/sync-device-status mengecek status device Wablas langsung dari API device info agar panel tidak hanya bergantung pada webhook device.

Semua provider menampilkan webhook_url untuk pesan masuk. Tempel URL ini di dashboard provider agar pesan inbound masuk ke bot Kliniktech.

Statistik dan log WhatsApp Bot membaca communication_messages channel WhatsApp agar Inbox/Outbox dari webhook, notifikasi, test kirim, provider, dan akun pengirim tetap konsisten. Sinkron status tidak melakukan retry pesan gagal.

Endpoint ini dipakai panel Netadmin yang sudah login dengan permission Mitra. Detail Mitra dapat menampilkan pelanggan internet terhubung, invoice, pembayaran, tiket, kontrak, dan dokumen.

Paket khusus Mitra ditandai dari modul Paket Internet melalui field is_partner_package. Saat membuat pelanggan dari Mitra, sistem mewajibkan paket khusus Mitra agar harga layanan partner tidak bercampur dengan paket pelanggan umum.

Endpoint ini dipakai panel Netadmin tenant yang sudah login dengan permission inventory. Import barang supplier selalu memakai alur preview dulu agar data katalog tidak langsung masuk tanpa pengecekan operator.

Request Barang multi-item memakai header request dan baris item. Status workflow: draft, pending, deferred, approved, rejected, processing, completed, dan cancelled. Saat diproses, sistem membuat mutasi inventaris per item.

File yang didukung: CSV, TXT, XLSX, dan PDF. PDF diparse best-effort sehingga hasil preview wajib dicek dan dikoreksi sebelum import.

Import membuat atau memperbarui master barang, lalu menautkan harga beli ke supplier. Import tidak menambah stok gudang; stok tetap masuk melalui flow Stok Masuk.

Endpoint ini dipakai panel Netadmin yang sudah login. File Manager memisahkan file tenant menjadi private untuk folder pribadi user dan shared untuk folder umum tenant.

Admin tenant dapat melihat semua folder user dalam tenantnya. Superadmin atau tenant master dapat memakai query tenant_id untuk audit/support lintas tenant.

Endpoint ini dipakai panel Netadmin yang sudah login di tenant master. File Share berfungsi sebagai repository file internal untuk dokumen, APK, laporan, export, template, dan arsip verifikasi backup.

Jika S3 Object Storage tenant master aktif, file disimpan ke S3. Jika belum aktif, sistem menggunakan local fallback dan tetap menampilkan label storage yang jelas.

Endpoint ini dipakai NetAdmin untuk menjaga akses tiket teknisi, rekomendasi assign manual, dan incident massal. Role teknisi hanya melihat tiket yang ditugaskan, diklaim, atau mencatat dirinya sebagai anggota tim.

Endpoint POST /api/tickets/incidents menerima field tambahan home_base_id, severity, estimated_recovery_at, impact_area, root_cause_initial, impact_ticket_description, group_message, auto_link_tickets, create_impact_tickets, schedule_impact_tickets, notify_customers, notify_whatsapp_groups, auto_link_limit, dan impact_ticket_limit. Jika auto-link atau create-ticket aktif tanpa OLT/Home Base yang bisa dipetakan ke ONU, backend melewati proses massal agar tidak menautkan/membuat tiket untuk semua pelanggan.

Notifikasi group memakai event ticket_incident_created / label Incident Massal. Atur group tujuan dari WhatsApp Bot dengan mencentang event tersebut pada group NOC/teknisi.

Endpoint ini dipakai NetAdmin yang sudah login dengan permission settings.view / settings.manage. Field ai_assistant_enabled mengatur visibilitas tombol Bantuan AI per tenant dan defaultnya false.

Endpoint ini dipakai oleh UI portal pelanggan setelah login pelanggan. Reopen tiket dari portal hanya aktif jika admin mengizinkan di Pengaturan → SLA Tiket → Opsi Reopen Tiket Selesai.

Endpoint ini dipakai panel Netadmin yang sudah login dengan permission APK Builder. Konfigurasi bersifat tenant-scoped dan app type yang didukung adalah portal, netadmin, partner, dan absensi.

Untuk absensi, isi base_url dengan domain utama aplikasi. Builder otomatis mengarahkan Capacitor server URL ke /absensi/, sehingga theme, login, kamera, liveness, GPS, dan fitur teknisi mengikuti portal Absensi yang sudah ada.

Ambil pelanggan aktif

curl "https://apps.ion.net.id/api/external/v1/customers?status=active&per_page=50" \
  -H "Authorization: Bearer 1|TOKEN..." \
  -H "Accept: application/json"

Buat pelanggan baru

curl -X POST https://apps.ion.net.id/api/external/v1/customers \
  -H "Authorization: Bearer 1|TOKEN_READ_WRITE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Budi Santoso",
    "phone": "081234567890",
    "email": "budi@example.com",
    "address": "Jl. Merdeka No. 10",
    "package_id": 12,
    "service_type": "pppoe",
    "billing_cycle": "prepaid"
  }'

Buat tiket gangguan

curl -X POST https://apps.ion.net.id/api/external/v1/tickets \
  -H "Authorization: Bearer 1|TOKEN_READ_WRITE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 101,
    "type": "Internet lambat",
    "priority": "medium",
    "description": "Dilaporkan dari CRM eksternal",
    "contact_name": "Budi",
    "contact_phone": "081234567890",
    "external_id": "CRM-88991"
  }'

Contoh response list

{
  "current_page": 1,
  "data": [
    {
      "id": 101,
      "code": "CST-21017890",
      "name": "Budi Santoso",
      "phone": "081234567890",
      "status": "active",
      "package": {"id": 12, "name": "Home 30 Mbps"}
    }
  ],
  "per_page": 50,
  "total": 1
}

Flow ini dipakai saat operator membuat pelanggan DHCP/Static tanpa mengetahui MAC ONU/CPE. Pelanggan disimpan dulu, kemudian lease DHCP dari VyOS yang sudah online dihubungkan ke pelanggan.

{
  "customer_id": 123,
  "mac_address": "aa:bb:cc:dd:ee:ff",
  "address": "10.10.20.15",
  "router_id": 2,
  "sync": true
}

Error 422 dibuat eksplisit: lease tanpa MAC/IP valid, pelanggan bukan tipe DHCP/Static, MAC sudah dipakai pelanggan lain, atau NAS VyOS tidak aktif.