API Reference

Referensi endpoint HTTP + MQTT platform IncludeApps, untuk integrasi perangkat kustom (BYOD) dan aplikasi pihak ketiga. Kontrak otoritatif tetap ada di kode backend - dokumen ini dijaga selaras, tapi laporkan ke tim kami kalau menemukan perbedaan.

Konvensi

• Base URL: https://app.include.co.id/api/v1
• Autentikasi: hampir semua route memerlukan Authorization: Bearer <access_token> (kecuali /auth/*, /health, /public/*, dan /device/*).
• Response sukses: { data, meta } - meta berisi info paginasi (page/limit/total) bila relevan.
• Response error: { error, message }.
• Scoping: hampir semua data ber-group_id (Grup di dalam Organisasi Anda).

Auth

Method	Path	Keterangan
POST	/auth/register	Daftar user + organisasi baru
POST	/auth/login	Login, mengembalikan access + refresh token
POST	/auth/refresh	Perbarui access token
POST	/auth/logout	Invalidasi refresh token
POST	/auth/forgot-password	Kirim email reset password
POST	/auth/reset-password	Reset password dengan token
GET	/auth/google	Login dengan Google (redirect OAuth)

Devices

Method	Path	Keterangan
POST	/devices/claim	Claim device via Device ID/token
POST	/devices/custom	Daftarkan perangkat kustom/BYOD sendiri
GET	/devices	Daftar device (filter solusi/status/zona)
GET	/devices/:id	Detail device
PATCH	/devices/:id	Ubah device (nama, zona, kalibrasi)
DELETE	/devices/:id	Hapus device
POST	/devices/:id/command	Kirim perintah aktuator (publish MQTT)

Telemetry

Method	Path	Keterangan
GET	/telemetry/:deviceId	Nilai terakhir
GET	/telemetry/:deviceId/history	Historis (startTime, endTime, limit)
POST	/telemetry/:deviceId/import	Impor data historis (Pro+; tidak memicu alarm untuk data lampau)

Realtime: Server-Sent Events di /telemetry/stream (bukan WebSocket).

Alarms

Method	Path	Keterangan
GET	/alarms	Daftar alarm (filter status/severity)
PATCH	/alarms/:id/acknowledge	Acknowledge
PATCH	/alarms/:id/resolve	Resolve
POST	/devices/:id/thresholds	Atur ambang batas (optimal/warning/critical) per parameter

Dashboards

Method	Path	Keterangan
GET	/dashboards/:id	Detail (termasuk layout widget)
PATCH	/dashboards/:id	Simpan layout/widget

Rule Chains

Graf otomasi per-Organisasi yang berjalan tiap telemetry masuk - node deklaratif (filter/switch/transform) plus node scripting JavaScript sandboxed untuk logika custom.

Method	Path	Keterangan
GET	/rule-chains	Daftar chain
POST	/rule-chains	Buat chain
PUT	/rule-chains/:id	Ubah graph
POST	/rule-chains/test	Dry-run graph atas contoh nilai

Device API (khusus perangkat, pakai device token)

Dipakai firmware IncludeBox maupun perangkat kustom/BYOD - autentikasi memakai device token (bukan JWT user), bisa lewat header atau URL.

Method	Path	Keterangan
POST	/device/telemetry	Kirim telemetry (token di header X-Device-Token)
POST	/{token}/telemetry	Kirim telemetry, token di URL (gaya ThingsBoard - jalan langsung dari curl/PowerShell tanpa header custom)
GET	/{token}/mqtt-config	Ambil konfigurasi bootstrap MQTT (host, port, topic)
GET	/device/ota	Polling perintah OTA

MQTT

Broker EMQX. Konvensi topik:

includeapps/{group_id}/{solution_slug}/{device_id}/{telemetry|command|status}

• Backend subscribe includeapps/+/+/+/telemetry, memvalidasi payload, menyimpan ke TimescaleDB, mengevaluasi alarm/rule chain, lalu broadcast ke dashboard yang sedang terbuka - semua dalam hitungan detik.
• Autentikasi: deviceId sebagai MQTT username, device token sebagai password.
• command dipakai untuk kontrol aktuator & perintah OTA.

Contoh payload telemetry

Energy meter 1 fasa:

{
  "values": {
    "voltage": 220.5,
    "current": 2.1,
    "power": 462.3,
    "energy": 145.2,
    "frequency": 50.0,
    "power_factor": 0.95
  }
}

Energy meter 3 fasa:

{
  "values": {
    "voltage_r": 221.0,
    "voltage_s": 219.8,
    "voltage_t": 220.5,
    "current_r": 5.2,
    "current_s": 5.0,
    "current_t": 5.1,
    "total_power": 3350.0,
    "energy": 890.4,
    "frequency": 50.0,
    "power_factor": 0.92
  }
}

Field yang diterima mengikuti skema jenis perangkat (device_type_key) yang terdaftar untuk device tersebut - lihat Manage Devices di aplikasi untuk daftar parameter lengkap per tipe.