FHIR BHYT: ánh xạ XML BHYT (QĐ 130/4750/3176) sang Coverage, Claim, EOB

1. Bối cảnh FHIR BHYT — vì sao cần bridge XML và FHIR

Các cơ sở khám chữa bệnh trao đổi dữ liệu đầu ra phục vụ giám định và thanh toán BHYT với Bảo hiểm xã hội Việt Nam (BHXH) theo chuỗi định dạng XML hiện hành; khối lượng phụ thuộc từng cơ sở và kỳ quyết toán. Chuỗi văn bản hiện hành bắt đầu từ QĐ 130/QĐ-BYT (2023), được sửa đổi bởi QĐ 4750/QĐ-BYT (2023), rồi tiếp tục được sửa bởi QĐ 3176/QĐ-BYT ngày 29/10/2024; QĐ 4210/QĐ-BYT là nguồn gốc lịch sử của cách gọi “XML 4210”.

Nhiều tài liệu kỹ thuật và đội ngũ phát triển vẫn quen gọi tệp XML này là "XML 4210" theo tên QĐ 4210/QĐ-BYT gốc. Tên gọi shorthand này không sai về mặt văn hóa kỹ thuật, nhưng khi viết spec hoặc trích dẫn pháp lý, mọi tham chiếu phải về đúng chuỗi QĐ 130/QĐ-BYT / 4750 / 3176. Đây là điểm quan trọng vì BHXH thực hiện giám định dựa trên schema và mã đối tượng theo các quyết định mới, không phải QĐ 4210/QĐ-BYT.

Schema XML này được quản trị cho luồng đầu ra BHYT, nên phạm vi và quy tắc thay đổi gắn với văn bản áp dụng. Việc tái sử dụng trực tiếp cho EMR hoặc Sổ sức khỏe điện tử bị giới hạn bởi khác biệt use case và semantics. Tra cứu điều kiện hưởng/thẻ BHYT là một contract tích hợp riêng; không nên suy diễn contract đó từ schema đầu ra hoặc từ FHIR REST.

FHIR R4 (4.0.1) cung cấp các Resource tài chính như Coverage, Claim, ClaimResponse, ExplanationOfBenefit, Invoice và PaymentReconciliation. Chúng hỗ trợ mô hình dữ liệu có cấu trúc nhưng không tương đương một-một với schema BHYT và không thay thế định dạng nộp chính thức. Một lựa chọn kiến trúc là dùng mô hình FHIR ở tầng liên thông rồi sinh XML qua mapping được quản trị và kiểm thử; hệ thống cũng có thể chọn adapter khác nếu đáp ứng cùng contract và yêu cầu truy vết.

2. Khung pháp lý BHYT 2023-2026

Bảng dưới tóm tắt các văn bản BV và đội ngũ FHIR cần đọc khi thiết kế bridge layer. Mọi mã căn cứ tham chiếu chính xác theo CodeSystem VNLegalDocumentRefCS trong VN Core IG.

3. Bốn use case FHIR BHYT chính

Bridge layer XML BHYT và FHIR phục vụ bốn luồng nghiệp vụ. Mỗi luồng map sang một resource hoặc operation FHIR, dù BHXH hiện chưa nhận FHIR official. Các đoạn pseudocode dưới đây dùng để mô tả ý đồ thiết kế REST API nội bộ — không phải FHIR instance đầy đủ. VN Core v0.9.0 đã có các mẫu R4 hợp lệ như ExampleClaimBHYT, ExampleClaimResponseBHYT, ExampleExplanationOfBenefitBHYT và ExamplePaymentReconciliationBHYT để đối chiếu khi triển khai.

3.1. Tra cứu thẻ BHYT — Coverage

Khi bệnh nhân đăng ký KCB, BV cần xác minh thẻ BHYT còn hiệu lực, đối tượng nào, nơi đăng ký KCB ban đầu là cơ sở nào. Trong mô hình FHIR-native nội bộ, BV đọc Coverage theo identifier:

