# Liên thông hồ sơ BHYT - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Liên thông hồ sơ BHYT

# Liên thông hồ sơ thanh toán BHYT — BHYT Submission

## Phạm vi

Lớp `BHYT Submission` được tách khỏi `VN Core Base` để tránh buộc mọi triển khai FHIR nội bộ phải phụ thuộc trực tiếp vào định dạng gateway của BHXH. Đây là lớp liên thông hồ sơ thanh toán BHYT, bổ sung:

* [VNCoreBHYTSubmissionBundle](StructureDefinition-vn-core-bhyt-submission-bundle.md) cho Bundle hồ sơ thanh toán BHYT
* Tham số tìm kiếm theo `MA_LK`
* Logical models cho `Check-in` và các bảng dữ liệu đầu ra
* OperationDefinition cho validate, submit, reverse hồ sơ thanh toán BHYT
* Ví dụ hợp lệ/không hợp lệ cho các tình huống thanh toán phổ biến

## Nguyên tắc thiết kế

### FHIR-native trước, gateway sau

FHIR resources (`Patient`, `Encounter`, `Coverage`, `Claim`, `ExplanationOfBenefit`) là nguồn dữ liệu chuẩn bên trong hệ thống. Lớp liên thông chỉ chịu trách nhiệm:

* Chuẩn hóa `MA_LK`
* Ánh xạ sang cấu trúc dữ liệu đầu ra đang có hiệu lực
* Đóng gói payload API gửi cơ quan BHXH
* Kiểm tra các hard rule của hồ sơ thanh toán

### Chuẩn pháp lý đầu vào

Lớp này dựa trên các văn bản hiện hành:

* `QĐ 130/QĐ-BYT`
* `QĐ 4750/QĐ-BYT`
* `QĐ 3176/QĐ-BYT`
* `QĐ 697/QĐ-BYT`
* `TT 12/2026/TT-BTC`
* `NĐ 164/2025/NĐ-CP`
* `NĐ 188/2025/NĐ-CP`

`QĐ 4210/QĐ-BYT` chỉ được xem như bối cảnh lịch sử và không còn là chuẩn đầu ra đang áp dụng.

## Quy tắc bắt buộc tối thiểu

### MA_LK

* `MA_LK` là khóa liên kết hồ sơ bắt buộc
* Phải đồng nhất giữa Bundle hồ sơ thanh toán và Claim thanh toán
* Bên triển khai nên coi đây là khóa nghiệp vụ duy nhất cho một đợt KCB gửi BHXH

### SO_CCCD

* `SO_CCCD` mặc định là bắt buộc
* Chỉ được để trống nếu có lý do bất khả kháng hợp lệ
* Hồ sơ thiếu `SO_CCCD` nhưng không có mã lý do phải bị từ chối ở `gateway layer`

### Định dạng ngày giờ export

* FHIR nội bộ dùng `date`, `dateTime`, `instant`
* Dữ liệu export/gateway phải serialize thành `yyyyMMddHHmm`
* Validator phía server phải kiểm tra định dạng trước khi submit

## Operation đề xuất

| | |
| :--- | :--- |
| `$validate-bhyt-claim` | Kiểm tra hồ sơ có đủ điều kiện gửi BHXH hay không |
| `$submit-bhyt-claim` | Đóng gói và gửi hồ sơ thanh toán |
| `$reverse-bhyt-claim` | Thu hồi/hủy hồ sơ đã gửi |

## Mapping matrix ở mức logical model

Từ `0.3.0`, toàn bộ `13` logical models của lớp `BHYT Submission` đều có `mapping` annotations trực tiếp trong `StructureDefinition` để chỉ rõ nguồn dữ liệu FHIR-native cho lớp liên thông hồ sơ thanh toán BHYT.

