# 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*