{
  "openapi": "3.0.3",
  "info": {
    "title": "HTG.iBHYT Simulator API",
    "version": "2.7.0-national-facilities",
    "description": "API giả lập nghiệp vụ BHYT phục vụ phát triển HTG.iHIS. Không phải API chính thức của BHXH Việt Nam."
  },
  "servers": [{ "url": "/", "description": "Máy chủ hiện tại" }],
  "tags": [
    { "name": "System", "description": "Thông tin và tình trạng dịch vụ" },
    { "name": "Eligibility", "description": "Tra cứu thẻ và quyền lợi giả lập" },
    { "name": "Claims", "description": "Kiểm tra, gửi và nhận kết quả hồ sơ" },
    { "name": "Simulator", "description": "Dữ liệu hỗ trợ kiểm thử" }
  ],
  "paths": {
    "/health": { "get": { "tags": ["System"], "summary": "Kiểm tra tình trạng dịch vụ", "responses": { "200": { "description": "Healthy" } } } },
    "/api/v1/metadata": { "get": { "tags": ["System"], "summary": "Thông tin Simulator", "responses": { "200": { "description": "Thông tin hệ thống" } } } },
    "/api/v1/simulator/cards": { "get": { "tags": ["Simulator"], "summary": "Danh sách thẻ kiểm thử", "responses": { "200": { "description": "Danh sách thẻ" } } } },
    "/api/v1/simulator/cards/search": { "get": { "tags": ["Simulator"], "summary": "Tìm kiếm và phân trang 200 thẻ tổng hợp", "parameters": [{"name":"q","in":"query","schema":{"type":"string"}},{"name":"scenario","in":"query","schema":{"type":"string","enum":["VALID","VALID_100","EXPIRED","NOT_YET_VALID","OTHER_FACILITY","FIVE_YEAR_CONTINUOUS"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100}}], "responses": { "200": { "description": "Trang kết quả thẻ giả lập" } } } },
    "/api/v1/eligibility/check": {
      "post": {
        "tags": ["Eligibility"], "summary": "Tra cứu giá trị sử dụng và quyền lợi thẻ",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityRequest" }, "example": { "requestId": "IHIS-20260817-00001", "facilityCode": "79001", "insuranceNumber": "GD4790000000001", "identityNumber": "079085000001", "patientName": "Nguyễn Minh Quân", "visitTime": "2026-08-17T09:15:00+07:00" } } } },
        "responses": { "200": { "description": "Kết quả tra cứu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EligibilityResponse" } } } } }
      }
    },
    "/api/v1/claims/validate": {
      "post": {
        "tags": ["Claims"], "summary": "Kiểm tra hồ sơ trước khi gửi",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } } },
        "responses": { "200": { "description": "Kết quả kiểm tra" } }
      }
    },
    "/api/v1/claims": {
      "get": { "tags": ["Claims"], "summary": "Danh sách hồ sơ", "responses": { "200": { "description": "Danh sách hồ sơ" } } },
      "post": {
        "tags": ["Claims"], "summary": "Gửi hồ sơ và chạy giám định tự động",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } } },
        "responses": { "201": { "description": "Đã tiếp nhận" }, "400": { "description": "Hồ sơ không hợp lệ" } }
      }
    },
    "/api/v1/claims/{claimId}": {
      "get": { "tags": ["Claims"], "summary": "Chi tiết hồ sơ", "parameters": [{ "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Chi tiết hồ sơ" }, "404": { "description": "Không tìm thấy" } } }
    },
    "/api/v1/claims/{claimId}/assessment": {
      "get": { "tags": ["Claims"], "summary": "Kết quả giám định", "parameters": [{ "name": "claimId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Kết quả giám định" }, "404": { "description": "Không tìm thấy" } } }
    }
  },
  "components": {
    "schemas": {
      "EligibilityRequest": { "type": "object", "required": ["requestId", "facilityCode", "insuranceNumber", "visitTime"], "properties": { "requestId": { "type": "string" }, "facilityCode": { "type": "string" }, "insuranceNumber": { "type": "string" }, "identityNumber": { "type": "string" }, "patientName": { "type": "string" }, "visitTime": { "type": "string", "format": "date-time" } } },
      "EligibilityResponse": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "type": "string", "enum": ["VALID", "EXPIRED", "NOT_YET_VALID", "NOT_FOUND"] }, "insuranceNumber": { "type": "string" }, "baseBenefitRate": { "type": "number" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ApiMessage" } } } },
      "ApiMessage": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string", "nullable": true } } },
      "ClaimItem": { "type": "object", "required": ["itemId", "group", "code", "name", "quantity", "unitPrice", "benefitRate", "performedAt"], "properties": { "itemId": { "type": "string" }, "group": { "type": "string", "enum": ["EXAM", "MEDICINE", "SERVICE", "SUPPLY", "BED", "BLOOD"] }, "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" }, "benefitRate": { "type": "number" }, "performedAt": { "type": "string", "format": "date-time" } } },
      "ClaimRequest": { "type": "object", "required": ["facilityCode", "medicalRecordId", "insuranceNumber", "patientName", "checkInTime", "checkOutTime", "treatmentType", "primaryDiagnosisCode", "items"], "properties": { "facilityCode": { "type": "string" }, "medicalRecordId": { "type": "string" }, "insuranceNumber": { "type": "string" }, "patientName": { "type": "string" }, "checkInTime": { "type": "string", "format": "date-time" }, "checkOutTime": { "type": "string", "format": "date-time" }, "treatmentType": { "type": "string", "enum": ["OUTPATIENT", "INPATIENT"] }, "primaryDiagnosisCode": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimItem" } } } }
    }
  }
}