From 820a0600edb523064ca821fb745ac972c1c45eb6 Mon Sep 17 00:00:00 2001 From: mwpn Date: Thu, 18 Dec 2025 06:42:27 +0700 Subject: [PATCH] docs: update API_ENDPOINTS.md dengan endpoint baru dan field camera - Tambah dokumentasi GET /locations/{code} (detail location) - Tambah dokumentasi GET /gates/{location_code}/{gate_code} (detail gate) - Tambah dokumentasi GET /tariffs (list tariffs) - Tambah dokumentasi GET /tariffs/{location_code}/{gate_code}/{category} (detail tariff) - Tambah dokumentasi GET /audit-logs (audit trail) - Tambah dokumentasi GET /entry-events (raw entry events) - Tambah dokumentasi GET /realtime/events (realtime events list) - Update response examples untuk include field camera di gates - Tambah note tentang format camera (HLS, RTSP, HTTP, Camera ID) - Update daftar isi dengan struktur endpoint baru --- API_ENDPOINTS.md | 299 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) diff --git a/API_ENDPOINTS.md b/API_ENDPOINTS.md index 952117a..d10a0cc 100644 --- a/API_ENDPOINTS.md +++ b/API_ENDPOINTS.md @@ -12,6 +12,12 @@ Dokumentasi lengkap semua endpoint yang tersedia di API Btekno. - [Authentication](#authentication) - [Retribusi - Ingest](#retribusi---ingest) - [Retribusi - Frontend CRUD](#retribusi---frontend-crud) + - [Locations](#locations) + - [Gates](#gates) + - [Tariffs](#tariffs) + - [Streams](#streams) + - [Audit Logs](#audit-logs) + - [Entry Events](#entry-events) - [Retribusi - Summary](#retribusi---summary) - [Retribusi - Dashboard](#retribusi---dashboard) - [Retribusi - Realtime](#retribusi---realtime) @@ -187,6 +193,33 @@ Get list of locations dengan pagination. --- +#### Get Location Detail +**GET** `/retribusi/v1/frontend/locations/{code}` + +Get detail location berdasarkan code. + +**Response (200):** +```json +{ + "success": true, + "data": { + "code": "kerkof_01", + "name": "Kerkof 01", + "type": "kerkof", + "is_active": 1 + }, + "timestamp": 1703123456 +} +``` + +**Error Responses:** +- `404` - Location not found +- `422` - Invalid location code + +**Access:** Viewer, Operator, Admin + +--- + #### Create Location **POST** `/retribusi/v1/frontend/locations` @@ -294,6 +327,7 @@ Get list of gates dengan pagination. "gate_code": "gate01", "name": "Gate 01", "direction": "in", + "camera": "https://example.com/stream.m3u8", "is_active": 1 } ], @@ -311,6 +345,35 @@ Get list of gates dengan pagination. --- +#### Get Gate Detail +**GET** `/retribusi/v1/frontend/gates/{location_code}/{gate_code}` + +Get detail gate berdasarkan location_code dan gate_code. + +**Response (200):** +```json +{ + "success": true, + "data": { + "location_code": "kerkof_01", + "gate_code": "gate01", + "name": "Gate 01", + "direction": "in", + "camera": "https://example.com/stream.m3u8", + "is_active": 1 + }, + "timestamp": 1703123456 +} +``` + +**Error Responses:** +- `404` - Gate not found +- `422` - Invalid location_code or gate_code + +**Access:** Viewer, Operator, Admin + +--- + #### Create Gate **POST** `/retribusi/v1/frontend/gates` @@ -323,10 +386,17 @@ Create new gate. "gate_code": "gate02", "name": "Gate 02", "direction": "out", + "camera": "rtsp://192.168.1.100:554/stream1", "is_active": 1 } ``` +**Note:** Field `camera` optional, bisa diisi dengan: +- HLS URL: `https://example.com/stream.m3u8` +- RTSP URL: `rtsp://192.168.1.100:554/stream1` +- HTTP URL: `http://192.168.1.100:8080/camera1` +- Camera ID: `camera_001` + **Response (201):** ```json { @@ -336,6 +406,7 @@ Create new gate. "gate_code": "gate02", "name": "Gate 02", "direction": "out", + "camera": "rtsp://192.168.1.100:554/stream1", "is_active": 1 }, "timestamp": 1703123456 @@ -356,10 +427,17 @@ Update gate (location_code dan gate_code tidak bisa diubah). { "name": "Gate 02 Updated", "direction": "out", + "camera": "http://192.168.1.100:8080/hls/stream.m3u8", "is_active": 1 } ``` +**Note:** Field `camera` optional, bisa diisi dengan: +- HLS URL: `https://example.com/stream.m3u8` +- RTSP URL: `rtsp://192.168.1.100:554/stream1` +- HTTP URL: `http://192.168.1.100:8080/camera1` +- Camera ID: `camera_001` + **Response (200):** ```json { @@ -369,6 +447,7 @@ Update gate (location_code dan gate_code tidak bisa diubah). "gate_code": "gate02", "name": "Gate 02 Updated", "direction": "out", + "camera": "http://192.168.1.100:8080/hls/stream.m3u8", "is_active": 1 }, "timestamp": 1703123456 @@ -401,6 +480,72 @@ Soft delete gate (set `is_active = 0`). ### Tariffs +#### List Tariffs +**GET** `/retribusi/v1/frontend/tariffs` + +Get list of tariffs dengan pagination. + +**Query Parameters:** +- `page` (optional, default: 1) +- `limit` (optional, default: 20, max: 100) +- `location_code` (optional, filter) +- `gate_code` (optional, filter) + +**Response (200):** +```json +{ + "success": true, + "data": [ + { + "location_code": "kerkof_01", + "gate_code": "gate01", + "category": "motor", + "price": 5000, + "location_name": "Kerkof 01", + "gate_name": "Gate 01" + } + ], + "meta": { + "page": 1, + "limit": 20, + "total": 10, + "pages": 1 + }, + "timestamp": 1703123456 +} +``` + +**Access:** Viewer, Operator, Admin + +--- + +#### Get Tariff Detail +**GET** `/retribusi/v1/frontend/tariffs/{location_code}/{gate_code}/{category}` + +Get detail tariff berdasarkan location_code, gate_code, dan category. + +**Response (200):** +```json +{ + "success": true, + "data": { + "location_code": "kerkof_01", + "gate_code": "gate01", + "category": "motor", + "price": 5000 + }, + "timestamp": 1703123456 +} +``` + +**Error Responses:** +- `404` - Tariff not found +- `422` - Invalid location_code, gate_code, or category + +**Access:** Viewer, Operator, Admin + +--- + #### Create Tariff **POST** `/retribusi/v1/frontend/tariffs` @@ -523,6 +668,113 @@ Get list of streams (alias untuk gates). --- +### Audit Logs + +#### List Audit Logs +**GET** `/retribusi/v1/frontend/audit-logs` + +Get audit trail history dengan pagination dan filter. + +**Query Parameters:** +- `page` (optional, default: 1) +- `limit` (optional, default: 20, max: 100) +- `entity` (optional, filter: `locations|gates|tariffs`) +- `action` (optional, filter: `create|update|delete`) +- `entity_key` (optional, filter by specific entity key) +- `start_date` (optional, format: YYYY-MM-DD) +- `end_date` (optional, format: YYYY-MM-DD) + +**Response (200):** +```json +{ + "success": true, + "data": [ + { + "id": 123, + "actor_user_id": 1, + "actor_username": "admin", + "actor_role": "admin", + "action": "update", + "entity": "locations", + "entity_key": "kerkof_01", + "before_json": { + "code": "kerkof_01", + "name": "Kerkof 01", + "type": "kerkof", + "is_active": 1 + }, + "after_json": { + "code": "kerkof_01", + "name": "Kerkof 01 Updated", + "type": "kerkof", + "is_active": 1 + }, + "ip_address": "192.168.1.100", + "user_agent": "Mozilla/5.0...", + "created_at": "2025-01-17 10:30:00" + } + ], + "meta": { + "page": 1, + "limit": 20, + "total": 150, + "pages": 8 + }, + "timestamp": 1703123456 +} +``` + +**Access:** Viewer, Operator, Admin + +--- + +### Entry Events + +#### List Entry Events +**GET** `/retribusi/v1/frontend/entry-events` + +Get list of raw entry events (data mentah dari mesin) dengan pagination dan filter. + +**Query Parameters:** +- `page` (optional, default: 1) +- `limit` (optional, default: 20, max: 100) +- `location_code` (optional, filter) +- `gate_code` (optional, filter) +- `category` (optional, filter) +- `start_date` (optional, format: YYYY-MM-DD) +- `end_date` (optional, format: YYYY-MM-DD) + +**Response (200):** +```json +{ + "success": true, + "data": [ + { + "id": 12345, + "location_code": "kerkof_01", + "gate_code": "gate01", + "category": "motor", + "event_time": "2025-01-17 10:30:00", + "source_ip": "192.168.1.100", + "created_at": "2025-01-17 10:30:01" + } + ], + "meta": { + "page": 1, + "limit": 20, + "total": 5000, + "pages": 250 + }, + "timestamp": 1703123456 +} +``` + +**Access:** Viewer, Operator, Admin + +**Note:** Endpoint ini berguna untuk debugging dan admin untuk melihat raw event data. + +--- + ## Retribusi - Summary Semua endpoint di bawah ini memerlukan **JWT Authentication**. @@ -803,6 +1055,53 @@ Get snapshot data untuk real-time dashboard cards. --- +### Realtime Events + +#### List Realtime Events +**GET** `/retribusi/v1/realtime/events` + +Get list of realtime events (history events untuk SSE) dengan pagination dan filter. + +**Query Parameters:** +- `page` (optional, default: 1) +- `limit` (optional, default: 20, max: 100) +- `location_code` (optional, filter) +- `gate_code` (optional, filter) +- `category` (optional, filter) +- `start_date` (optional, format: YYYY-MM-DD) +- `end_date` (optional, format: YYYY-MM-DD) + +**Response (200):** +```json +{ + "success": true, + "data": [ + { + "id": 12345, + "location_code": "kerkof_01", + "gate_code": "gate01", + "category": "motor", + "event_time": 1703123456, + "total_count_delta": 1, + "created_at": "2025-01-17 10:30:01" + } + ], + "meta": { + "page": 1, + "limit": 20, + "total": 1000, + "pages": 50 + }, + "timestamp": 1703123456 +} +``` + +**Access:** Viewer, Operator, Admin + +**Note:** `event_time` adalah Unix timestamp (integer). Endpoint ini untuk melihat history events yang sudah masuk ke realtime_events table. + +--- + ## Error Responses Semua endpoint mengembalikan error dalam format konsisten: