# Mở rộng (Extensions) - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Mở rộng (Extensions)

# Phần mở rộng — Extensions

Phiên bản `0.5.0` công bố 44 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ơ](profiles.md) và [Hướng dẫn thuật ngữ](terminology-guidance.md).

-------

## Tổng quan

VN Core IG định nghĩa **44 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â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, loại đơn vị cấp xã | 3 |
| Bảo hiểm y tế và Coverage (Insurance & Coverage) | Loại thẻ BHYT, Nơi ĐKKCB, Loại KCB BHYT, tổng cùng chi trả lũy kế | 4 |
| 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, cơ quan hướng dẫn chuyên môn | 9 |
| 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, loại chương trình tiêm chủng | 4 |
| Tài chính và thanh toán (Claims) | Chi phí Claim, Khoa chỉ định, Thời gian thanh toán, Chi phí BHYT, nguồn chi trả, thông tin thầu, phương thức chế biến YHCT, flag vết thương tái phát, trạng thái giám định, số biên bản quyết toán, Phương thức thanh toán, Ngày y lệnh, phạm vi BH TBYT legacy | 13 |
| Dược phẩm (Medication) | Số đăng ký thuốc | 1 |
| Trang thiết bị (Device) | Nhóm TBYT BHYT, phân loại rủi ro A/B/C/D, số lưu hành, cờ IVD | 4 |
| Governance, consent và audit | Căn cứ pháp lý, phương thức đồng ý, thời hạn lưu trữ audit | 3 |

-------

## Nhân khẩu học và định danh

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| [VNCoreExtEthnicity](StructureDefinition-vn-ext-ethnicity.md) | `Patient` | `CodeableConcept` | `VNEthnicityVS`(required) | FHIR base chỉ có US Race/Ethnicity. VN có 54 dân tộc theo 121/TCTK-PPCĐ |
| [VNCoreExtOccupation](StructureDefinition-vn-ext-occupation.md) | `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](StructureDefinition-vn-ext-force-majeure-reason.md) | `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ỉ

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| [VNCoreExtProvince](StructureDefinition-vn-ext-province.md) | `Address` | `Coding` | `VNProvinceVS`(required) | `Address.state`là text tự do. Extension dùng mã coded theo NQ 202/2025 (34 tỉnh/TP) |
| [VNCoreExtWard](StructureDefinition-vn-ext-ward.md) | `Address` | `Coding` | `VNWardVS`(required) | FHIR base không có ward/commune. Xã là cấp 2 chính thức sau NQ 202/2025 |
| [VNCoreExtWardType](StructureDefinition-vn-ext-ward-type.md) | `Address` | `Coding` | `VNWardTypeVS`(required) | Phân biệt xã, phường và đặc khu khi dữ liệu địa chỉ cần semantics cấp xã rõ hơn text |

-------

## Bảo hiểm y tế

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| [VNCoreExtBHYTCardType](StructureDefinition-vn-ext-bhyt-card-type.md) | `Coverage` | `Coding` | `VNBHYTCardTypeVS`(required) | Loại đối tượng BHYT (DN, TE, HN, CC…) ảnh hưởng mức hưởng |
| [VNCoreExtPrimaryCareFacility](StructureDefinition-vn-ext-primary-care-facility.md) | `Coverage` | `Reference(Organization)` | — | Thẻ BHYT ghi nơi ĐKKCB ban đầu — ảnh hưởng đúng/trái tuyến |
| [VNCoreExtInsuranceVisitType](StructureDefinition-vn-ext-insurance-visit-type.md) | `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 |
| [VNCoreExtCoverageCumulativeCopay](StructureDefinition-vn-ext-coverage-cumulative-copay.md) | `Coverage` | `Money` | — | Tổng cùng chi trả lũy kế trong năm để phục vụ chính sách quyền lợi BHYT |

-------

## Tổ chức

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| [VNCoreExtOrgRank](StructureDefinition-vn-ext-org-rank.md) | `Organization` | `CodeableConcept` | `VNHospitalRankVS`(required) | Hạng cơ sở KCB theo TT 06/2024. Chỉ dùng cho cơ sở KCB |
| [VNCoreExtHealthUnitRank](StructureDefinition-vn-ext-health-unit-rank.md) | `Organization` | `CodeableConcept` | `VNHealthUnitRankVS`(required) | Hạng I-IV cho y tế dự phòng, TTYT, kiểm nghiệm (TT 06/2024) |
| [VNCoreExtOrgRankStatus](StructureDefinition-vn-ext-org-rank-status.md) | `Organization` | `CodeableConcept` | `VNOrganizationRankStatusVS`(required) | Biểu diễn`đã xếp hạng`/`chưa xếp hạng`/`không áp dụng` |
| [VNCoreExtOrgLevel](StructureDefinition-vn-ext-org-level.md) | `Organization` | `CodeableConcept` | `VNHealthcareLevelVS`(required) | Cấp quản lý hành chính sau mô hình 2 cấp |
| [VNCoreExtOrgType](StructureDefinition-vn-ext-org-type.md) | `Organization` | `Coding` | `VNOrganizationTypeVS`(required) | Phân biệt công lập / tư nhân / liên doanh |
| [VNCoreExtFacilityCareLevel](StructureDefinition-vn-ext-facility-care-level.md) | `Organization`,`Location` | `CodeableConcept` | `VNFacilityCareLevelVS`(required) | 3 cấp KCB hiện hành theo Luật KCB 2023, NĐ 96/2023 |
| [VNCoreExtLegacyTechnicalLine](StructureDefinition-vn-ext-legacy-technical-line.md) | `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](StructureDefinition-vn-ext-quality-score-band.md) | `Organization` | `CodeableConcept` | `VNQualityScoreBandVS`(required) | NĐ 188/2025 dùng ngưỡng`<50`/`50-70`/`>70`cho hưởng BHYT trái tuyến |
| [VNCoreExtSupervisingAuthority](StructureDefinition-vn-ext-supervising-authority.md) | `Organization` | `Reference(Organization)` | — | Cơ quan hướng dẫn chuyên môn kỹ thuật khi khác với quan hệ quản lý hành chính |

