153 lines
6.4 KiB
Markdown
153 lines
6.4 KiB
Markdown
# 04. Enterprise REST API Documentation & OpenAPI Spec
|
|
**Project:** Thai Traditional Massage Queue Management System (TTMQMS Enterprise)
|
|
**Standard:** OpenAPI Specification 3.0.3 (Swagger)
|
|
**Base URL:** `https://ttmqms.hospital.go.th/api/v1`
|
|
**Authentication:** Bearer JWT (JSON Web Token RFC 7519) + 2FA TOTP
|
|
**Version:** 1.0.0 Production
|
|
|
|
---
|
|
|
|
## 1. Architecture & Security Standards
|
|
REST API ของระบบ TTMQMS ถูกสร้างขึ้นเพื่อให้บริการแก่หน้าจอ PWA, อุปกรณ์ Smart TV, เครื่องนวดมือถือ, ฮาร์ดแวร์ Smart Card Reader / ESC/POS Printer และการเชื่อมต่อกับระบบ HIS ของโรงพยาบาล โดยมีเกณฑ์ความปลอดภัยดังนี้:
|
|
1. **HTTPS / TLS 1.3 Encryption Only:** ไม่อนุญาตให้เชื่อมต่อผ่านพอร์ต HTTP ธรรมดา
|
|
2. **Bearer JWT Access Token:** โทเค็นมีอายุใช้งาน 60 นาที โดยต้องแนบใน Header `Authorization: Bearer <token>`
|
|
3. **mTLS (Mutual TLS):** สำหรับการเชื่อมต่อระหว่างเซิร์ฟเวอร์ HIS HOSxP/JHCIS และ MOPH FHIR Server
|
|
4. **Rate Limiting:** จำกัดคำขอสูงสุด 120 Requests / Minute / IP เพื่อป้องกันการโจมตี DDoS
|
|
|
|
---
|
|
|
|
## 2. Interactive Swagger Spec & OpenAPI Viewer
|
|
ผู้พัฒนาระบบและเจ้าหน้าที่ IT โรงพยาบาลสามารถทดสอบเรียก API สดผ่าน **Swagger UI Console** ที่ติดตั้งมาพร้อมกับระบบที่หน้าเว็บ:
|
|
- **Swagger Console UI:** `https://ttmqms.hospital.go.th/api-docs/index.html`
|
|
- **OpenAPI JSON Spec File:** `/public/api-docs/openapi.json`
|
|
|
|
---
|
|
|
|
## 3. Core Endpoint Specifications
|
|
|
|
### 3.1 Authentication & Security Endpoints
|
|
#### `POST /api/v1/auth/login`
|
|
- **Description:** ตรวจสอบชื่อผู้ใช้งาน (เลขบัตร 13 หลัก) และรหัสผ่านด้วย Argon2id
|
|
- **Request Body (JSON):**
|
|
```json
|
|
{
|
|
"username": "1100000000001",
|
|
"password": "SecurePassword@2026",
|
|
"totp_code": "123456"
|
|
}
|
|
```
|
|
- **Response (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"expires_in": 3600,
|
|
"user": { "id": 1, "name": "คุณสมชาย รักสุขภาพ", "role": "Admin", "branch_id": 1 }
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.2 Queue Management & AI Allocation Endpoints
|
|
#### `POST /api/v1/queues/walkin`
|
|
- **Description:** ออกบัตรคิวสำหรับผู้ป่วย Walk-in พร้อมประมวลผลจัดสรรหมอนวดและห้องพักอัตโนมัติด้วย AI
|
|
- **Headers:** `Authorization: Bearer <JWT_TOKEN>`
|
|
- **Request Body (JSON):**
|
|
```json
|
|
{
|
|
"branch_id": 1,
|
|
"patient_id": 1,
|
|
"service_id": 2,
|
|
"priority": "Normal"
|
|
}
|
|
```
|
|
- **Response (200 OK - AI Allocated):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"queue_id": 15,
|
|
"queue_no": "A003",
|
|
"status": "Assigned",
|
|
"assigned_therapist": { "id": 2, "name": "หมอสมศรี (T-102)" },
|
|
"assigned_room": { "id": 1, "room_no": "R-101", "name": "ห้องนวดไทย VIP 1" },
|
|
"est_wait_time_mins": 0,
|
|
"ai_workload_score": 420.50
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `GET /api/v1/queues?branch_id=1&status=Assigned,In_Progress`
|
|
- **Description:** ดึงรายชื่อคิวเรียลไทม์ สำหรับหน้าจอ Reception Board และ Smart TV Display
|
|
- **Response (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"total": 2,
|
|
"queues": [
|
|
{ "id": 15, "queue_no": "A003", "status": "In_Progress", "room_no": "R-101", "therapist_name": "หมอสมศรี (T-102)" },
|
|
{ "id": 16, "queue_no": "A004", "status": "Waiting", "est_wait": "10 นาที" }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.3 Clinical Assessment & SOAP Note Endpoints
|
|
#### `POST /api/v1/clinical/soap`
|
|
- **Description:** บันทึกเวชระเบียน SOAP Note, VAS Pain Score และลายมือชื่อดิจิทัล พร้อมกระตุ้น Triggers ซิงค์ FHIR
|
|
- **Headers:** `Authorization: Bearer <JWT_TOKEN>`
|
|
- **Request Body (JSON):**
|
|
```json
|
|
{
|
|
"queue_id": 15,
|
|
"patient_id": 1,
|
|
"subjective": "ปวดหลังและต้นคอมา 3 วัน จากการนั่งทำงานหน้าคอมพิวเตอร์",
|
|
"objective_vas_pre": 7,
|
|
"objective_vas_post": 2,
|
|
"objective_rom": { "flexion": 45, "extension": 30 },
|
|
"assessment": "โรคลมปลายปัตฆาตสัญญาณ 4 หลัง",
|
|
"plan_treatment": "นวดแผนไทยราชสำนักเน้นเส้นประธานสิบ และประคบสมุนไพร",
|
|
"signature_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.4 POS Billing & Receipt Endpoints
|
|
#### `POST /api/v1/billing/checkout`
|
|
- **Description:** ชำระค่าบริการ ออกเลขที่ใบเสร็จ และส่งข้อความให้ ESC/POS Printer
|
|
- **Request Body (JSON):**
|
|
```json
|
|
{
|
|
"queue_id": 15,
|
|
"payment_method": "PromptPay",
|
|
"subtotal": 750.00,
|
|
"discount": 50.00,
|
|
"vat": 49.00,
|
|
"grand_total": 749.00
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.5 HIS & FHIR R4 Interoperability Endpoints
|
|
#### `POST /api/v1/his/fhir/bundle`
|
|
- **Description:** ส่งออกข้อมูลการตรวจรักษาในรูปแบบ HL7 FHIR R4 JSON Bundle (Encounter + Observation)
|
|
- **Response (201 Created):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"fhir_id": "Bundle/fhir-20260727-003",
|
|
"his_response_status": 201,
|
|
"message": "Encounter and Observation resources synchronized with HOSxP successfully."
|
|
}
|
|
```
|
|
|
|
---
|
|
*เอกสารฉบับนี้เชื่อมโยงกับ OpenAPI Spec File `/public/api-docs/openapi.json` แบบ 1-to-1*
|