{"openapi":"3.1.0","info":{"title":"HOATIEU3 API","version":"0.1.0","description":"Healthcare navigation API — 3 phút, biết mình nên làm gì."},"servers":[{"url":"https://api.hoatieu3.com"}],"components":{"securitySchemes":{"caseToken":{"type":"http","scheme":"bearer","description":"accessToken nhận khi tạo case"}},"schemas":{"Intake":{"type":"object","properties":{"need":{"type":"string","enum":["checkup","treatment","revisit","surgery","second_opinion","lab_test","imaging","admission","discharge","home_care","find_doctor","find_hospital","emergency"],"example":"checkup"},"patient":{"type":"object","properties":{"age":{"type":"integer","minimum":0,"maximum":120,"example":62},"sex":{"type":"string","enum":["male","female","other"]},"province":{"type":"string","maxLength":80,"example":"Nghệ An"},"isSelf":{"type":"boolean"}}},"symptoms":{"type":"string","maxLength":2000,"example":"Điện tim bất thường, hay hồi hộp"},"diagnosis":{"type":"string","maxLength":500},"durationDays":{"type":"integer","minimum":0,"maximum":36500},"severity":{"type":"string","enum":["mild","moderate","severe"]},"redFlags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"conditionsCount":{"type":"integer","minimum":0,"maximum":50},"hasPriorResults":{"type":"boolean"},"preferredCity":{"type":"string","maxLength":80,"example":"Hà Nội"},"goal":{"type":"string","maxLength":500}},"required":["need","patient"]},"CreateCase":{"type":"object","properties":{"intake":{"$ref":"#/components/schemas/Intake"},"patient":{"$ref":"#/components/schemas/Patient"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"},"maxItems":10}},"required":["intake"]},"Patient":{"type":"object","properties":{"fullName":{"type":"string","maxLength":120},"birthYear":{"type":"integer","minimum":1900,"maximum":2100},"sex":{"type":"string","enum":["male","female","other"]},"province":{"type":"string","maxLength":80},"address":{"type":"string","maxLength":300}}},"Contact":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":120},"relationship":{"type":"string","maxLength":60},"role":{"type":"string","enum":["primary","secondary"]},"phone":{"type":"string","maxLength":30},"zalo":{"type":"string","maxLength":60},"email":{"type":"string","maxLength":200,"format":"email"},"province":{"type":"string","maxLength":80},"decisionAuthority":{"type":"boolean","default":false},"canAccompany":{"type":"boolean","default":false},"canReceiveMedicalInfo":{"type":"boolean","default":false},"isEmergencyContact":{"type":"boolean","default":false}},"required":["fullName","role"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"FollowUp":{"type":"object","properties":{"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"kind":{"type":"string","enum":["revisit","medication","check_in","test","warning_signs"]},"title":{"type":"string","minLength":1,"maxLength":200},"note":{"type":"string","maxLength":1000},"notifyContactId":{"type":"string","maxLength":60}},"required":["dueAt","kind","title"]}},"parameters":{}},"paths":{"/v1/meta":{"get":{"tags":["Meta"],"summary":"Danh mục nhu cầu và dấu hiệu nguy hiểm","responses":{"200":{"description":"Danh mục","content":{"application/json":{"schema":{}}}}}}},"/v1/navigate":{"post":{"tags":["Navigation"],"summary":"Chạy HOATIEU Engine: Safety → Intake → Matching → Next Best Action (không lưu)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Intake"}}}},"responses":{"200":{"description":"Recommendation","content":{"application/json":{"schema":{}}}}}}},"/v1/cases":{"post":{"tags":["Cases"],"summary":"Tạo Navigation Case (kèm Patient Profile + Contact Network). Trả về accessToken — chỉ hiển thị một lần.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCase"}}}},"responses":{"201":{"description":"Case đã tạo","content":{"application/json":{"schema":{}}}}}}},"/v1/cases/{id}":{"get":{"tags":["Cases"],"summary":"Xem Navigation Case đầy đủ","security":[{"caseToken":[]}],"parameters":[{"schema":{"type":"string","pattern":"^HT3-\\d{6,}$","example":"HT3-000123"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Case","content":{"application/json":{"schema":{}}}},"401":{"description":"Thiếu hoặc sai token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Cases"],"summary":"Cập nhật trạng thái hành trình / bệnh viện đã chọn","security":[{"caseToken":[]}],"parameters":[{"schema":{"type":"string","pattern":"^HT3-\\d{6,}$","example":"HT3-000123"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["intake","pre_hospital","in_hospital","post_discharge","follow_up","closed","emergency"]},"chosenHospitalId":{"type":"string","maxLength":60},"assignedNavigator":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"Đã cập nhật","content":{"application/json":{"schema":{}}}},"401":{"description":"Thiếu hoặc sai token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cases/{id}/renavigate":{"post":{"tags":["Cases"],"summary":"Chạy lại engine với dữ liệu mới nhất của Service Graph","security":[{"caseToken":[]}],"parameters":[{"schema":{"type":"string","pattern":"^HT3-\\d{6,}$","example":"HT3-000123"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Recommendation mới","content":{"application/json":{"schema":{}}}},"401":{"description":"Thiếu hoặc sai token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cases/{id}/contacts":{"post":{"tags":["Contacts"],"summary":"Thêm người liên hệ","security":[{"caseToken":[]}],"parameters":[{"schema":{"type":"string","pattern":"^HT3-\\d{6,}$","example":"HT3-000123"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"responses":{"200":{"description":"Đã thêm","content":{"application/json":{"schema":{}}}},"401":{"description":"Thiếu hoặc sai token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Đã có người liên hệ chính"}}}},"/v1/cases/{id}/shares":{"post":{"tags":["Remote review"],"summary":"Tạo link có hạn để một bác sĩ xem hồ sơ, ảnh và ghi ý kiến","security":[{"caseToken":[]}],"parameters":[{"schema":{"type":"string","pattern":"^HT3-\\d{6,}$","example":"HT3-000123"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reviewerName":{"type":"string","minLength":1,"maxLength":120},"reviewerTitle":{"type":"string","maxLength":200},"expiresInHours":{"type":"integer","minimum":1,"maximum":720,"default":72}},"required":["reviewerName"]}}}},"responses":{"201":{"description":"reviewToken — chỉ hiển thị một lần","content":{"application/json":{"schema":{}}}},"401":{"description":"Thiếu hoặc sai token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cases/{id}/followups":{"post":{"tags":["Follow-up"],"summary":"Tạo lịch tái khám / nhắc việc","security":[{"caseToken":[]}],"parameters":[{"schema":{"type":"string","pattern":"^HT3-\\d{6,}$","example":"HT3-000123"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUp"}}}},"responses":{"200":{"description":"Đã tạo","content":{"application/json":{"schema":{}}}},"401":{"description":"Thiếu hoặc sai token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/hospitals":{"get":{"tags":["Service Graph"],"summary":"Tìm bệnh viện theo thành phố / chuyên khoa","parameters":[{"schema":{"type":"string"},"required":false,"name":"city","in":"query"},{"schema":{"type":"string"},"required":false,"name":"specialty","in":"query"},{"schema":{"type":"string"},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Danh sách","content":{"application/json":{"schema":{}}}}}}},"/v1/hospitals/{hid}":{"get":{"tags":["Service Graph"],"summary":"Một nút bệnh viện đầy đủ: khoa, dịch vụ, quy định, nơi ở, ăn uống","parameters":[{"schema":{"type":"string","example":"h-bachmai"},"required":true,"name":"hid","in":"path"}],"responses":{"200":{"description":"Bệnh viện","content":{"application/json":{"schema":{}}}},"404":{"description":"Không có"}}}}},"webhooks":{}}