-------

## Lâm sàng và luồng nghiệp vụ

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| [VNCoreExtTreatmentOutcome](StructureDefinition-vn-ext-treatment-outcome.md) | `Encounter` | `CodeableConcept` | `VNTreatmentOutcomeVS`(required) | KET_QUA_DTRI (QĐ 3176) — 8 giá trị. Khác với`dischargeDisposition`(MA_LOAI_RV) |
| [VNCoreExtReferralMode](StructureDefinition-vn-ext-referral-mode.md) | `Encounter` | `Coding` | — | Hình thức chuyển tuyến (HTCHUYEN) |
| [VNCoreExtEncounterCode](StructureDefinition-vn-ext-encounter-code.md) | `Encounter` | `Identifier` | — | MA_LUOT_KCB dưới dạng Identifier |
| [VNCoreExtImmunizationProgramType](StructureDefinition-vn-ext-immunization-program-type.md) | `Immunization` | `CodeableConcept` | `VNImmunizationProgramTypeVS`(required) | Phân biệt TCMR, dịch vụ và chiến dịch tiêm chủng |

-------

## Tài chính và thanh toán

| | | | |
| :--- | :--- | :--- | :--- |
| [VNCoreExtClaimCostSummary](StructureDefinition-vn-ext-claim-cost-summary.md) | `Claim` | `complex`(Money) | Tổng hợp chi phí KCB theo QĐ 697. FHIR`Claim.total`chỉ có 1 trường |
| [VNCoreExtClaimItemDepartment](StructureDefinition-vn-ext-claim-item-department.md) | `Claim.item` | `string` | MA_KHOA (QĐ 3176) — khoa chỉ định dịch vụ |
| [VNCoreExtClaimPaymentPeriod](StructureDefinition-vn-ext-claim-payment-period.md) | `Claim` | `Period` | Kỳ thanh toán BHYT (tháng/quý) — đối soát CSKCB vs BHXH |
| [VNCoreExtInsuranceCostInfo](StructureDefinition-vn-ext-insurance-cost-info.md) | `MedicationRequest`,`Procedure`,`Claim.item`,`ServiceRequest`,`MedicationDispense` | `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). Với thiết bị/vật tư, ưu tiên đặt trên`Claim.item`; không dùng trên`DeviceUseStatement`. |
| [VNCoreExtDeviceInsuranceScope](StructureDefinition-vn-ext-device-insurance-scope.md) | `Claim.item` | `CodeableConcept`(extensible →`$vn-insurance-scope-vs`) | Compatibility extension cho phạm vi BH TBYT (PHAM_VI per QĐ 3176). Dữ liệu mới nên dùng`Claim.item.extension[insuranceCostInfo].scope`; không dùng trên`Device`hoặc`DeviceUseStatement`. |
| [VNCoreExtPaymentSource](StructureDefinition-vn-ext-payment-source.md) | `Claim.item`,`ExplanationOfBenefit.item`,`MedicationRequest`,`MedicationDispense` | `CodeableConcept` | NGUON_CTRA theo QĐ 3176 cho dòng chi phí, đặc biệt XML2 thuốc |
| [VNCoreExtTenderInfo](StructureDefinition-vn-ext-tender-info.md) | `Claim.item`,`ExplanationOfBenefit.item`,`MedicationRequest`,`MedicationDispense` | `complex` | TT_THAU cho thuốc/vật tư/thiết bị trong dữ liệu KCB/BHYT |
| [VNCoreExtTraditionalProcessingMethod](StructureDefinition-vn-ext-traditional-processing-method.md) | `Claim.item`,`ExplanationOfBenefit.item`,`MedicationRequest`,`MedicationDispense` | `CodeableConcept` | Carrier cho`MA_PP_CHEBIEN`của vị thuốc/dược liệu/YHCT khi xuất dữ liệu BHYT |
| [VNCoreExtRecurrentWoundBenefit](StructureDefinition-vn-ext-recurrent-wound-benefit.md) | `Claim.item`,`ExplanationOfBenefit.item` | `boolean` | Flag`VET_THUONG_TP`ở dòng chi phí BHYT; không phải mã chẩn đoán tái phát |
| [VNCoreExtClaimAuditStatus](StructureDefinition-vn-ext-claim-audit-status.md) | `PaymentReconciliation`,`Task`,`ClaimResponse` | `CodeableConcept` | Vòng đời giám định/quyết toán BHYT nội địa, bổ sung cho`PaymentReconciliation.outcome`chuẩn FHIR |
| [VNCoreExtPaymentReconciliationForm](StructureDefinition-vn-ext-payment-reconciliation-form.md) | `PaymentReconciliation` | `string` | Số hiệu biên bản 06/BH theo TT 12/2026/TT-BTC |
| [VNCoreExtPaymentMethod](StructureDefinition-vn-ext-payment-method.md) | `Claim` | `Coding` | Phương thức thanh toán: BHYT, thu phí, miễn phí, viện phí |
| [VNCoreExtOrderDate](StructureDefinition-vn-ext-order-date.md) | `Claim.item` | `date` | NGAY_YL (QĐ 3176) — ngày y lệnh, khác`servicedDate` |

-------

## Dược phẩm

| | | | |
| :--- | :--- | :--- | :--- |
| [VNCoreExtMedRegNumber](StructureDefinition-vn-ext-med-reg-number.md) | `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ị