| | |
| :--- | :--- |
| `Check-in`,`XML1`,`XML2`,`XML3` | `Claim`,`Coverage`,`Patient`,`Encounter`,`Organization` |
| `XML4` | `DiagnosticReport`+`Observation` |
| `XML5`,`XML6`,`XML7` | `Composition`+`Encounter` |
| `XML8`,`XML9`,`XML10`,`XML11`,`XML12` | `DocumentReference`+`Patient`+`RelatedPerson` |

Nguyên tắc diễn giải:

* Nếu một field có nguồn FHIR chuẩn rõ ràng, mapping chỉ ra element nguồn ưu tiên.
* Nếu field là giá trị export phát sinh trong quá trình round-trip, mapping sẽ ghi rõ đây là giá trị `derived`.
* Nếu field chưa có element lõi tương ứng trong `VN Core`, mapping comment phải nói rõ đó là `reserved slot` hoặc `fallback`, không được mô tả như đã có semantics ổn định.

### Guardrail mapping BHYT

Các trường dễ nhầm nghĩa phải map theo đúng profile VN Core hiện hành:

| | | |
| :--- | :--- | :--- |
| `MA_DOITUONG_KCB` | [VNCoreClaim](StructureDefinition-vn-core-claim.md)`.subType` | Không fallback sang`Coverage.extension[bhytCardType]` |
| `MA_CSKCB` | [VNCoreEncounter](StructureDefinition-vn-core-encounter.md)`.serviceProvider`hoặc[VNCoreClaim](StructureDefinition-vn-core-claim.md)`.provider` | Không fallback sang`Coverage.extension[primaryCareFacility]`vì đó là`MA_DKBD` |
| `MA_DKBD` | [VNCoreCoverage](StructureDefinition-vn-core-coverage.md)`.extension[primaryCareFacility]` | Không dùng làm cơ sở thực hiện lượt KCB |
| `MA_LOAI_KCB` | [VNCoreEncounter](StructureDefinition-vn-core-encounter.md)`.type` | Không dùng`Claim.type` |
| `XML1_ID` | [VNCoreClaimResponse](StructureDefinition-vn-core-claim-response.md)`.identifier[gatewayResponseId]`+ SearchParameter`vn-sp-claim-response-xml1-id` | Không thay thế`MA_LK`của Claim/Bundle |

Các guardrail này được lưu trong FSH profile/logical model và phải được giữ đồng bộ với Wiki traceability.

## Chuỗi thuốc BHYT: kê đơn → cấp phát → thanh toán

[VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) là mắt xích quan trọng trong chuỗi dữ liệu BHYT, đặc biệt với đơn thuốc ngoại trú liên thông Hệ thống đơn thuốc quốc gia theo **TT 26/2025/TT-BYT ngày 30/06/2025 Điều 12**.

Các điểm mapping chính:

* `authorizingPrescription` tham chiếu [VNCoreMedicationRequest](StructureDefinition-vn-core-medication-request.md), giữ link về đơn thuốc/y lệnh gốc và các trường nguồn như `SO_DANG_KY`, `MA_THUOC`, `NGAY_YL` trong dữ liệu đầu ra KCB.
* `whenHandedOver` map `NGAY_CAP` khi hệ thống nguồn có ngày cấp/giao thuốc.
* `performer.actor` tham chiếu [VNCorePractitioner](StructureDefinition-vn-core-practitioner.md), [VNCorePractitionerRole](StructureDefinition-vn-core-practitioner-role.md), hoặc [VNCoreOrganization](StructureDefinition-vn-core-organization.md) để biểu diễn dược sĩ, vai trò hành nghề, khoa Dược hoặc đơn vị cấp phát.
* [VNCoreExtInsuranceCostInfo](StructureDefinition-vn-ext-insurance-cost-info.md), [VNCoreExtMedRegNumber](StructureDefinition-vn-ext-med-reg-number.md) và [VNCoreExtPaymentSource](StructureDefinition-vn-ext-payment-source.md) được reuse trên MedicationDispense/MedicationRequest hoặc `Claim.item`; không tạo extension mới cho cùng semantics.
* `NGUON_CTRA` của XML2 được mô hình hóa ở mức item thuốc bằng `VNCoreExtPaymentSource`, với semantics theo QĐ 130/QĐ 3176: `1` quỹ BHYT, `2` thuốc của dự án/viện trợ, `3` thuốc thuộc chương trình mục tiêu quốc gia, `4` nguồn khác. Không dùng `Coverage.type` để mang trường này.

