918 lines
14 KiB
Markdown
918 lines
14 KiB
Markdown
# API Endpoints Documentation
|
|
|
|
Dokumentasi lengkap semua endpoint yang tersedia di API Btekno.
|
|
|
|
**Base URL**: `https://api.btekno.cloud`
|
|
|
|
---
|
|
|
|
## 📋 Daftar Isi
|
|
|
|
- [Public Endpoints](#public-endpoints)
|
|
- [Authentication](#authentication)
|
|
- [Retribusi - Ingest](#retribusi---ingest)
|
|
- [Retribusi - Frontend CRUD](#retribusi---frontend-crud)
|
|
- [Retribusi - Summary](#retribusi---summary)
|
|
- [Retribusi - Dashboard](#retribusi---dashboard)
|
|
- [Retribusi - Realtime](#retribusi---realtime)
|
|
|
|
---
|
|
|
|
## Public Endpoints
|
|
|
|
### Health Check
|
|
**GET** `/health`
|
|
|
|
Health check endpoint untuk monitoring.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"time": 1703123456
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Documentation
|
|
**GET** `/`
|
|
|
|
Redirect ke `/docs` (Swagger UI).
|
|
|
|
**GET** `/docs`
|
|
|
|
Swagger UI documentation (public access).
|
|
|
|
**GET** `/docs/openapi.json`
|
|
|
|
OpenAPI 3.0 specification JSON.
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
### Login
|
|
**POST** `/auth/v1/login`
|
|
|
|
Login untuk mendapatkan JWT token.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"username": "admin",
|
|
"password": "password123"
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
|
"expires_in": 3600,
|
|
"user": {
|
|
"id": 1,
|
|
"username": "admin",
|
|
"role": "admin"
|
|
}
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Error Responses:**
|
|
- `401` - Invalid credentials
|
|
- `403` - User inactive
|
|
- `422` - Validation error
|
|
|
|
**Authentication:** None (public endpoint)
|
|
|
|
---
|
|
|
|
## Retribusi - Ingest
|
|
|
|
### Ingest Event
|
|
**POST** `/retribusi/v1/ingest`
|
|
|
|
Endpoint untuk mesin/IoT mengirim event data.
|
|
|
|
**Headers:**
|
|
```
|
|
X-API-KEY: your-api-key-here
|
|
Content-Type: application/json
|
|
```
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"timestamp": 1703123456,
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"category": "motor"
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"stored": true
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Error Responses:**
|
|
- `401` - Invalid API key
|
|
- `404` - Location/Gate/Tariff not found
|
|
- `422` - Validation error
|
|
|
|
**Authentication:** `X-API-KEY` header
|
|
|
|
**Category Values:**
|
|
- `person_walk`
|
|
- `motor`
|
|
- `car`
|
|
|
|
---
|
|
|
|
## Retribusi - Frontend CRUD
|
|
|
|
Semua endpoint di bawah ini memerlukan **JWT Authentication**.
|
|
|
|
**Headers:**
|
|
```
|
|
Authorization: Bearer <jwt-token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### Locations
|
|
|
|
#### List Locations
|
|
**GET** `/retribusi/v1/frontend/locations`
|
|
|
|
Get list of locations dengan pagination.
|
|
|
|
**Query Parameters:**
|
|
- `page` (optional, default: 1)
|
|
- `limit` (optional, default: 20, max: 100)
|
|
- `location_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"code": "kerkof_01",
|
|
"name": "Kerkof 01",
|
|
"type": "kerkof",
|
|
"is_active": 1
|
|
}
|
|
],
|
|
"meta": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 10,
|
|
"pages": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
#### Create Location
|
|
**POST** `/retribusi/v1/frontend/locations`
|
|
|
|
Create new location.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"code": "kerkof_02",
|
|
"name": "Kerkof 02",
|
|
"type": "kerkof",
|
|
"is_active": 1
|
|
}
|
|
```
|
|
|
|
**Response (201):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"code": "kerkof_02",
|
|
"name": "Kerkof 02",
|
|
"type": "kerkof",
|
|
"is_active": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Operator, Admin
|
|
|
|
---
|
|
|
|
#### Update Location
|
|
**PUT** `/retribusi/v1/frontend/locations/{code}`
|
|
|
|
Update location (code tidak bisa diubah).
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "Kerkof 02 Updated",
|
|
"type": "kerkof",
|
|
"is_active": 1
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"code": "kerkof_02",
|
|
"name": "Kerkof 02 Updated",
|
|
"type": "kerkof",
|
|
"is_active": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Operator, Admin
|
|
|
|
---
|
|
|
|
#### Delete Location
|
|
**DELETE** `/retribusi/v1/frontend/locations/{code}`
|
|
|
|
Soft delete location (set `is_active = 0`).
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"deleted": true
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Admin only
|
|
|
|
---
|
|
|
|
### Gates
|
|
|
|
#### List Gates
|
|
**GET** `/retribusi/v1/frontend/gates`
|
|
|
|
Get list of gates dengan pagination.
|
|
|
|
**Query Parameters:**
|
|
- `page` (optional, default: 1)
|
|
- `limit` (optional, default: 20, max: 100)
|
|
- `location_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"name": "Gate 01",
|
|
"direction": "in",
|
|
"is_active": 1
|
|
}
|
|
],
|
|
"meta": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 5,
|
|
"pages": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
#### Create Gate
|
|
**POST** `/retribusi/v1/frontend/gates`
|
|
|
|
Create new gate.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate02",
|
|
"name": "Gate 02",
|
|
"direction": "out",
|
|
"is_active": 1
|
|
}
|
|
```
|
|
|
|
**Response (201):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate02",
|
|
"name": "Gate 02",
|
|
"direction": "out",
|
|
"is_active": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Operator, Admin
|
|
|
|
---
|
|
|
|
#### Update Gate
|
|
**PUT** `/retribusi/v1/frontend/gates/{location_code}/{gate_code}`
|
|
|
|
Update gate (location_code dan gate_code tidak bisa diubah).
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "Gate 02 Updated",
|
|
"direction": "out",
|
|
"is_active": 1
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate02",
|
|
"name": "Gate 02 Updated",
|
|
"direction": "out",
|
|
"is_active": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Operator, Admin
|
|
|
|
---
|
|
|
|
#### Delete Gate
|
|
**DELETE** `/retribusi/v1/frontend/gates/{location_code}/{gate_code}`
|
|
|
|
Soft delete gate (set `is_active = 0`).
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"deleted": true
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Admin only
|
|
|
|
---
|
|
|
|
### Tariffs
|
|
|
|
#### Create Tariff
|
|
**POST** `/retribusi/v1/frontend/tariffs`
|
|
|
|
Create new tariff.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"category": "motor",
|
|
"price": 5000
|
|
}
|
|
```
|
|
|
|
**Response (201):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"category": "motor",
|
|
"price": 5000
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Operator, Admin
|
|
|
|
---
|
|
|
|
#### Update Tariff
|
|
**PUT** `/retribusi/v1/frontend/tariffs/{location_code}/{gate_code}/{category}`
|
|
|
|
Update tariff price (location_code, gate_code, category tidak bisa diubah).
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"price": 6000
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"category": "motor",
|
|
"price": 6000
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Operator, Admin
|
|
|
|
---
|
|
|
|
#### Delete Tariff
|
|
**DELETE** `/retribusi/v1/frontend/tariffs/{location_code}/{gate_code}/{category}`
|
|
|
|
Hard delete tariff (permanent delete).
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"deleted": true
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Admin only
|
|
|
|
---
|
|
|
|
### Streams
|
|
|
|
#### List Streams
|
|
**GET** `/retribusi/v1/frontend/streams`
|
|
|
|
Get list of streams (alias untuk gates).
|
|
|
|
**Query Parameters:**
|
|
- `page` (optional, default: 1)
|
|
- `limit` (optional, default: 20, max: 100)
|
|
- `location_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"name": "Gate 01",
|
|
"direction": "in",
|
|
"is_active": 1
|
|
}
|
|
],
|
|
"meta": {
|
|
"page": 1,
|
|
"limit": 20,
|
|
"total": 5,
|
|
"pages": 1
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
## Retribusi - Summary
|
|
|
|
Semua endpoint di bawah ini memerlukan **JWT Authentication**.
|
|
|
|
### Daily Summary
|
|
|
|
#### Trigger Daily Aggregation
|
|
**POST** `/retribusi/v1/admin/summary/daily`
|
|
|
|
Trigger manual aggregation untuk daily summary.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"date": "2025-12-16"
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"rows_processed": 150,
|
|
"date": "2025-12-16"
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Admin only
|
|
|
|
---
|
|
|
|
#### Get Daily Summary
|
|
**GET** `/retribusi/v1/summary/daily`
|
|
|
|
Get daily summary data.
|
|
|
|
**Query Parameters:**
|
|
- `date` (required, format: YYYY-MM-DD)
|
|
- `location_code` (optional, filter)
|
|
- `gate_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"summary_date": "2025-12-16",
|
|
"location_code": "kerkof_01",
|
|
"gate_code": "gate01",
|
|
"category": "motor",
|
|
"total_count": 100,
|
|
"total_amount": 500000
|
|
}
|
|
],
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
### Hourly Summary
|
|
|
|
#### Get Hourly Summary
|
|
**GET** `/retribusi/v1/summary/hourly`
|
|
|
|
Get hourly summary data untuk chart (24 jam).
|
|
|
|
**Query Parameters:**
|
|
- `date` (required, format: YYYY-MM-DD)
|
|
- `location_code` (optional, filter)
|
|
- `gate_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"labels": ["00", "01", "02", ..., "23"],
|
|
"series": {
|
|
"total_count": [10, 15, 20, ..., 5],
|
|
"total_amount": [50000, 75000, 100000, ..., 25000]
|
|
}
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
## Retribusi - Dashboard
|
|
|
|
Semua endpoint di bawah ini memerlukan **JWT Authentication**.
|
|
|
|
### Daily Chart
|
|
**GET** `/retribusi/v1/dashboard/daily`
|
|
|
|
Get daily chart data (line chart).
|
|
|
|
**Query Parameters:**
|
|
- `start_date` (required, format: YYYY-MM-DD)
|
|
- `end_date` (required, format: YYYY-MM-DD)
|
|
- `location_code` (optional, filter)
|
|
- `gate_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"labels": ["2025-12-01", "2025-12-02", "2025-12-03"],
|
|
"series": {
|
|
"total_count": [100, 150, 200],
|
|
"total_amount": [500000, 750000, 1000000]
|
|
}
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
### By Category Chart
|
|
**GET** `/retribusi/v1/dashboard/by-category`
|
|
|
|
Get chart data grouped by category (bar/donut chart).
|
|
|
|
**Query Parameters:**
|
|
- `date` (required, format: YYYY-MM-DD)
|
|
- `location_code` (optional, filter)
|
|
- `gate_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"labels": ["person_walk", "motor", "car"],
|
|
"series": {
|
|
"total_count": [50, 100, 30],
|
|
"total_amount": [100000, 500000, 300000]
|
|
}
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
### Summary Statistics
|
|
**GET** `/retribusi/v1/dashboard/summary`
|
|
|
|
Get summary statistics (stat cards).
|
|
|
|
**Query Parameters:**
|
|
- `date` (required, format: YYYY-MM-DD)
|
|
- `location_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"total_count_today": 180,
|
|
"total_amount_today": 900000,
|
|
"by_gate": [
|
|
{
|
|
"gate_code": "gate01",
|
|
"total_count": 100,
|
|
"total_amount": 500000
|
|
}
|
|
],
|
|
"by_category": [
|
|
{
|
|
"category": "motor",
|
|
"total_count": 100,
|
|
"total_amount": 500000
|
|
}
|
|
]
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
## Retribusi - Realtime
|
|
|
|
Semua endpoint di bawah ini memerlukan **JWT Authentication**.
|
|
|
|
### SSE Stream
|
|
**GET** `/retribusi/v1/realtime/stream`
|
|
|
|
Server-Sent Events (SSE) stream untuk real-time updates.
|
|
|
|
**Headers:**
|
|
```
|
|
Authorization: Bearer <jwt-token>
|
|
Accept: text/event-stream
|
|
```
|
|
|
|
**Query Parameters:**
|
|
- `last_id` (optional, untuk resume dari event tertentu)
|
|
- `location_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```
|
|
Content-Type: text/event-stream
|
|
Cache-Control: no-cache
|
|
Connection: keep-alive
|
|
|
|
id: 12345
|
|
event: ingest
|
|
data: {"location_code":"kerkof_01","gate_code":"gate01","category":"motor","event_time":1703123456}
|
|
|
|
id: 12346
|
|
event: ingest
|
|
data: {"location_code":"kerkof_01","gate_code":"gate01","category":"car","event_time":1703123457}
|
|
|
|
...
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
**Note:** Connection akan tetap terbuka dan mengirim event setiap ada ingest baru. Ping dikirim setiap 10 detik jika tidak ada data.
|
|
|
|
---
|
|
|
|
### Snapshot
|
|
**GET** `/retribusi/v1/realtime/snapshot`
|
|
|
|
Get snapshot data untuk real-time dashboard cards.
|
|
|
|
**Query Parameters:**
|
|
- `date` (optional, default: today, format: YYYY-MM-DD)
|
|
- `location_code` (optional, filter)
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"total_count_today": 180,
|
|
"total_amount_today": 900000,
|
|
"by_gate": [
|
|
{
|
|
"gate_code": "gate01",
|
|
"total_count": 100,
|
|
"total_amount": 500000
|
|
}
|
|
],
|
|
"by_category": [
|
|
{
|
|
"category": "motor",
|
|
"total_count": 100,
|
|
"total_amount": 500000
|
|
}
|
|
]
|
|
},
|
|
"timestamp": 1703123456
|
|
}
|
|
```
|
|
|
|
**Access:** Viewer, Operator, Admin
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
Semua endpoint mengembalikan error dalam format konsisten:
|
|
|
|
### 401 Unauthorized
|
|
```json
|
|
{
|
|
"error": "unauthorized",
|
|
"message": "Invalid or expired token"
|
|
}
|
|
```
|
|
|
|
### 403 Forbidden
|
|
```json
|
|
{
|
|
"error": "forbidden",
|
|
"message": "Insufficient permissions"
|
|
}
|
|
```
|
|
|
|
### 404 Not Found
|
|
```json
|
|
{
|
|
"error": "not_found",
|
|
"message": "Resource not found"
|
|
}
|
|
```
|
|
|
|
### 409 Conflict
|
|
```json
|
|
{
|
|
"error": "conflict",
|
|
"message": "Resource already exists"
|
|
}
|
|
```
|
|
|
|
### 422 Validation Error
|
|
```json
|
|
{
|
|
"error": "validation_error",
|
|
"fields": {
|
|
"location_code": "Field is required",
|
|
"price": "Must be >= 0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 500 Server Error
|
|
```json
|
|
{
|
|
"error": "server_error",
|
|
"message": "Internal server error"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication & Authorization
|
|
|
|
### JWT Token
|
|
- **Algorithm:** HS256
|
|
- **TTL:** Configurable via `JWT_TTL_SECONDS` (default: 3600 seconds)
|
|
- **Header:** `Authorization: Bearer <token>`
|
|
|
|
### Roles
|
|
- **viewer** - Read-only access
|
|
- **operator** - Read + Write (POST, PUT)
|
|
- **admin** - Full access (Read + Write + Delete)
|
|
|
|
### API Key (Ingest)
|
|
- **Header:** `X-API-KEY: <api-key>`
|
|
- **Config:** `RETRIBUSI_API_KEY` in `.env`
|
|
|
|
---
|
|
|
|
## Rate Limiting
|
|
|
|
Saat ini tidak ada rate limiting. Untuk production, pertimbangkan untuk menambahkan rate limiting middleware.
|
|
|
|
---
|
|
|
|
## Pagination
|
|
|
|
Semua list endpoints mendukung pagination:
|
|
|
|
- `page` - Page number (default: 1)
|
|
- `limit` - Items per page (default: 20, max: 100)
|
|
|
|
Response selalu include `meta` object dengan:
|
|
- `page` - Current page
|
|
- `limit` - Items per page
|
|
- `total` - Total items
|
|
- `pages` - Total pages
|
|
|
|
---
|
|
|
|
## Timestamps
|
|
|
|
Semua response include `timestamp` field (Unix timestamp).
|
|
|
|
Untuk date parameters, gunakan format: `YYYY-MM-DD`
|
|
|
|
Untuk datetime, gunakan format: `YYYY-MM-DD HH:MM:SS` atau Unix timestamp (integer).
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
Untuk pertanyaan atau issue, silakan hubungi tim development.
|
|
|
|
**Last Updated:** 2025-12-17
|
|
|