Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide
0.9.0 - Draft for Community Review
Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.9.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.9.0 | ||||
| Computable Name: VNCoreIG | |||||
| Định danh khác: OID:2.25.161089673617632664299011809196868855799 | |||||
VN Core là bộ hướng dẫn triển khai HL7 FHIR R4 quy định các cấu hình và yêu cầu tuân thủ dùng chung cho trao đổi dữ liệu y tế tại Việt Nam. Phiên bản hiện hành là v0.9.0.
Đây là bản trial-use công khai để rà soát kỹ thuật do Omi HealthTech duy trì. Phiên bản này chưa được cơ quan nhà nước hoặc HL7 International phê duyệt thành tiêu chuẩn chính thức. Các tổ chức có thể kiểm thử trong môi trường phù hợp và gửi phản hồi qua [email protected].
VN Core FHIR Implementation Guide (IG) xác định Profiles, Extensions, CodeSystems, ValueSets, NamingSystems, SearchParameters, CapabilityStatements, OperationDefinitions và các quy tắc triển khai theo HL7 FHIR R4 (4.0.1).
Lựa chọn HL7 FHIR R4 có căn cứ chính thức: Khung kiến trúc số Bộ Y tế (QĐ 2146/QĐ-BYT, 15/07/2026) chỉ định đích danh HL7 FHIR R4 và DICOM làm chuẩn liên thông dữ liệu y tế, cùng ICD-10/ICD-11, SNOMED CT, LOINC, RxNorm cho chuẩn hóa dữ liệu, với lộ trình thực hiện đến năm 2030 — xem chi tiết tại Cơ sở pháp lý.
Phiên bản hiện hành được tổ chức theo nguyên tắc:
VN Core Base là lõi FHIR ổn định cho liên thông dùng chungBHYT Submission thành lớp riêng cho liên thông hồ sơ thanh toánMust Support, tìm kiếm, định danh, cơ sở pháp lý, bảo mật và tuân thủ theo vai trò| Artifact | Số lượng | Ghi chú |
|---|---|---|
Profiles |
86 | Bao gồm các profile lâm sàng, hành chính, tài chính, tài liệu và quản trị |
Extensions |
53 cục bộ + 3 chuẩn HL7 | Ưu tiên tái sử dụng extension chuẩn của HL7 cho Patient |
CodeSystems |
165 | Bao gồm các bộ mã nền tảng, BHYT, nghề nghiệp, địa chỉ và hỗ trợ validation |
ValueSets |
168 | Đi cùng các CodeSystem đang dùng trong IG |
NamingSystems |
36 | Bao gồm CCCD, BHYT, BHXH, GKS, GPHN, CCHN, CSKCB, MA_LK, MA_LUOT_KCB |
SearchParameters |
19 | Bao gồm các tham số nghiệp vụ hiện hành; VNeID chỉ còn là artifact lịch sử retired |
CapabilityStatements |
5 | 1 mức cơ sở + 4 theo từng vai trò triển khai |
OperationDefinitions |
4 | $validate-bhyt-claim, $submit-bhyt-claim, $reverse-bhyt-claim, $summary |
Examples |
249 tệp / 227 thực thể | Bao gồm positive và negative fixtures cho lớp BHYT Submission |
| Gói | Vai trò | Dùng khi nào |
|---|---|---|
hl7.fhir.vn.core |
Gói tổng hợp | Kiểm tra cục bộ, đào tạo, thử nghiệm nhanh và cài đặt trọn bộ |
hl7.fhir.vn.core.base |
Gói lõi ổn định | EMR, HIE, hồ sơ công dân, dữ liệu dùng chung và liên thông FHIR-native |
hl7.fhir.vn.pharmacy |
Gói chuyên đề dược | Đơn thuốc điện tử ngoại trú và y học cổ truyền, cấp phát và bán thuốc theo đơn, liên thông Cơ sở dữ liệu về dược; phụ thuộc hl7.fhir.vn.core.base |
hl7.fhir.vn.bhyt.submission |
Gói liên thông hồ sơ thanh toán BHYT | Gateway, adapter, kiểm tra và ánh xạ hồ sơ thanh toán; phụ thuộc hl7.fhir.vn.core.base |
hl7.fhir.vn.patient-access |
Gói truy cập của người dân | Sổ sức khỏe điện tử trên VNeID, khám sức khỏe định kỳ và chứng nhận sức khỏe; phụ thuộc hl7.fhir.vn.core.base và hl7.fhir.vn.pharmacy |
hl7.fhir.vn.terminology.clinical |
Gói thuật ngữ lâm sàng | ICD-10 VN, ICD-9-CM, SNOMED CT VN subset, CLS, LOINC, ConceptMap lâm sàng |
hl7.fhir.vn.terminology.traditional-medicine |
Gói thuật ngữ Y học cổ truyền | Toàn bộ bộ mã Y học cổ truyền hiện hành |
hl7.fhir.vn.device |
Gói thiết bị y tế | Danh pháp thiết bị, DeviceDefinition, regulatory workflow, UDI guidance, kiểm định, asset và procurement khi có use case |
Chi tiết xem tại Kiến trúc gói phát hành.
CCCD là định danh công dân chính; VNeID chỉ được giữ ở lớp ứng dụng người dân hoặc lớp tích hợp/xác thực.VN Core Base và BHYT Submission phải được tách ranh giới để ngữ nghĩa cốt lõi không bị chi phối bởi logic gửi nhận hồ sơ thanh toán.NamingSystems, CodeSystems và ValueSets được coi là hạ tầng của liên thông, không phải phần phụ lục.| Nếu cần | Nên bắt đầu từ |
|---|---|
| Cài thử, build cục bộ và tạo tài nguyên đầu tiên | Bắt đầu nhanh |
| Xác định gói, vai trò triển khai và mức yêu cầu tối thiểu | Tuân thủ theo vai trò triển khai |
Chốt định danh, system URI, trạng thái hiện hành/lịch sử/ngừng dùng |
Danh mục định danh |
| Chốt quy tắc triển khai chung cho tên, địa chỉ, định danh, Organization/Location | Hướng dẫn chung |
| Chốt hành vi tìm kiếm và kiểm tra hợp lệ | Hành vi tìm kiếm, Hướng dẫn kiểm tra hợp lệ |
| Tra cứu căn cứ pháp lý và nền tảng bảo mật | Cơ sở pháp lý, Bảo mật và quyền riêng tư |
| Mục | Nội dung |
|---|---|
| Bắt đầu nhanh | Quy trình cài thử, build và kiểm tra hợp lệ đầu tiên |
| Kiến trúc gói phát hành | Ranh giới của 5 gói chuyên biệt, 1 gói tổng hợp và cách sử dụng |
| Tuân thủ theo vai trò triển khai | Ma trận vai trò, gói và CapabilityStatements |
| Hướng dẫn chung | Quy tắc chung cho tên, địa chỉ, định danh, Organization/Location |
| Danh mục định danh | Danh mục thực dụng của các NamingSystems |
| Hướng dẫn thuật ngữ | Cách dùng CodeSystems, ValueSets và gói thuật ngữ |
| Bảo mật và quyền riêng tư | Nền tảng pháp lý và kỹ thuật cho dữ liệu nhạy cảm |
| Ổn định và tuân thủ | Mô hình trưởng thành, mô hình tuân thủ và độ ổn định gói |
| Phát hành và quản trị | Ngưỡng phát hành và chính sách hiện hành / lịch sử / ngừng dùng |
| Tải xuống | Gói phát hành và các bộ định nghĩa |
| Lịch sử thay đổi | Delta theo từng phiên bản |
Ưu tiên trước thí điểm: Trước khi mở rộng triển khai, VN Core ưu tiên kiểm thử quản trị dữ liệu, định danh theo CCCD, EMR/HSSK, đồng bộ BHYT, lớp ứng dụng người dân và tích hợp, LGSP/API facade và nền tảng an toàn.
| Mốc | Trạng thái | Ghi chú |
|—|—|—|
| v0.3.0 | Lịch sử | Công bố công khai đầu tiên: nhân khẩu học, gói gửi BHYT, thuật ngữ nền tảng và các kịch bản ngoại trú |
| v0.4.0 | Lịch sử | Bổ sung 6 profiles mới và cập nhật căn cứ pháp lý 2025-2026 |
| v0.5.3 | Lịch sử | Dòng 0.5 ổn định QĐ 697/QĐ-BYT, danh mục pháp lý và đóng góp thuộc phạm vi lõi cho CHC/TYT xã. Phạm vi chính: bảng kê chi phí 12 nhóm, dịch vụ y tế cơ bản TYT xã, vòng đời mã cơ sở, thiết bị và dấu hiệu hiệu lực trong tương lai; danh mục pháp lý công khai hiện hành là 134 nguồn |
| v0.6.1 | Lịch sử | Bản phát hành phụ dạng bổ sung, giữ nguyên canonical URL/package id. Trọng tâm: quản lý chăm sóc, KSK cấu trúc theo HL7 SDC, IPS/$summary để trao đổi quốc tế và QĐ 2919/QĐ-BYT; chi tiết kỹ thuật nằm ở changelog/IG |
| v0.7.0 | Lịch sử | Bản gia cố sau kiểm toán hậu phát hành v0.6.1 (v0.6.1 rút lại): sửa nhóm lỗi tài chính BHYT và người ký giấy chuyển tuyến, operations đúng scope, gói bhyt.submission nhận đủ delta XML13–15, rollover trạng thái pháp lý chạm mốc 01/07/2026 và corpus 145 văn bản (rà soát bổ sung 8 văn bản đợt hiệu lực 01/07/2026); công bố đúng SemVer 3 breaking change tồn đọng kèm hướng dẫn migration. Phần chiều sâu liên thông/khám từ xa của kế hoạch 0.7.0 cũ chuyển sang chu kỳ v0.8.0 |
| v0.8.0 | Lịch sử | Bản minor có thay đổi phá vỡ tương thích: tái cấu trúc dữ liệu khám sức khỏe định kỳ theo QĐ 2062/QĐ-BYT (mẫu phiếu theo nhóm tuổi, danh mục đối tượng mở rộng, kênh liên thông mới) và đợt gia cố chất lượng sau hai vòng kiểm toán độc lập — chuẩn hóa viện dẫn pháp lý theo văn bản ban hành, tách giai đoạn hiệu lực terminology kèm bản đồ chuyển đổi, chính sách đặt tên bền vững (ADR-0017). v0.7.0 đóng băng nguyên trạng; kho pháp lý 172 văn bản. Chi tiết: Lịch sử thay đổi |
| v0.9.0 | Hiện hành | Bản minor có thay đổi phá vỡ tương thích, tập trung vào trục thanh toán BHYT và độ chính xác của chính bộ artifact. Bảng kê chi phí chi tiết nhiều giai đoạn theo QĐ 697/QĐ-BYT; biên bản quyết toán quý Mẫu số 06/BH theo TT 12/2026/TT-BTC kèm bộ mã 55 chỉ tiêu và validator 23 công thức; nhật ký truy cập khẩn cấp theo mô hình BALP; tách giai đoạn hiệu lực danh mục quận/huyện. Khám sức khỏe định kỳ và khám sàng lọc vào phạm vi hưởng BHYT theo Luật 114/2025/QH15 Điều 44. Kho pháp lý bổ sung ba văn bản hợp nhất luật nền (BHYT, KCB, Dược). Gỡ hẳn extension vn-ext-encounter-code (retired từ v0.7.0). Ba cổng kiểm ngữ nghĩa mới: đích ánh xạ của logical model, mốc thời gian ví dụ và số học tài chính. Bản này đồng thời hoàn thiện trọn phần chiều sâu liên thông và nền tảng vốn dự kiến ở chu kỳ sau: primitive điều phối VNCoreTask, đặt lịch khám từ xa (Appointment/Schedule/Slot), ConceptMap y học cổ truyền sang ICD-10 (228 mã bệnh danh và thể lâm sàng), ValueSet mã dị ứng SNOMED CT Đợt 3 đã có bản dịch chính thức (1.327 mã), đơn thuốc điện tử hoàn chỉnh gồm đơn ngoại trú và đơn y học cổ truyền, hướng dẫn khử định danh và AI-ready theo Luật 91/2025/QH15 Điều 14 cùng Luật 134/2025/QH15, hướng dẫn SMART on FHIR và Bulk Data ở mức nghĩa vụ actor, cùng Group/Measure/MeasureReport cho báo cáo chất lượng theo TT 35/2024/TT-BYT. Kế hoạch thi công chi tiết: analysis/68. Bản này đồng thời hoàn tất phủ căn cứ pháp lý máy-đọc-được cho 100% artifact (618/618, 15 loại — extension vn-ext-legal-basis + bộ mã ngoại lệ vn-legal-basis-exception-cs, cổng ratchet chống tái diễn), khép trọn 15/15 StructureMap ánh xạ bảng XML BHYT (thêm XML13-XML15: chuyển tuyến, hẹn khám lại, quản lý lao), và nâng kho pháp lý lên 209 văn bản (thêm Luật Hộ tịch 60/2014/QH13, Luật Xuất nhập cảnh 49/2019/QH14, TT 30/2025/TT-BYT; pin toàn văn TT 09/2026/TT-BTC) |
| v1.0.0 | Mục tiêu (Q3/2027) | Mục tiêu ổn định sau khi báo cáo triển khai được công bố hoặc đủ điều kiện rà soát, kiểm thử tuân thủ theo phạm vi thống nhất và ConceptMap ưu tiên XML đầu ra KCB ↔ FHIR được kiểm tra hợp lệ theo phạm vi. Hồ sơ Affiliate chỉ chuẩn bị khi quản trị đủ điều kiện. Bản này cũng là nơi mở bốn hạng mục phụ thuộc bằng chứng bên ngoài, mỗi hạng mục có điều kiện kích hoạt rõ: Subscription (khi có ≥1 cơ sở KCB hoặc bên chi trả nêu yêu cầu sự kiện cụ thể), bộ mã thuốc VNMedicationCodeVS và mô hình định danh thuốc đầy đủ (khi sandbox Cơ sở dữ liệu Dược cấp quyền truy cập danh mục drug_id), đặc tả trao đổi hồ sơ bệnh án điện tử với EMR HUB (khi Trung tâm Thông tin Y tế Quốc gia công bố API chính thức), và Bulk Data ở mức triển khai có kiểm thử (khi có máy chủ pilot). Xem analysis/68 §3.2 |
Chi tiết lịch sử thay đổi xem tại Lịch sử thay đổi và Phát hành và quản trị.
VN Core được xây dựng và duy trì bởi Omi HealthTech. Nội dung được công bố dưới giấy phép CC-BY-4.0. Trang giới thiệu dự án, khung pháp lý và tài liệu kiến thức: hl7.org.vn.
Phiên bản 0.8.0 là bản hiện hành và có thay đổi phá vỡ tương thích so với 0.7.0. Thay đổi chính gồm tái cấu trúc dữ liệu khám sức khỏe theo QĐ 2062/QĐ-BYT, sửa mô hình Consent theo cấu trúc R4, chuẩn hóa slicing định danh Patient, giới hạn namespace BHYT về hai định dạng được công bố và tách các giai đoạn hiệu lực thuật ngữ. Bản 0.7.0 được giữ nguyên như một bản lịch sử đã bị thay thế. Xem chi tiết và hướng dẫn chuyển đổi tại Lịch sử thay đổi và Phát hành và quản trị.
| Kênh | Mục đích |
|---|---|
| [email protected] | Góp ý nội dung, phản biện pháp lý, đề xuất phạm vi |
| Kênh đóng góp kỹ thuật | Gửi đề xuất qua email; mọi thay đổi kỹ thuật cần truy vết, rà soát và căn cứ rõ trước khi merge |
Rà soát từ bệnh viện, nhà cung cấp HIS/EMR/LIS, chuyên gia y tế, người rà soát pháp lý và nhóm QA là đầu vào chính cho các vòng chỉnh sửa tiếp theo.
| Nếu cần | Nên đọc tiếp |
|---|---|
| Bắt đầu cài đặt và chạy thử tài nguyên đầu tiên | Bắt đầu nhanh |
| Hiểu kiến trúc 5 gói chuyên biệt và 1 gói tổng hợp | Kiến trúc gói phát hành |
| Xác định vai trò triển khai và CapabilityStatement | Tuân thủ theo vai trò |
| Tra cứu hồ sơ, phần mở rộng, thuật ngữ và định danh | Hồ sơ, Phần mở rộng, Thuật ngữ, Định danh |
| Tra cứu căn cứ pháp lý và nền tảng bảo mật | Cơ sở pháp lý, Bảo mật và quyền riêng tư |
VN Core 0.8.0 is a public trial-use draft with breaking changes. It restructures health-check data under Decision 2062/QĐ-BYT, aligns Consent with the FHIR R4 provision hierarchy, corrects Patient.identifier slicing, restricts the BHYT namespace to two published formats, and separates terminology eras. Omi HealthTech maintains the guide under CC-BY-4.0; it is not an officially approved national or HL7 International standard.