GET /Coverage?identifier=http://fhir.hl7.org.vn/core/sid/bhyt|DN4123456789012
Accept: application/fhir+json

VN Core hiện dùng profile trial-use VNCoreCoverageEligibilityRequest và VNCoreCoverageEligibilityResponse để mô hình hóa yêu cầu/kết quả kiểm tra quyền lợi nội bộ. Package chưa xuất bản OperationDefinition Coverage/$verify-eligibility, và NĐ 164/2025/NĐ-CP không định nghĩa operation FHIR này. Nếu một dự án tự thêm operation, phải công bố OperationDefinition, khai trong CapabilityStatement và ánh xạ sang đúng contract Cổng BHXH. Mã đối tượng đến KCB theo QĐ 3276/QĐ-BYT thuộc Claim.subType, không thuộc Coverage.type.

3.2. Gửi yêu cầu thanh toán — Claim

Sau khi kết thúc đợt KCB, BV gửi yêu cầu thanh toán. Trong nội bộ EMR, đây là một Claim:

POST /Claim
Content-Type: application/fhir+json

# Pseudocode shape — Claim hợp lệ R4 cần đầy đủ
# status, type, use, created, priority, insurance.sequence, insurance.focal.
# Xem mẫu chuẩn trong VN Core IG.

Bridge layer sau đó render Claim này thành tệp XML theo schema QĐ 130/4750/3176 và đẩy lên Cổng BHXH. Việc giữ Claim FHIR ở nội bộ giúp BV chia sẻ cùng một dataset cho EMR (Thông tư 13/2025/TT-BYT), nội bộ kế toán, và cho VNeID Sổ sức khỏe điện tử nếu sau này có yêu cầu.

3.3. Nhận phản hồi BHXH — ClaimResponse / EOB

BHXH giám định và trả lại kết quả: chấp thuận, từ chối, hoặc cần bổ sung. Bộ chuyển đổi chuyển thông báo XML đó thành ClaimResponse trong nội bộ. Mỗi item gốc trong Claim có một entry tương ứng trong ClaimResponse.item.adjudication, ghi rõ T_BNTT (số tiền bệnh nhân tự trả) và T_BHTT (số tiền BHYT chi trả). Cho mục đích báo cáo retrospective hoặc đẩy lên VNeID, ExplanationOfBenefit (EOB) là resource phù hợp hơn vì nó tổng hợp đầy đủ context quyền lợi và kết quả giám định.

3.4. Quyết toán định kỳ — PaymentReconciliation

Hằng quý, BV và cơ quan BHXH ký biên bản quyết toán. Resource PaymentReconciliation tổng hợp nhiều ClaimResponse và ghi nhận khoản thanh toán cuối cùng. Đây cũng là nơi mapping biểu mẫu 06/BH theo TT 12/2026/TT-BTC vào FHIR.

4. Mapping XML BHYT sang FHIR — bảng chi tiết

Phần dưới chỉ mapping cốt lõi cho ba bảng XML phổ biến nhất. VN Core v0.9.0 hiện cung cấp các ConceptMap hẹp như vn-cm-bhyt-financial-field-to-adjudication và vn-cm-qd3176-cost-group-to-q697-cost-category; mapping đầy đủ cho toàn bộ schema QĐ 130/4750/3176 vẫn cần được pilot thêm theo từng hệ thống HIS/EMR trước khi đóng thành artifact conformance.

4.1. Bảng XML4210_TONGHOP sang Bundle, Patient, Coverage, Encounter, Claim

4.2. Bảng XML4210_CHITIET sang Claim.item

4.3. Bảng XML4210_THUOC sang MedicationRequest và Claim.item

5. Coverage profile cho thẻ BHYT

Coverage trong FHIR mô hình hóa phạm vi và quyền lợi bảo hiểm. Bài này dùng Coverage để biểu diễn thẻ BHYT cụ thể của một bệnh nhân tại một thời điểm. VN Core đề xuất profile VNCoreCoverage với các ràng buộc dưới đây.