Mapping tối thiểu từ XML thuốc/DVKT sang FHIR:

| | | |
| :--- | :--- | :--- |
| `MA_THUOC` | `MedicationDispense.medicationCodeableConcept` | [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) |
| `NGAY_CAP` | `MedicationDispense.whenHandedOver` | [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) |
| `SO_DANG_KY` | Extension[VNCoreExtMedRegNumber](StructureDefinition-vn-ext-med-reg-number.md) | [VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) |
| `NGUON_CTRA` | Extension[VNCoreExtPaymentSource](StructureDefinition-vn-ext-payment-source.md)trên`Claim.item`,`MedicationRequest`,`MedicationDispense` | [VNCoreClaim](StructureDefinition-vn-core-claim.md),[VNCoreMedicationRequest](StructureDefinition-vn-core-medication-request.md),[VNCoreMedicationDispense](StructureDefinition-vn-core-medication-dispense.md) |

## Chẩn đoán hình ảnh trong hồ sơ BHYT

Với chi phí CĐHA, [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md) giữ metadata DICOM/RIS/PACS, còn [VNCoreDiagnosticReportImaging](StructureDefinition-vn-core-diagnostic-report-imaging.md) giữ báo cáo đã đọc và phiếu kết quả.

* `VNCoreImagingStudy.procedureCode` biểu diễn kỹ thuật CĐHA được thực hiện.
* `VNCoreDiagnosticReportImaging.category` gồm nhóm diagnostic service `RAD` và nhóm chi phí `4` CĐHA theo **QĐ 697/QĐ-BYT ngày 19/03/2026**.
* `DiagnosticReport.imagingStudy` tham chiếu về [VNCoreImagingStudy](StructureDefinition-vn-core-imaging-study.md), giúp nối chỉ định, thực hiện chụp và báo cáo đọc phim trước khi tổng hợp [VNCoreClaim](StructureDefinition-vn-core-claim.md).

## Phạm vi chưa công bố như tài nguyên chuẩn

* Chưa phát hành `ConceptMap` quốc tế cho `facilityCareLevel`/`organizationRank`.
* Lý do: hiện chưa có target terminology quốc tế đủ ổn định và đủ tương đương ngữ nghĩa cho mô hình năng lực KCB theo `NĐ 188/2025`.
* Các ánh xạ quốc tế kiểu này hiện được giữ ở mức `experimental analysis`, không đưa vào lớp core ổn định để tránh tạo equivalence giả.

## Liên hệ với các trang khác

| | |
| :--- | :--- |
| Tra cứu cơ sở pháp lý (QĐ 130, QĐ 4750, QĐ 3176, QĐ 697, NĐ 188/2025) | [Cơ sở pháp lý](legal-basis.md) |
| Xem các hồ sơ FHIR liên quan đến bundle thanh toán BHYT | [Danh mục hồ sơ](profiles.md) |
| Kiểm tra hợp lệ bundle nộp BHYT trước khi submit | [Hướng dẫn kiểm tra hợp lệ](validation-guidance.md) |
| Hiểu các định danh dùng trong hồ sơ thanh toán (CCCD, BHYT, mã CSKCB) | [Identifier Registry](identifier-registry.md) |

## English Summary

The BHYT Submission layer isolates Vietnam's health insurance gateway requirements from the FHIR-native core, providing a submission bundle, logical models for all 13 output tables with inline FHIR mapping annotations, and operations for claim validation, submission, and reversal. It is aligned with the current legal framework (QD 130, QD 4750, QD 3176, QD 697, TT 12/2026/TT-BTC) and treats QD 4210 as historical context only.