| | | | |
| :--- | :--- | :--- | :--- |
| [VNCoreExtDeviceGroup](StructureDefinition-vn-ext-device-group.md) | `Claim.item`,`Device`legacy/fallback | `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. Ưu tiên đặt trên dòng chi phí`Claim.item`khi phục vụ thanh toán. |
| [VNCoreExtDeviceRiskClass](StructureDefinition-vn-ext-device-risk-class.md) | `Device` | `CodeableConcept` | Phân loại rủi ro A/B/C/D theo NĐ 98/2021/NĐ-CP Điều 4 và TT 05/2022/TT-BYT; extension tùy chọn, không thay nhóm BHYT hoặc danh pháp thiết bị |
| [VNCoreExtDeviceRegistrationNumber](StructureDefinition-vn-ext-device-registration-number.md) | `Device`,`DeviceDefinition` | `Identifier` | Số lưu hành TBYT cho class B/C/D theo NĐ 98/2021 và các sửa đổi; là định danh regulatory ở mức sản phẩm/model |
| [VNCoreExtDeviceIVD](StructureDefinition-vn-ext-device-ivd.md) | `Device` | `boolean` | Cờ phân biệt thiết bị chẩn đoán in vitro khi dữ liệu nguồn cần tách IVD khỏi TBYT thông thường |

-------

## Governance, consent và audit

| | | | |
| :--- | :--- | :--- | :--- |
| [VNCoreExtLegalBasis](StructureDefinition-vn-ext-legal-basis.md) | `ElementDefinition`,`StructureDefinition`,`CodeSystem`,`ValueSet` | `Coding` | Tham chiếu structured tới`VNLegalDocumentRefCS`để audit căn cứ pháp lý bằng máy |
| [VNCoreExtConsentMethod](StructureDefinition-vn-ext-consent-method.md) | `Consent`,`Consent.provision` | `CodeableConcept` | Phương thức chủ thể dữ liệu thể hiện đồng ý theo Luật 91/2025 và NĐ 356/2025 |
| [VNCoreExtAuditRetention](StructureDefinition-vn-ext-audit-retention.md) | `AuditEvent` | `Duration` | Thời hạn lưu trữ log/audit phục vụ incident response và nghĩa vụ bảo vệ DLCN |

-------

## 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:

| | | |
| :--- | :--- | :--- |
| `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

| | |
| :--- | :--- |
| Xem các hồ sơ FHIR sử dụng extension | [Danh mục hồ sơ](profiles.md) |
| Hiểu cách ràng buộc thuật ngữ và binding trong extension | [Hướng dẫn thuật ngữ và binding](terminology-guidance.md) |
| Tra cứu CodeSystem/ValueSet mà extension tham chiếu | [Danh mục thuật ngữ](terminology.md) |
| Biết element nào bắt buộc Must Support khi dùng extension | [Hướng dẫn Must Support](must-support-guidance.md) |

## English Summary

VN Core IG defines 44 local extensions covering Vietnam-specific data: ethnicity, occupation, force-majeure reason, province/ward, BHYT card classification, organization rank, claim/payment metadata, medication registration number, device insurance/risk/registration data, structured legal basis, consent method, and audit retention. Religion, citizenship, and birth place reuse standard HL7 extensions constrained for Vietnamese terminology.