Profile: VNCoreCoverage
Parent: Coverage
Id: vn-core-coverage
Title: "VN Core Coverage — Thẻ BHYT"
Description: "Profile Coverage cho thẻ Bảo hiểm y tế Việt Nam."

* identifier 0..* MS
* identifier ^slicing.discriminator.type = #value
* identifier ^slicing.discriminator.path = "system"
* identifier ^slicing.rules = #open
* identifier contains BHYT 0..1 MS
* identifier[BHYT].system = "http://fhir.hl7.org.vn/core/sid/bhyt" (exactly)
* identifier[BHYT].value 1..1
* identifier[BHYT].value obeys vn-bhyt-format
* status 1..1 MS
* type 1..1 MS
* type.coding ^slicing.discriminator.type = #value
* type.coding ^slicing.discriminator.path = "system"
* type.coding ^slicing.rules = #open
* type.coding contains coverageCategory 1..1 MS
* type.coding[coverageCategory].system = "http://terminology.hl7.org/CodeSystem/insurance-coverage-type" (exactly)
* type.coding[coverageCategory].code = #medical (exactly)
* beneficiary 1..1 MS
* policyHolder 0..1
* payor 1..* MS
* period 0..1 MS

// MA_DKBD (mã nơi ĐKKCB ban đầu) KHÔNG bind vào Coverage.network.
// Coverage.network theo spec FHIR R4 dành cho identifier mạng lưới do
// insurer định nghĩa, không phải mã cơ sở KCB ban đầu của VN.
* extension contains
    VNCoreExtBHYTCardType named bhytCardType 0..1 MS and
    VNCoreExtPrimaryCareFacility named primaryCareFacility 0..1 MS and
    VNCoreExtCoverageCumulativeCopay named cumulativeCopay 0..1

VN Core dùng 3 extension chính trên Coverage: VNCoreExtBHYTCardType (loại đối tượng — DN/HC/HS/...), VNCoreExtPrimaryCareFacility (Reference Organization — CSKCB ban đầu, đúng semantics thay vì lạm dụng Coverage.network vốn dành cho identifier mạng lưới insurer) và VNCoreExtCoverageCumulativeCopay (tổng cùng chi trả lũy kế, theo dõi trần 6 tháng lương cơ sở của BHYT).

6. Claim profile cho yêu cầu thanh toán

VNCoreClaim ràng buộc các trường cơ sở KCB phải gửi và bind terminology ở đúng tầng ngữ nghĩa. Trong v0.9.0, diagnosis.diagnosisCodeableConcept bind với bộ mã chẩn đoán, còn item.category bind với 12 nhóm chi phí theo QĐ 697/QĐ-BYT. item.productOrService bắt buộc có nhưng chưa bind vào một ValueSet hợp nhất, vì trường này có thể mang mã DVKT, thuốc hoặc thiết bị từ các danh mục có vòng đời quản trị khác nhau.

Profile: VNCoreClaim
Parent: Claim
Id: vn-core-claim
Title: "VN Core Claim — Yêu cầu thanh toán BHYT"

* status 1..1 MS
* type 1..1 MS
* use 1..1 MS
* subType 0..1 MS
* subType from $vn-patient-visit-type-vs (extensible)
* patient 1..1 MS
* created 1..1 MS
* priority 1..1
* provider 1..1 MS
* insurance 1..* MS
* insurance.focal 1..1 MS
* insurance.coverage 1..1 MS
* diagnosis 1..* MS
* diagnosis.diagnosisCodeableConcept 0..1 MS
* diagnosis.diagnosisCodeableConcept from $vn-condition-code-vs (extensible)
* item 1..* MS
* item.sequence 1..1 MS
* item.category 0..1 MS
* item.category from $vn-cost-category-vs (extensible)
* item.productOrService 1..1 MS
* item.unitPrice 0..1
* item.quantity 0..1
* item.net 0..1 MS

