Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.4.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Mở rộng (Extensions)
Phần mở rộng — Extensions
Phiên bản 0.4.0 công bố 29 extension cục bộ và tái sử dụng 3 extension chuẩn HL7 cho Patient. Khi rà soát cách dùng trong resource thật, đọc song song với Hồ sơ và Hướng dẫn thuật ngữ.
Tổng quan
VN Core IG định nghĩa 29 extension cục bộ cho các phần tử dữ liệu đặc thù Việt Nam mà FHIR R4 gốc không có sẵn.
Đối với religion, citizenship, và birthPlace, VNCorePatient dùng thẳng các extension chuẩn của HL7 thay vì tạo extension cục bộ mới.
| Nhóm |
Phần mở rộng |
Số lượng |
| Nhân khẩu học và định danh (Demographics & Identity) |
Dân tộc, Nghề nghiệp, Lý do bất khả kháng thiếu CCCD |
3 |
| Địa chỉ (Address) |
Tỉnh/TP, Xã/Phường |
2 |
| Bảo hiểm y tế (Insurance) |
Loại thẻ BHYT, Nơi ĐKKCB, Loại KCB BHYT |
3 |
| Tổ chức (Organization) |
Hạng KCB, hạng đơn vị y tế không phải KCB, trạng thái xếp hạng, cấp quản lý hành chính, loại hình, cấp năng lực KCB, tuyến kỹ thuật lịch sử, dải điểm chất lượng |
8 |
| Lâm sàng và luồng nghiệp vụ (Clinical & Workflow) |
Kết quả điều trị, Hình thức chuyển tuyến, Mã lượt KCB |
3 |
| Tài chính và thanh toán (Claims) |
Chi phí Claim, Khoa chỉ định, Thời gian thanh toán, Chi phí BHYT, Phương thức thanh toán, Ngày y lệnh |
6 |
| Dược phẩm (Medication) |
Số đăng ký thuốc |
1 |
| Trang thiết bị (Device) |
Phạm vi BH TBYT, Nhóm TBYT BHYT |
2 |
Nhân khẩu học và định danh
| Extension |
Context |
Type |
Binding |
Lý do |
| VNCoreExtEthnicity |
Patient |
CodeableConcept |
VNEthnicityVS (required) |
FHIR base chỉ có US Race/Ethnicity. VN có 54 dân tộc theo 121/TCTK-PPCĐ |
| VNCoreExtOccupation |
Patient |
CodeableConcept |
VNOccupationVS (extensible) |
Patient không có nghề nghiệp. Mã VSCO 2020 (QĐ 34/2020), 1.516 mã, tương thích ISCO-08 |
| VNCoreExtForceMajeureReason |
Patient |
CodeableConcept |
VNForceMajeureReasonVS (required) |
QĐ 3176 yêu cầu SO_CCCD bắt buộc, chỉ trống khi bất khả kháng |
Địa chỉ
| Extension |
Context |
Type |
Binding |
Lý do |
| VNCoreExtProvince |
Address |
Coding |
VNProvinceVS (required) |
Address.state là text tự do. Extension dùng mã coded theo NQ 202/2025 (34 tỉnh/TP) |
| VNCoreExtWard |
Address |
Coding |
VNWardVS (required) |
FHIR base không có ward/commune. Xã là cấp 2 chính thức sau NQ 202/2025 |
Bảo hiểm y tế
| Extension |
Context |
Type |
Binding |
Lý do |
| VNCoreExtBHYTCardType |
Coverage |
Coding |
VNBHYTCardTypeVS (required) |
Loại đối tượng BHYT (DN, TE, HN, CC…) ảnh hưởng mức hưởng |
| VNCoreExtPrimaryCareFacility |
Coverage |
Reference(Organization) |
— |
Thẻ BHYT ghi nơi ĐKKCB ban đầu — ảnh hưởng đúng/trái tuyến |
| VNCoreExtInsuranceVisitType |
Encounter |
Coding |
VNInsuranceVisitTypeVS (required) |
Phân loại KCB ban đầu / chuyển tuyến / cấp cứu — ảnh hưởng thanh toán BHYT |
Tổ chức
| Extension |
Context |
Type |
Binding |
Lý do |
| VNCoreExtOrgRank |
Organization |
CodeableConcept |
VNHospitalRankVS (required) |
Hạng cơ sở KCB theo TT 06/2024. Chỉ dùng cho cơ sở KCB |
| VNCoreExtHealthUnitRank |
Organization |
CodeableConcept |
VNHealthUnitRankVS (required) |
Hạng I-IV cho y tế dự phòng, TTYT, kiểm nghiệm (TT 06/2024) |
| VNCoreExtOrgRankStatus |
Organization |
CodeableConcept |
VNOrganizationRankStatusVS (required) |
Biểu diễn đã xếp hạng / chưa xếp hạng / không áp dụng |
| VNCoreExtOrgLevel |
Organization |
CodeableConcept |
VNHealthcareLevelVS (required) |
Cấp quản lý hành chính sau mô hình 2 cấp |
| VNCoreExtOrgType |
Organization |
Coding |
VNOrganizationTypeVS (required) |
Phân biệt công lập / tư nhân / liên doanh |
| VNCoreExtFacilityCareLevel |
Organization, Location |
CodeableConcept |
VNFacilityCareLevelVS (required) |
3 cấp KCB hiện hành theo Luật KCB 2023, NĐ 96/2023 |
| VNCoreExtLegacyTechnicalLine |
Organization |
CodeableConcept |
VNLegacyTechnicalLineVS (required) |
Tuyến 1-4 theo TT 43/2013 cho dữ liệu legacy (đã hết hiệu lực 18/10/2024) |
| VNCoreExtQualityScoreBand |
Organization |
CodeableConcept |
VNQualityScoreBandVS (required) |
NĐ 188/2025 dùng ngưỡng <50 / 50-70 / >70 cho hưởng BHYT trái tuyến |
Lâm sàng và luồng nghiệp vụ
| Extension |
Context |
Type |
Binding |
Lý do |
| VNCoreExtTreatmentOutcome |
Encounter |
CodeableConcept |
VNTreatmentOutcomeVS (required) |
KET_QUA_DTRI (QĐ 3176) — 8 giá trị. Khác với dischargeDisposition (MA_LOAI_RV) |
| VNCoreExtReferralMode |
Encounter |
Coding |
— |
Hình thức chuyển tuyến (HTCHUYEN) |
| VNCoreExtEncounterCode |
Encounter |
Identifier |
— |
MA_LUOT_KCB dưới dạng Identifier |
Tài chính và thanh toán
| Extension |
Context |
Type |
Lý do |
| VNCoreExtClaimCostSummary |
Claim |
complex (Money) |
Tổng hợp chi phí KCB theo QĐ 697. FHIR Claim.total chỉ có 1 trường |
| VNCoreExtClaimItemDepartment |
Claim.item |
string |
MA_KHOA (QĐ 3176) — khoa chỉ định dịch vụ |
| VNCoreExtClaimPaymentPeriod |
Claim |
Period |
Kỳ thanh toán BHYT (tháng/quý) — đối soát CSKCB vs BHXH |
| VNCoreExtInsuranceCostInfo |
MedicationRequest, Procedure, DeviceUseStatement, Claim.item |
complex (PHAM_VI, TYLE_TT, MUC_HUONG) |
Chi tiết phân bổ chi phí BHYT theo dòng dịch vụ: phạm vi BHYT, tỷ lệ thanh toán, mức hưởng (QĐ 3176) |
| VNCoreExtPaymentMethod |
Claim |
Coding |
Phương thức thanh toán: BHYT, thu phí, miễn phí, viện phí |
| VNCoreExtOrderDate |
Claim.item |
date |
NGAY_YL (QĐ 3176) — ngày y lệnh, khác servicedDate |
Dược phẩm
| Extension |
Context |
Type |
Lý do |
| VNCoreExtMedRegNumber |
MedicationRequest, Medication, Claim.item |
string |
Số đăng ký lưu hành thuốc (Cục QLD/BYT) — bắt buộc khi kê đơn BHYT (SO_DANG_KY per QĐ 3176) |
Trang thiết bị
| Extension |
Context |
Type |
Lý do |
| VNCoreExtDeviceInsuranceScope |
Device |
CodeableConcept (extensible → $vn-insurance-scope-vs) |
Phạm vi BH TBYT (PHAM_VI per QĐ 3176): trong danh mục BHYT / ngoài danh mục / không chi trả |
| VNCoreExtDeviceGroup |
Device |
CodeableConcept |
Nhóm thiết bị y tế theo danh mục BHYT (VNDeviceGroupVS, extensible): N01-N09 theo TT 04/2017/TT-BYT Phụ lục 01, sửa đổi bởi TT 24/2025/TT-BYT và hợp nhất trong VBHN 14/VBHN-BYT |
Extension chuẩn HL7 được tái sử dụng
VNCorePatient dùng 3 extension chuẩn HL7 thay vì tạo mới, theo hướng triển khai của JP Core và CH Core:
| Extension |
URL |
Cách dùng VN Core |
patient-religion |
http://hl7.org/fhir/StructureDefinition/patient-religion |
Bind VNReligionVS, khuyến nghị mã kép với v3-ReligiousAffiliation khi có ánh xạ 1-1 |
patient-citizenship |
http://hl7.org/fhir/StructureDefinition/patient-citizenship |
Mã ISO 3166-1 |
patient-birthPlace |
http://hl7.org/fhir/StructureDefinition/patient-birthPlace |
Constrain về VNCoreAddress để mang tỉnh/xã phục vụ đối soát dân cư |
Liên hệ với các trang khác
English Summary
VN Core IG defines 29 local extensions covering Vietnam-specific data: ethnicity, occupation, force-majeure reason, province/ward, BHYT card classification, organization rank, claim/payment metadata, medication registration number, and device insurance grouping. Religion, citizenship, and birth place reuse standard HL7 extensions constrained for Vietnamese terminology.
