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 - Local Development build (v0.9.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Hướng dẫn tích hợp cho chuỗi kê đơn → (liên thông đơn thuốc quốc gia) → cấp phát → (sử dụng) → thanh toán BHYT. Trang minh họa phương án gửi bằng Bundle.type = transaction khi CapabilityStatement áp dụng cho máy chủ công bố hỗ trợ transaction.
Cùng bộ playbook: Ngoại trú · Cấp cứu · Nội trú.
Điểm khác biệt VN cốt lõi: đơn thuốc điện tử liên thông Hệ thống đơn thuốc quốc gia (mỗi đơn có mã đơn quốc gia); mã thuốc theo ATC + số đăng ký lưu hành + DM thuốc BHYT; phân biệt hóa dược (TT 26/2025/TT-BYT) vs YHCT (TT 27/2025/TT-BYT); cấp phát nội trú (khoa Dược) vs ngoại trú/nhà thuốc bán lẻ.
Ca minh họa tổng hợp: Nguyễn Văn An (tăng huyết áp) được kê Amlodipine 5mg × 30 viên, cấp phát BHYT 80% tại BV Chợ Rẫy ngày 22/3/2026. Tất cả Example Instance là dữ liệu tổng hợp, không phải hồ sơ người bệnh thật.
Kê đơn → liên thông đơn quốc gia → cấp phát → (nội trú: sử dụng) → chi phí thuốc trong Claim. Áp dụng cho ngoại trú/cấp cứu/nội trú và nhà thuốc bán lẻ.
Bác sĩ kê đơn (HIS/EMR), Hệ thống đơn thuốc quốc gia (liên thông), khoa Dược/nhà thuốc (cấp phát), điều dưỡng (sử dụng nội trú), cổng BHXH.
TT 26/2025/TT-BYT (kê đơn hóa dược ngoại trú, hiệu lực 01/7/2025; Điều 12 liên thông đơn quốc gia + lĩnh thuốc trong 05 ngày); TT 27/2025/TT-BYT (thuốc dược liệu/YHCT BHYT); Luật Dược 105/2016 + Luật 44/2024/QH15; NĐ 163/2025/NĐ-CP; QĐ 3176/QĐ-BYT (MA_THUOC, SO_DANG_KY, NGAY_CAP, NGAY_TH_YL); QĐ 697/QĐ-BYT (chi phí thuốc).
| # | Resource | Profile | Ghi chú VN | |—|—|—|—| | P1 | Bệnh nhân | VNCorePatient | CCCD là định danh cốt lõi; VNeID chỉ dùng cho xác thực/tích hợp | | P2 | Bác sĩ kê đơn | VNCorePractitioner | GPHN hiện hành; CCHN chỉ dùng cho dữ liệu lịch sử | | P3 | Cơ sở/nhà thuốc | VNCoreOrganization | mã cơ sở/nhà thuốc | | P4 | Thẻ BHYT (nếu có) | VNCoreCoverage | mức hưởng | | P5 | Danh mục thuốc | VNCoreMedication | ATC + số ĐKLH + mã thuốc BHYT |
Khi máy chủ công bố hỗ trợ transaction, có thể gửi chuỗi kê đơn → cấp phát bằng transaction Bundle để áp dụng atomic. Ví dụ tổng hợp: Bundle-ExampleBundlePharmacyDispenseTransaction (Patient, Coverage, Encounter, MedicationRequest, MedicationDispense — PUT update-as-create). Hệ thống MAY dùng tương tác khác nếu CapabilityStatement và hợp đồng tích hợp cho phép. Đơn thuốc điện tử trọn bộ: ExampleBundleEPrescription. Chi tiết pattern xem Playbook Nội trú §5.
MedicationRequest(kê đơn) ──▶ [Liên thông Hệ thống đơn thuốc quốc gia: gán mã đơn]
│ identifier (mã đơn quốc gia), requester (GPHN hiện hành), medicationCodeableConcept (ATC + mã BHYT)
▼
MedicationDispense(cấp phát) ── authorizingPrescription ─▶ (lại) MedicationRequest
│ whenHandedOver (NGAY_CAP), quantity, performer (dược sĩ/khoa/nhà thuốc)
▼
(nội trú) MedicationAdministration(sử dụng) ── request ─▶ MedicationRequest
▼
(BHYT) Claim.item.category = "thuốc" ─▶ ClaimResponse/EOB
| # | Bước | Profile | Element chính | Example |
|—|—|—|—|—|
| 1 | Thuốc (danh mục) | VNCoreMedication | code (ATC + số ĐKLH + mã BHYT), dạng bào chế | Amlodipine |
| 2 | Kê đơn | VNCoreMedicationRequest | medicationCodeableConcept, dosageInstruction, requester (Practitioner/PractitionerRole có GPHN hiện hành), intent=order | Hypertension · YHCT: YHCT |
| 3 | Mã đơn quốc gia | MedicationRequest.identifier | system = http://fhir.hl7.org.vn/core/sid/don-thuoc-quoc-gia (14 ký tự — VNPrescriptionCode NamingSystem) | QĐ 808/QĐ-BYT |
| 4 | Cấp phát | VNCoreMedicationDispense | authorizingPrescription→MedicationRequest, whenHandedOver, quantity, performer.actor | OutpatientBHYT · Nội trú |
| 5 | Sử dụng (nội trú) | VNCoreMedicationAdministration | effective[x] (NGAY_TH_YL), request→MedicationRequest | Nội trú |
| 6 | BHYT | VNCoreClaim | item.category = thuốc (QĐ 697/QĐ-BYT) | BHYTSubmission |
ATC; số đăng ký lưu hành (VD/VS/QLĐB); DM thuốc BHYT; đơn vị UCUM; đường dùng (vn-medication-route-vs); YHCT vị thuốc/bài thuốc (QĐ 2552/3080, TT 27/2025/TT-BYT).
requester là Practitioner hoặc PractitionerRole liên kết người hành nghề có GPHN hiện hành; CCHN chỉ dùng khi chuyển đổi dữ liệu lịch sử.authorizingPrescription trỏ đúng MedicationRequest — không "cấp phát mồ côi" cho cấp phát ngoại trú/bán lẻ (VN-RULE-MED-002); nội trú gắn y lệnh khi có.request khép chuỗi (VN-RULE-MED-003).quantity cấp phát ≤ số lượng kê (trừ quy tắc riêng).Ví dụ OperationOutcome — cấp phát mồ côi:
{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"required",
"details":{"coding":[{"system":"http://fhir.hl7.org.vn/core/CodeSystem/vn-validation-rule-cs","code":"VN-RULE-MED-002"}],
"text":"MedicationDispense.authorizingPrescription là bắt buộc cho cấp phát ngoại trú/bán lẻ để bảo toàn chuỗi BHYT"},
"expression":["Bundle.entry[4].resource.authorizingPrescription"]}]}
| GAP | Ảnh hưởng | Priority |
|—|—|—|
| Medication.batch (số lô/hạn dùng) | ✅ Đã đánh dấu MS trong VNCoreMedication (batch.lotNumber, batch.expirationDate) | resolved |
| System mã đơn thuốc quốc gia | ✅ Đã bổ sung VNPrescriptionCode NamingSystem (QĐ 808/QĐ-BYT) | resolved |
| MedicationStatement (tiền sử dùng thuốc) | ✅ Đã bổ sung VNCoreMedicationStatement | resolved |
✅ MedicationAdministration (sử dụng thuốc nội trú) đã có — VNCoreMedicationAdministration.
Ngoài Hệ thống đơn thuốc quốc gia, cơ sở bán lẻ thuốc — bao gồm nhà thuốc bệnh viện — phải liên thông giao dịch nhập – xuất – kiểm kê với Hệ thống cơ sở dữ liệu về dược (api.csdlduoc.com.vn/v2) theo TT 11/2025/TT-BYT (Điều 5 khoản 2, từ 01/01/2026) và đặc tả API v1.1 ban hành kèm QĐ 232/QĐ-TTYQG (thay QĐ 522/QĐ-TTYQG). VN Core không profile hóa API này (chuẩn REST/JSON riêng, không phải FHIR); thay vào đó cung cấp bộ logical model làm field catalog + bảng ánh xạ hai chiều với các profile thuốc hiện có:
| Nghiệp vụ | Logical model | Đích FHIR chủ đạo |
|---|---|---|
| Danh mục thuốc quốc gia (đồng bộ về) | VNPharmacyDrugCatalogLM | VNCoreMedication |
| Phiếu nhập hàng | VNPharmacyStockInLM | SupplyDelivery — ví dụ phiếu nhập từ nhà cung cấp |
| Phiếu xuất hàng (gồm bán lẻ) | VNPharmacyStockOutLM | VNCoreMedicationDispense (sale-retail) — ví dụ bán lẻ theo đơn điện tử; SupplyDelivery (nghiệp vụ khác) |
| Phiếu kiểm kho | VNPharmacyStockTakingLM | Không có resource R4 tương ứng (InventoryReport từ R5) |
Lưu ý triển khai: cơ sở phải khai báo phiếu nhập tồn đầu kỳ trước khi liên thông giao dịch khác; xử lý bất đồng bộ (poll trạng thái accepted/processing/completed/error/rejected); ngày giờ API theo GMT+7 không ghi offset trong khi FHIR dateTime bắt buộc offset +07:00. Bảng ánh xạ chi tiết từng trường và các gap đã ghi nhận: xem wiki mapping "Liên thông Hệ thống CSDL về dược" trong kho tri thức dự án.
| Nếu cần | Đọc tiếp | |—|—| | Sử dụng thuốc nội trú | Playbook Nội trú | | Quy ước OperationOutcome | OperationOutcome & Registry | | Danh mục định danh | Registry định danh |
Pharmacy integration playbook covering the prescribe → (national ePrescription interoperability) → dispense → administer → BHYT chain through a coherent synthetic Amlodipine scenario. It illustrates an atomic transaction Bundle (ExampleBundlePharmacyDispenseTransaction) when the applicable server CapabilityStatement advertises transaction support. Key Vietnamese specifics include the national prescription code, current GPHN-based practitioner identification, ATC/marketing-authorization/BHYT drug coding, and the distinction between conventional medicines and traditional medicines. The dispense-to-prescription link is enforced for outpatient/retail dispensing; inpatient administration is covered by VNCoreMedicationAdministration.