Việc đặt insurance 1..* hỗ trợ trường hợp multi-BHYT theo NĐ 188/2025/NĐ-CP: một bệnh nhân có thể có nhiều thẻ BHYT cùng lúc, mỗi thẻ là một entry trong Claim.insurance với focal đánh dấu thẻ chính dùng cho lần KCB này.

7. ClaimResponse và ExplanationOfBenefit

Adjudication — quyết định BHXH chi trả bao nhiêu, BN tự trả bao nhiêu, từ chối hạng mục nào — thuộc về phía cơ quan thanh toán. Trong FHIR R4, Claim.item không có sub-element adjudication; mọi giá trị giám định nằm trên ClaimResponse.item.adjudication. Bridge layer phải nhận thông báo XML từ BHXH, parse các trường T_BNTT, T_BHTT, T_NGUONKHAC, T_NSNN và dựng ra ClaimResponse có cấu trúc:

Profile: VNCoreClaimResponse
Parent: ClaimResponse
Id: vn-core-claim-response

* status 1..1 MS
* type 1..1 MS
* use 1..1 MS
* patient 1..1 MS
* created 1..1 MS
* insurer 1..1 MS
* request 0..1 MS    // Reference đến Claim gốc khi có
* outcome 1..1 MS
* item 0..* MS
* item.itemSequence 1..1 MS
* item.adjudication 1..* MS
* item.adjudication.category 1..1 MS
* item.adjudication.category from http://hl7.org/fhir/ValueSet/adjudication (extensible)
* item.adjudication.amount 0..1 MS

ExplanationOfBenefit (EOB) là resource cao tầng hơn, hợp nhất Claim và ClaimResponse cộng với context Coverage và Patient. Khi BV cần đẩy lịch sử thanh toán BHYT lên Sổ sức khỏe điện tử trên VNeID hoặc khi nhà cung cấp tích hợp dashboard cho bệnh nhân, EOB là format khuyến nghị.

8. Invoice cho bảng kê chi phí QĐ 697/QĐ-BYT

QĐ 697/QĐ-BYT ban hành ngày 19/3/2026, hiệu lực kể từ 19/3/2026. Thời hạn cuối để các BV nâng cấp phần mềm và chuyển đổi hoàn toàn sang biểu mẫu mới là 01/7/2026 — sau mốc này, biểu mẫu cũ theo QĐ 6556/QĐ-BYT (2018) không còn được chấp nhận. Bảng kê QĐ 697/QĐ-BYT có 12 danh mục chi phí và 13 cột, đồng thời hỗ trợ trường hợp một bệnh nhân có nhiều thẻ BHYT cùng chi trả (multi-BHYT theo NĐ 188/2025/NĐ-CP).

VN Core hiện không tạo Profile Invoice riêng cho QĐ 697/QĐ-BYT; thay vào đó, 12 danh mục chi phí được model trực tiếp trong VNCoreClaim.item: mỗi Claim.item.category bind vào CodeSystem VNCostCategoryCS (canonical vn-cost-category-cs) — mỗi mã tương ứng 1 trong 12 nhóm chi phí của QĐ 697/QĐ-BYT (thuốc, vật tư y tế, dịch vụ kỹ thuật, ...). Claim.item.unitPrice, Claim.item.quantity và Claim.item.net mang chi tiết từng dòng. Phần phân chia BHYT chi trả / BN tự trả / đồng chi trả / NSNN / nguồn khác được tổng hợp ở cấp Claim/EOB qua extension VNCoreExtClaimCostSummary, không tách thành Invoice profile riêng.

// VNCoreClaim — trích đoạn binding QĐ 697/QĐ-BYT (12 nhóm chi phí)
Profile: VNCoreClaim
Parent: Claim
Id: vn-core-claim

// Mỗi item.category tương ứng 1 mã trong VNCostCategoryCS
// (12 nhóm chi phí KCB theo QĐ 697/QĐ-BYT)
* item.category 0..1 MS
* item.category from VNCostCategoryVS (extensible)
* item.unitPrice 0..1
* item.quantity 0..1
* item.net 0..1 MS

