gravity/บริหารจัดการคิวนวดแผนไทย/docs/04_API_Documentation.md

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):

  {
    "username": "1100000000001",
    "password": "SecurePassword@2026",
    "totp_code": "123456"
  }
  

• Response (200 OK):

  {
    "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):

  {
    "branch_id": 1,
    "patient_id": 1,
    "service_id": 2,
    "priority": "Normal"
  }
  

• Response (200 OK - AI Allocated):

  {
    "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):

  {
    "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):

  {
    "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):

  {
    "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):

  {
    "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