Ringkasan Integrasi API: Dashboard Pengiriaman Surat Konfirmasi x ETLENAS
Dokumentasi API ini digunakan untuk integrasi antara sistem ETLENAS dengan
Dashboard Pengiriman Surat Konfirmasi ETLE Korlantas (Kirim Dokumen Polri). Melalui
integrasi ini, sistem ETLENAS dapat mengirim data pelanggaran secara otomatis, memvalidasi ID Region
Polres, serta melacak status dokumen.
Base URL API
Semua pemanggilan endpoint API diarahkan ke Base URL berikut:
https://api.dashboardkonfirmasi.org
PENTING: Untuk dapat melakukan integrasi, akun yang digunakan harus memiliki role
Integrator. Hubungi administrator sistem untuk mendapatkan kredensial
(username & password) dengan role tersebut sebelum memulai.
Mekanisme Autentikasi
Semua API (kecuali login) memerlukan autentikasi menggunakan Bearer Token yang dikirimkan
melalui header HTTP:
Authorization: Bearer {your_jwt_token_here}
Token diperoleh dari endpoint /user/login dan memiliki masa kedaluwarsa sesuai waktu yang
ditentukan pada response login.
2. Kirim Data Violation (Capture)
Mengirimkan data pelanggaran lalu lintas dari ETLENAS ke sistem Kirim Dokumen. Endpoint ini mendukung
pengiriman tunggal (single) maupun banyak (multiple) data sekaligus dalam satu request.
POST
/integrate/etlenas/capture
Request Body (Array of ViolationData)
| Field |
Tipe |
Wajib |
Keterangan |
Contoh |
plate_no |
String |
Ya |
Nomor plat kendaraan |
"B1234ABC" |
violation |
String |
Ya |
Jenis/deskripsi pelanggaran |
"Melanggar Rambu Lalu Lintas" |
location_description |
String |
Ya |
Lokasi kejadian pelanggaran |
"Jl. Sudirman KM 5" |
owner_name |
String |
Ya |
Nama pemilik kendaraan |
"Budi Santoso" |
owner_address |
String |
Ya |
Alamat pemilik kendaraan |
"Jl. Merdeka No. 123, Jakarta Pusat" |
phone_number |
String |
Tidak |
Nomor telepon pemilik (opsional) |
"081234567890" |
confirmation_code |
String |
Ya |
Kode konfirmasi unik surat konfirmasi |
"CONF-2026-001" |
date |
String |
Ya |
Tanggal & waktu kejadian (ISO 8601) |
"2026-06-21T10:30:00Z" |
id_region |
String |
Salah satu* |
ID Region Polres (atau Polda, untuk surat Ditlantas Polda) tujuan. Diprioritaskan kalau diisi (lebih presisi). |
"RES_KNDL054" |
sender_name |
String |
Salah satu* |
Alternatif dari id_region — nama Polres tujuan, atau nama Polda (mis. "Polda Bali") untuk surat yang diterbitkan Ditlantas Polda, dicocokkan ke data satuan
(case-insensitive, spasi di awal/akhir diabaikan). Dipakai kalau id_region kosong.
|
"Polres Kendal" |
ref_no |
String |
Ya |
Nomor referensi unik dari ETLENAS |
"ETLENAS-REF-001" |
send_wa |
Boolean |
Tidak |
Permintaan notifikasi WhatsApp ke pemilik kendaraan (nomor di
phone_number). Default false — kalau tidak diisi atau
false, tidak ada WA yang terkirim. Kalau true, WA dikirim selama saklar
WA Otomatis Polres tujuan di dashboard aktif; kalau
nonaktif, dicatat skipped. |
true |
photo_url |
String (URL) |
Tidak |
Link foto kendaraan dari kamera ETLE, untuk ditampilkan di notifikasi WhatsApp &
detail dokumen. Boleh http:// atau https://, bisa diakses publik dari internet tanpa login/token
(diunduh langsung oleh server WhatsApp, bukan disimpan oleh kami), format JPG/PNG maks. 5 MB (batas dari WhatsApp — foto yang lebih besar tidak bisa tampil di WA), dan tetap berlaku minimal
beberapa hari (WA dikirim lewat antrian). Link yang tidak valid tidak menggagalkan
data — fotonya saja yang diabaikan (lihat photo_status). |
"https://storage.etlenas.example/foto/ETLENAS-REF-003.jpg" |
Notifikasi WhatsApp (send_wa): dikirim hanya untuk data dengan
send_wa: true yang masuk ke Polres dengan saklar WA Otomatis aktif (default
aktif; diatur admin di dashboard per Polres). Kalau saklar nonaktif, wa_status =
skipped dengan wa_message
"WA otomatis dimatikan untuk satuan ini". Data tetap disimpan seperti biasa, lalu WA
dimasukkan ke antrian dan dikirim bertahap (satu per satu dengan jeda, supaya nomor
pengirim tidak dianggap spam). Karena itu response capture tidak menunggu WA terkirim
— status awalnya queued. Pantau statusnya lewat
Check Document Status (objek wa: terkirim, sampai di HP, dibaca,
atau gagal). Kalau phone_number kosong / tidak valid, WA langsung berstatus
skipped. Gagal kirim dicoba ulang otomatis sampai 5x. Satu surat tidak akan menerima WA dua
kali.
* Salah satu wajib diisi: id_region atau sender_name. Kalau
id_region diisi, sistem selalu memakainya (walau sender_name juga ikut
dikirim). Kalau id_region kosong, sistem mencocokkan sender_name ke nama
satuan Polres yang terdaftar — harus persis penulisannya (hanya kapitalisasi & spasi di
awal/akhir yang diabaikan, bukan pencocokan sebagian/typo). Kalau dua-duanya kosong, request ditolak.
Contoh Request Body
[
{
"plate_no": "B1234ABC",
"violation": "Melanggar Rambu Lalu Lintas",
"location_description": "Jl. Sudirman KM 5",
"owner_name": "Budi Santoso",
"owner_address": "Jl. Merdeka No. 123, Jakarta Pusat",
"phone_number": "081234567890",
"confirmation_code": "CONF-2026-001",
"date": "2026-06-21T10:30:00Z",
"sender_name": "Polres Kendal",
"ref_no": "ETLENAS-REF-001"
}
]
Contoh Request Body (dengan notifikasi WhatsApp, send_wa)
Tambahkan "send_wa": true pada data yang ingin sekaligus dikirimi WhatsApp ke pemilik
kendaraan. Bisa dicampur dalam satu request — data tanpa send_wa (atau
false) tidak dikirimi WA. Kalau WA Otomatis Polres tujuan nonaktif, WA
tidak dikirim walau send_wa: true (status skipped).
[
{
"plate_no": "B1234ABC",
"violation": "Melanggar Rambu Lalu Lintas",
"location_description": "Jl. Sudirman KM 5",
"owner_name": "Budi Santoso",
"owner_address": "Jl. Merdeka No. 123, Jakarta Pusat",
"phone_number": "081234567890",
"confirmation_code": "CONF-2026-003",
"date": "2026-06-21T10:30:00Z",
"sender_name": "Polres Kendal",
"ref_no": "ETLENAS-REF-003",
"send_wa": true,
"photo_url": "https://storage.etlenas.example/foto/ETLENAS-REF-003.jpg"
}
]
Responses
200 OK
(Success)
{
"message": "Documents received successfully",
"data": [
{
"plate_no": "B1234ABC",
"violation": "Melanggar Rambu Lalu Lintas",
"location_description": "Jl. Sudirman KM 5",
"owner_name": "Budi Santoso",
"owner_address": "Jl. Merdeka No. 123, Jakarta Pusat",
"phone_number": "081234567890",
"confirmation_code": "CONF-2026-001",
"date": "2026-06-21T10:30:00Z",
"sender_name": "Polres Kendal",
"ref_no": "ETLENAS-REF-003",
"send_wa": true,
"photo_url": "https://storage.etlenas.example/foto/ETLENAS-REF-003.jpg"
}
],
"count": 1,
"results": [
{
"ref_no": "ETLENAS-REF-003",
"id": 123,
"no_resi": "SKETLE00123",
"wa_status": "queued",
"photo_status": "ok"
}
]
}
data & count berisi ulang payload yang dikirim (sama seperti sebelumnya).
results berisi hasil per data: id dokumen, no_resi, dan — kalau
send_wa: true — wa_status awal (queued atau
skipped, disertai wa_message berisi alasannya). Tanpa send_wa,
field wa_status tidak muncul. Kalau photo_url dikirim, ada
photo_status: ok (foto disimpan) atau alasan foto diabaikan, mis.
diabaikan: photo_url bukan URL yang valid.
400 Bad
Request — ID Region tidak ditemukan
{
"error": "Polres dengan ID Region 'RES_INVALID' tidak ditemukan",
"message": "Pastikan ID Region sudah benar dan terdaftar di sistem"
}
400 Bad
Request — sender_name tidak ditemukan
{
"error": "Polres dengan nama 'Polres Tidak Ada' tidak ditemukan",
"message": "Pastikan penulisan sender_name sudah sesuai dengan nama satuan yang terdaftar di sistem"
}
400 Bad
Request — keduanya kosong
{
"error": "id_region atau sender_name wajib diisi",
"message": "Sertakan salah satu untuk menentukan Polres tujuan"
}
3. Check ID Region
Validasi apakah ID Region Polres tujuan valid dan aktif, serta mendapatkan sisa alokasi pengiriman (volume
remaining).
GET
/integrate/etlenas/check-region/{id_region}
Path Parameters
| Parameter |
Tipe |
Wajib |
Keterangan |
Contoh |
id_region |
String |
Ya |
ID Region Polres yang ingin dicek |
"RES_KNDL054" |
Responses
200 OK
(Success)
{
"valid": true,
"polres": {
"id": 1,
"name": "Polres Kendal",
"id_region": "RES_KNDL054",
"address": "Jl. Soekarno Hatta No. 1, Kendal",
"phone": "0294-381234",
"active": true,
"volume_remaining": 500,
"polda": {
"id": 1,
"name": "Polda Jawa Tengah"
}
},
"message": "ID Region valid dan siap menerima data"
}
404 Not
Found (Error)
{
"valid": false,
"message": "ID Region tidak ditemukan",
"id_region": "INVALID_ID",
"suggestion": "Pastikan ID Region sudah terdaftar di sistem"
}
4. Check Document Status (Tracking) BARU
Diperbarui 5 November 2026: status WhatsApp sekarang ada di objek wa
(status, reason, sent_at, delivered_at,
read_at), termasuk status sampai di HP dan dibaca. Field lama wa_requested,
wa_status, wa_sent, wa_sent_at, dan wa_message di
endpoint ini sudah dihapus.
Melacak status terkini dokumen pengiriman yang telah dikirim ke sistem berdasarkan nomor referensi
(ref_no).
GET
/integrate/etlenas/document/{ref_no}
Path Parameters
| Parameter |
Tipe |
Wajib |
Keterangan |
Contoh |
ref_no |
String |
Ya |
Nomor referensi unik pelanggaran dari ETLENAS |
"ETLENAS-REF-001" |
Status Alur Dokumen
Nilai status dokumen pada response dapat berubah secara dinamis seiring jalannya proses pengiriman fisik
surat konfirmasi:
new
→
preprocess
→
process
→
assigned
→
pickup
→
delivered
/
returned
Responses
200 OK
(Success)
{
"found": true,
"document": {
"id": 123,
"ref_no": "ETLENAS-REF-001",
"plate_no": "B1234ABC",
"status": "new",
"violation": "Melanggar Rambu Lalu Lintas",
"recipient": "Budi Santoso",
"created_at": "2026-06-21T10:30:00Z",
"polres": {
"id": 1,
"name": "Polres Kendal"
},
"photo_url": "https://.../foto-kendaraan.jpg",
"wa": {
"status": "delivered",
"reason": null,
"sent_at": "2026-06-21T10:31:04+07:00",
"delivered_at": "2026-06-21T10:31:06+07:00",
"read_at": null
}
},
"message": "Dokumen ditemukan"
}
Status Notifikasi WhatsApp BARU
| Field |
Keterangan |
photo_url |
Link foto kendaraan yang tersimpan untuk dokumen ini (tidak muncul kalau tidak ada foto). |
wa |
Status WA ke pemilik kendaraan, otomatis maupun dikirim manual oleh petugas.
null kalau dokumen ini tidak punya WA. |
wa.status |
queued = menunggu antrian,
sending = sedang dikirim,
accepted = diterima WhatsApp, belum ada kabar dari HP penerima,
sent = keluar dari server WhatsApp,
delivered = sampai di HP penerima,
read = dibaca penerima,
failed = gagal (setelah 5x percobaan, atau WhatsApp tidak bisa menyampaikan),
skipped = tidak dikirim (mis. nomor telepon kosong, atau WA Otomatis Polres
nonaktif),
expired = belum sempat terkirim dalam 24 jam di antrian sehingga dibatalkan
(petugas bisa mengirim ulang; statusnya kembali queued). |
wa.reason |
Alasan kalau failed / skipped / expired, mis.
131026: Message undeliverable (nomor tidak terdaftar di WhatsApp).
null untuk status lain. |
wa.sent_at |
Waktu WA diterima WhatsApp (RFC3339), atau null. |
wa.delivered_at |
Waktu WA sampai di HP penerima (RFC3339), atau null. Bisa tertunda kalau HP
penerima mati. |
wa.read_at |
Waktu WA dibuka penerima (RFC3339), atau null. Tetap null kalau
penerima mematikan centang biru. |
404 Not
Found (Error)
{
"found": false,
"message": "Dokumen tidak ditemukan",
"ref_no": "INVALID-REF",
"suggestion": "Pastikan reference number sudah benar atau dokumen sudah dikirim"
}