// Tổng hợp chi phí cấp Claim (BHYT trả / BN trả / đồng trả / NSNN)
* extension contains
    VNCoreExtClaimCostSummary named costSummary 0..1 MS

9. Mã đối tượng đến KCB theo QĐ 3276/QĐ-BYT

QĐ 3276/QĐ-BYT ban hành ngày 17/10/2025 quy định danh mục 27 mã đối tượng đến KCB BHYT, phân nhóm theo lý do/tuyến KCB (1.x — đúng tuyến, 2 — cấp cứu, 3.x — trái tuyến, 7.x — lĩnh thuốc, 8 — thu hồi, 9 — không BHYT). VN Core mã hóa danh mục này thành CodeSystem VNPatientVisitTypeCS (canonical vn-patient-visit-type-cs) và ValueSet VNPatientVisitTypeVS, ràng buộc vào Claim.subType với mức extensible. Lưu ý phân biệt: Claim.subType mang mã đối tượng đến KCB theo từng lượt, khác với Coverage.extension[bhytCardType] mang nhóm thẻ/người tham gia (DN/HC/HS/...) thuộc về thẻ BHYT. Mỗi mã trong CodeSystem đều có căn cứ pháp lý đầy đủ để truy vết.

10. Mức trần thanh toán theo NĐ 188/2025/NĐ-CP

NĐ 188/2025/NĐ-CP ban hành ngày 01/7/2025, hiệu lực chung từ 15/8/2025; một số điều áp dụng từ 01/7/2025. Nghị định này quy định trần thanh toán BHYT cho một lần KCB tương đương 45 tháng lương cơ sở, nhưng trần này chỉ áp dụng cho các nhóm chi phí và dịch vụ kỹ thuật cao theo quy định cụ thể, không phải mức trần phổ quát cho mọi giá trị Claim.total.

11. API điện tử BHXH theo NĐ 164/2025/NĐ-CP

NĐ 164/2025/NĐ-CP điều chỉnh giao dịch điện tử trong lĩnh vực BHXH; endpoint, payload và quy trình cụ thể phải theo tài liệu vận hành của Cổng BHXH áp dụng cho từng luồng. Hiện trang này chưa có căn cứ để tuyên bố một FHIR REST API chính thức của BHXH. Dùng FHIR nội bộ rồi chuyển sang định dạng/kênh nhận hiện hành là một phương án kiến trúc. Một đặc tả FHIR tương lai của BHXH vẫn có thể buộc thay đổi mô hình miền, terminology, workflow và adapter; không được cam kết chỉ đổi implementation outbound.

12. Câu hỏi thường gặp

BHXH đã chấp nhận FHIR Bundle chưa?

Chưa, tính đến quý 2/2026. BHXH vẫn yêu cầu gửi XML theo schema QĐ 130/QĐ-BYT, được sửa đổi bởi QĐ 4750/QĐ-BYT và QĐ 3176/QĐ-BYT. Tên gọi shorthand "XML 4210" theo QĐ 4210/QĐ-BYT gốc đã bị thay thế.

Có nên build FHIR-first và convert sang XML khi gửi BHXH?

Đây là một phương án kiến trúc cần đánh giá, không phải yêu cầu của TT 13/2025/TT-BYT. Nếu mô hình nội bộ đã được chuẩn hóa theo FHIR, lớp chuyển đổi có thể sinh XML BHXH hiện hành và tái sử dụng một phần dữ liệu cho luồng VNeID. Tuy nhiên mapping phải có version, kiểm thử theo từng bảng XML, lưu provenance và xử lý rõ các trường không tương đương; FHIR-native tự thân không chứng minh tuân thủ pháp lý hay nghiệp vụ BHXH.

QĐ 697/QĐ-BYT có thay QĐ 6556/QĐ-BYT không?

