Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.3.0 - STU1 Draft
Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.3.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| URL chính thức: http://fhir.hl7.org.vn/core/ImplementationGuide/hl7.fhir.vn.core | Phiên bản: 0.3.0 | ||||
| Computable Name: VNCoreIG | |||||
Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam — Phiên bản 0.3.0
Lưu ý: Đây là bản dự thảo do cộng đồng xây dựng. Bộ Hướng dẫn này chưa được cơ quan nhà nước phê duyệt hoặc ban hành chính thức. Nội dung mang tính tham khảo kỹ thuật.
VN Core FHIR Implementation Guide (IG) xác định bộ hồ sơ, phần mở rộng, bộ thuật ngữ và hệ thống định danh cốt lõi cho việc trao đổi dữ liệu y tế tại Việt Nam theo tiêu chuẩn HL7 FHIR R4 (4.0.1).
| Nhóm người đọc | Họ đang cần gì | Nên bắt đầu từ | Đọc tiếp |
|---|---|---|---|
| Kiến trúc sư giải pháp, CTO, Product Owner | Hiểu VN Core bao phủ gì, giới hạn ở đâu, nên dùng gói nào | Tuân thủ theo vai trò triển khai | Kiến trúc gói phát hành, Ổn định và tuân thủ, Cơ sở pháp lý |
| Nhóm HIS/EMR/HIE triển khai FHIR | Biết phải ánh xạ resource, identifier, search và validation như thế nào | Tuân thủ theo vai trò triển khai | Hướng dẫn chung, Hướng dẫn Must Support, Hướng dẫn kiểm tra hợp lệ |
| Nhóm gateway hoặc thanh toán BHYT | Biết ranh giới giữa lõi FHIR và lớp liên thông hồ sơ BHYT, cùng operation phải hỗ trợ | Tuân thủ theo vai trò triển khai | Liên thông hồ sơ BHYT, Danh mục định danh, Hướng dẫn kiểm tra hợp lệ |
| Nhóm quản trị định danh, dữ liệu chủ và thuật ngữ | Chốt URI, NamingSystem, CodeSystem, ValueSet và cách bắc cầu dữ liệu cũ | Tuân thủ theo vai trò triển khai | Danh mục định danh, Ánh xạ URI/OID, Hướng dẫn thuật ngữ |
| Nhóm pháp chế, an toàn thông tin, quản trị dữ liệu | Đối chiếu quyết định kỹ thuật với khung pháp lý và yêu cầu bảo mật | Cơ sở pháp lý | Ma trận pháp lý theo hồ sơ, Bảo mật và quyền riêng tư |
| Nhóm đánh giá tuân thủ, QA, reviewer cộng đồng | Biết tiêu chí đạt chất lượng phát hành, maturity và mẫu báo cáo triển khai | Tuân thủ theo vai trò triển khai | Ổn định và tuân thủ, Phát hành và quản trị, Báo cáo triển khai |
Bắt đầu nhanh -> Hướng dẫn chung -> Must Support -> Kiểm tra hợp lệ -> Hồ sơ/Phần mở rộng/Thuật ngữ.Cơ sở pháp lý -> Ma trận pháp lý -> Bảo mật -> Ổn định và tuân thủ.VN Core Base.IPS, rồi mới Việt hóa;NamingSystem, CodeSystem, ValueSet là hạ tầng của liên thông chứ không phải phụ lục;Identifier, Address, Coding, CodeableConcept, Dosage và phân lớp Observation.Những gì không được chấp nhận trong hướng hiện tại là canonical thiếu kỷ luật, legal framing lẫn lộn, chính sách định danh không tách current/legacy rõ, và cách gom profile mà thiếu hướng dẫn theo vai trò triển khai, yêu cầu tuân thủ, ví dụ và bộ kiểm thử.
data-first: dữ liệu dùng chung, tái sử dụng dữ liệu, LGSP và khai thác dữ liệu phục vụ điều hành.VN Core Base, lớp liên thông hồ sơ BHYT (BHYT Submission), thuật ngữ lâm sàng và thuật ngữ Y học cổ truyền để phục vụ cả liên thông FHIR-native lẫn quản trị theo chuyên đề.4 gói mô-đun và 1 gói tổng hợp từ cùng một kho mã nguồn biên soạn.Phiên bản này bao gồm tất cả tài nguyên P0 (v0.1.0) cộng thêm lớp liên thông hồ sơ BHYT (BHYT Submission), các tài nguyên quản trị dữ liệu và bảo mật, cùng phần mở rộng định danh số từ vòng rà soát lâm sàng:
| Loại tài nguyên | Số lượng | Mô tả |
|---|---|---|
| Hồ sơ | 32 | Bao gồm lớp liên thông hồ sơ BHYT (BHYT Submission), VNCoreAuditEvent, VNCoreProvenance, VNCoreRelatedPerson, VNCoreLocation và VNCoreSpecimen bên cạnh các profile lâm sàng, tài chính, tài liệu và thiết bị |
| Phần mở rộng | 27 cục bộ + 3 chuẩn HL7 | Ưu tiên các extension chuẩn của HL7 cho religion/citizenship/birthPlace; extension cục bộ chỉ dùng cho dữ liệu thật sự đặc thù Việt Nam |
| Bộ mã | 52 | Bổ sung thuật ngữ hỗ trợ kiểm tra tiền tố CCCD, phân loại tổ chức/y tế và lớp định danh hành nghề hiện hành - lịch sử cho người hành nghề |
| Tập giá trị | 54 | Tương ứng cho các CodeSystem đang dùng trong IG |
| Tham số tìm kiếm | 14 | Thêm tìm kiếm vn-ma-lk, vn-vneid, vn-ma-luot-kcb, vn-ma-dkbd, vn-bhxh, vn-gks, vn-gphn, cùng lớp định danh người hành nghề theo GPHN hiện hành / CCHN lịch sử |
| Ánh xạ khái niệm | 2 | CLS VN → LOINC (2.964 chỉ số, bao phủ 100%) + Tôn giáo Việt Nam → v3-ReligiousAffiliation (ánh xạ một phần) |
| Hệ thống định danh | 18 | CCCD, CMND, BHYT, BHXH, GKS, GPHN, CCHN, CSKCB, MRN, VNeID, hộ chiếu, MA_LK, MA_LUOT_KCB, số tài liệu, mã địa điểm nội bộ, mã tổ chức nội bộ, mã vật tư, mã mẫu bệnh phẩm nội bộ |
| CapabilityStatement | 5 | 1 CapabilityStatement mức cơ sở + 4 CapabilityStatement theo từng vai trò triển khai cho EMR, cổng BHYT và ứng dụng người dân |
| Mô hình logic | 13 | Check-in + các bảng BHYT 1-12 |
| OperationDefinition | 3 | $validate-bhyt-claim, $submit-bhyt-claim, $reverse-bhyt-claim |
| Tệp ví dụ / thực thể ví dụ | 122 tệp / 123 thực thể | Bao gồm bộ ví dụ dương tính/âm tính cho lớp liên thông hồ sơ BHYT (BHYT Submission), ví dụ quản trị/kiểm toán, mô hình hóa trẻ em-người giám hộ, Location và chuỗi xét nghiệm với Specimen |
Đây là bản STU1 Draft (Standard for Trial Use). Cộng đồng y tế số Việt Nam được khuyến khích sử dụng thử nghiệm, phản hồi và đóng góp qua email [email protected].
Từ
26/03/2026, lộ trình công bố của VN Core được điều chỉnh thêm theo QĐ 3516/QĐ-BYT để ưu tiênVNeID,EMR/HSSK,LGSP, tái sử dụng dữ liệu và mức bảo mật cơ sở trước khi mở rộng mạnh thêm phạm vi.
| Phiên bản | Thời gian | Trạng thái | Nội dung chính |
|---|---|---|---|
| v0.1.0 | 03/2026 | ✅ Đã phát hành | STU1 Draft — 23 hồ sơ, 42 CodeSystems, 20 phần mở rộng, 33 ví dụ |
| v0.2.0 | 03/2026 | ✅ Đã phát hành | Clinical + lớp liên thông hồ sơ BHYT (BHYT Submission) + rà soát quản trị — chốt ranh giới gateway layer, các tài nguyên quản trị và các bundle/operation đầu tiên |
| v0.3.0 | 03/2026 | ✅ Hiện hành | 32 hồ sơ, 30 phần mở rộng (27 cục bộ + 3 chuẩn HL7 cho Patient), 52 CodeSystems, 54 ValueSets, 14 SearchParameters, 13 logical models, 3 operation, 122 tệp ví dụ / 123 thực thể ví dụ, 232 thực thể, 345 tài nguyên JSON xuất ra; thay đổi lớn: bỏ 3 phần mở rộng Patient cục bộ để tái sử dụng extension chuẩn HL7, thêm VNCoreRelatedPerson, VNCoreLocation và VNCoreSpecimen, thuật ngữ hỗ trợ kiểm tra tiền tố CCCD, các lát cắt định danh BHXH/GKS/VNeID/HC, lớp định danh người hành nghề theo GPHN hiện hành / CCHN lịch sử, 5 CapabilityStatement mức yêu cầu, kiểm tra Tier 2, chuyển đổi khứ hồi BHYT phủ đến xml12, tái cấu trúc pháp lý cho Organization/Location để tách hạng, cấp KCB, cấp quản lý hành chính và tuyến kỹ thuật lịch sử, chuẩn hóa MA_LUOT_KCB dưới dạng Identifier có NamingSystem riêng, bổ sung ví dụ bệnh nhân người nước ngoài dùng hộ chiếu, cùng ConceptMap tôn giáo Việt Nam → v3-ReligiousAffiliation và chuẩn hóa Coverage.type theo loại bảo hiểm chuẩn FHIR |
| v0.4.0 | Q3/2026 | 🔜 Tiếp theo | Gia cố theo trục data-first: quy tắc chất lượng, VNeID, liên thông EMR/HSSK, hướng dẫn cho lớp LGSP/API facade, tuân thủ theo từng vai trò và mức bảo mật cơ sở cho giai đoạn thí điểm |
| v0.5.0 | Q1/2027 | 📋 Dự kiến | Mở rộng có kiểm soát: liên thông telehealth, đơn thuốc điện tử, truy cập dữ liệu thứ cấp, provenance sẵn sàng cho AI, Imaging/Dispense |
| v1.0.0 | Q3/2027 | 📋 Dự kiến | Phiên bản chính thức sau quy trình ballot. Yêu cầu tối thiểu 3 báo cáo triển khai và bộ kiểm thử tuân thủ hoàn chỉnh |
Omi HealthTech cam kết duy trì và phát triển VN Core FHIR IG lâu dài, phối hợp cùng các bên liên quan trong hệ sinh thái y tế số Việt Nam.
| Mục | Nội dung |
|---|---|
| Giới thiệu | Về Omi HealthTech, OmiGroup, và tầm nhìn VN Core |
| Bắt đầu nhanh | 4 bước để bắt đầu sử dụng VN Core FHIR IG |
| Cơ sở pháp lý | Bảng tổng hợp 28+ văn bản pháp lý ảnh hưởng đến thiết kế |
| Ma trận pháp lý theo hồ sơ | Diễn giải căn cứ hiện hành, căn cứ lịch sử và quyết định thiết kế theo từng nhóm hồ sơ |
| Kiến trúc gói phát hành | Phạm vi, phụ thuộc và cách dùng 5 gói phát hành |
| Quy ước biên tập và thuật ngữ | Nguồn sự thật cho cách gọi vai trò triển khai, gói, artifact và cấu trúc narrative |
| Hướng dẫn chung | Quy tắc tên tiếng Việt, địa chỉ, định danh, Organization/Location |
| Tìm kiếm chuỗi và Unicode | Quy tắc bảo toàn Unicode, dấu tiếng Việt và mở rộng tìm kiếm |
| Hành vi tìm kiếm | Kỳ vọng tối thiểu theo token, string, date, reference |
| Danh mục định danh | Danh mục triển khai của 18 NamingSystem |
| Ánh xạ URI/OID | Cách bắc cầu định danh và bộ mã lịch sử sang canonical URI |
| Hướng dẫn Must Support | Diễn giải Must Support, xử lý thiếu dữ liệu, cẩm nang HIS -> FHIR |
| Hướng dẫn thuật ngữ | Cách sử dụng CodeSystem/ValueSet, mức độ ràng buộc |
| Tuân thủ theo vai trò triển khai | Ma trận vai trò triển khai, package, CapabilityStatement và tiêu chí sẵn sàng thí điểm |
| Checklist sẵn sàng thí điểm theo vai trò | Checklist ngắn để tự đánh giá mức sẵn sàng thí điểm của từng vai trò triển khai |
| Tình huống lâm sàng | Minh họa luồng dữ liệu thực tế (khám ngoại trú + BHYT) |
| Hồ sơ | Danh sách 32 profile với mô tả chi tiết |
| Phần mở rộng | Danh sách 27 phần mở rộng cục bộ và các extension chuẩn của HL7 dành cho Patient được tái sử dụng |
| Thuật ngữ | Danh sách 52 CodeSystems + 54 ValueSets |
| Quản trị Organization/Location | Cách tách hạng pháp lý, cấp KCB hiện hành, cấp quản lý hành chính và tuyến kỹ thuật lịch sử |
| Bảo mật và quyền riêng tư | Luật 91/2025, NĐ 356/2025, phân loại dữ liệu |
| Kiểm tra hợp lệ | Hướng dẫn kiểm tra hợp lệ 3 tầng |
| Liên thông hồ sơ BHYT | Logical model, MA_LK, operation và nguyên tắc xuất dữ liệu ở gateway layer |
| Ổn định và tuân thủ | Mô hình trưởng thành, chính sách phát hành, CapabilityStatement theo từng vai trò triển khai và các kiểm tra thực thi được |
| Phát hành và quản trị | Khung phát hành công khai, đóng góp và ngưỡng phát hành tối thiểu |
| Báo cáo triển khai | Khung implementation report tối thiểu cho thí điểm và ballot |
| SNOMED CT VN — Đính chính | Đính chính bản dịch SNOMED CT tiếng Việt |
| Tải xuống | Gói phát hành, bộ định nghĩa |
| Lịch sử thay đổi | Ghi chép phiên bản |
Bộ Hướng dẫn Triển khai này là sáng kiến của Omi HealthTech (một công ty thành viên thuộc OmiGroup), được xây dựng với mục đích đóng góp cho cộng đồng y tế số Việt Nam.
The VN Core FHIR Implementation Guide defines the foundational FHIR R4 profiles, extensions, terminology, and naming systems for healthcare data exchange in Vietnam. The current 0.3.0 release provides 32 profiles, 27 local extensions plus 3 standard HL7 patient extensions, 52 CodeSystems, 54 ValueSets, 14 SearchParameters, 13 logical models, 3 OperationDefinitions, 2 ConceptMaps (CLS VN → LOINC with 2,964 codes, plus a partial Vietnam Religion → v3-ReligiousAffiliation mapping), 18 NamingSystems, 122 example files, 123 example instances, 232 total instances, 345 exported JSON artifacts, and 5 CapabilityStatements. In addition to core clinical and administrative profiles, this release includes a dedicated BHYT Submission layer, MA_LK/VNeID/MA_LUOT_KCB/MA_DKBD/BHXH/GKS/GPHN search support, a patient model that minimizes local extensions by reusing the standard HL7 extensions for religion, citizenship, and birth place, dedicated Location and Specimen profiles for service-delivery sites and laboratory workflow, governance artifacts for AuditEvent and Provenance, a five-package publication model (one aggregate package plus four modular packages), actor-based conformance guidance, executable Tier 2 validation checks for high-risk Vietnamese data rules including BCA birthplace-prefix validation for CCCD, explicit appendix-level legal provenance for all 10 traditional medicine CodeSystems, BHYT round-trip fixtures that now cover xml4 to xml12 across inpatient, newborn, HIV/AIDS, death, and supporting-document scenarios, a legal refactor for Organization/Location semantics that separates legal rank, current care level, administrative oversight level, and legacy technical line, a dedicated MA_LUOT_KCB NamingSystem plus Identifier-based encounter modeling, a new foreign-patient passport example, and a Practitioner licensing refactor that makes GPHN the current licensing identifier while retaining CCHN only for historical interoperability. The public roadmap is now also aligned with the Ministry of Health digital transformation strategy (Decision 3516/QD-BYT, dated November 12, 2025), which pushes data governance, VNeID-aligned identity, EMR/HSSK interoperability, LGSP-facing guidance, and security baselines ahead of broader scope expansion. The IG references 28+ Vietnamese legal documents and is designed to align with the 2025-2026 regulatory framework. Implementers remain responsible for ensuring full legal compliance.