Có. QĐ 6556/QĐ-BYT (2018) đã bị thay thế hoàn toàn bởi QĐ 697/QĐ-BYT. Giai đoạn chuyển tiếp dùng song song (để nâng cấp phần mềm) đã kết thúc ngày 01/07/2026 — hiện chỉ dùng biểu mẫu QĐ 697/QĐ-BYT; mẫu cũ chỉ còn giá trị đối chiếu hồ sơ lập trước mốc này.

Multi-BHYT theo NĐ 188/2025/NĐ-CP implement thế nào trong FHIR?

Claim.insurance là array. Mỗi thẻ BHYT của bệnh nhân là một entry với insurance.sequence khác nhau và insurance.coverage trỏ đến Coverage tương ứng. Một entry duy nhất được đánh dấu insurance.focal=true cho lần KCB cụ thể này. Adjudication trên ClaimResponse giữ nguyên tham chiếu sequence để rõ phần nào thuộc thẻ nào.

MA_DKBD nên map vào đâu trên Coverage?

Dùng extension VN VNCoreExtPrimaryCareFacility (canonical http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-primary-care-facility) chứa Reference đến Organization của cơ sở ĐKKCB ban đầu ghi trên thẻ BHYT. Không dùng Coverage.network — element này theo spec FHIR R4 đại diện cho identifier mạng lưới do insurer định nghĩa, không phải mã đăng ký KCB ban đầu của hệ thống y tế Việt Nam. Lưu ý: VNCoreExtPrimaryCareFacility mang nơi ĐKKCB ban đầu trên thẻ — khác với Encounter.serviceProvider hoặc Claim.provider vốn mang cơ sở KCB của lượt khám thực tế.

13. Tham chiếu pháp lý và FHIR spec

• QĐ 130/QĐ-BYT (2023) — Chuẩn dữ liệu đầu ra phục vụ quản lý chi phí KCB BHYT. Mã VN Core: QD-130-2023. Xem legal-corpus.md.
• QĐ 4750/QĐ-BYT (2023) — Sửa đổi QĐ 130/QĐ-BYT. Mã: QD-4750-2023.
• QĐ 3176/QĐ-BYT (29/10/2024) — Sửa QĐ 4750/QĐ-BYT/QĐ 130/QĐ-BYT, chuẩn KCB hiện hành. Mã: QD-3176-2024.
• QĐ 697/QĐ-BYT (19/3/2026) — Mẫu bảng kê chi phí KCB. Mã: QD-697-2026.
• QĐ 3276/QĐ-BYT (17/10/2025) — Danh mục mã đối tượng đến KCB. Mã: QD-3276-2025.
• QĐ 4210/QĐ-BYT — Chuẩn dữ liệu đầu ra phục vụ BHXH (legacy). Mã: QD-4210-BYT.
• Luật BHYT sửa đổi: Luật 51/2024/QH15 (mã: L-51-2024, hiệu lực 01/07/2025). Lưu ý L-91-2025 là Luật BVDLCN, không phải BHYT.
• NĐ 188/2025/NĐ-CP — Hướng dẫn Luật BHYT (ban hành 01/7/2025, hiệu lực 15/8/2025).
• NĐ 164/2025/NĐ-CP — Giao dịch điện tử BHXH (29/6/2025).
• NĐ 233/2025/NĐ-CP — Cơ chế tài chính quỹ BHYT.
• TT 12/2026/TT-BTC — Trình tự, biểu mẫu giám định và quyết toán BHYT (10/02/2026).
• FHIR R4 Claim — hl7.org/fhir/R4/claim.html.
• FHIR R4 ClaimResponse — hl7.org/fhir/R4/claimresponse.html.
• FHIR R4 Coverage — hl7.org/fhir/R4/coverage.html.
• FHIR R4 ExplanationOfBenefit — hl7.org/fhir/R4/explanationofbenefit.html.
• FHIR R4 Invoice — hl7.org/fhir/R4/invoice.html.
• FHIR Shorthand reference — FSH spec.

14. Đọc tiếp