Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Registry định danh

Danh mục định danh — Identifier Registry

VN Core v0.5.0 công bố 22 NamingSystem. Mỗi hệ thống kèm system URI, cơ quan quản lý, trạng thái hiện hành/lịch sử và search parameter liên quan.

VN Core áp dụng nguyên tắc URI-first. OID hoặc URN chỉ nên dùng như cầu nối cho hệ thống cũ hoặc khi bộ mã/quy ước gốc đã có định danh lịch sử ổn định.

Trang này phục vụ nhóm tích hợp, HIS/EMR/FHIR server và QA khi cần chọn đúng system URI, phân biệt định danh quốc gia với định danh cục bộ, và rà lại trạng thái áp dụng của từng hệ định danh.

CCCD: CCCD là định danh cá nhân lõi cho công dân Việt Nam trong VN Core.
VNeID: VNeID là tài khoản định danh điện tử và kênh truy cập của ứng dụng người dân; chỉ nên dùng ở lớp ứng dụng người dân, xác thực hoặc tích hợp, không dùng song song với CCCD như một định danh người bệnh chính.

Nguyên tắc registry

Trong kiến trúc hiện tại, NamingSystem được coi là hạ tầng của liên thông quốc gia, không chỉ là chi tiết của Patient hay Organization. Registry này tuân theo các nguyên tắc sau:

• Mỗi định danh có system URI chuẩn, vai trò rõ và phạm vi áp dụng rõ;
• Trạng thái hiện hành, lịch sử và ngừng dùng được tách nghĩa để tránh lẫn định danh công dân, định danh nghiệp vụ, payer identifier và định danh cục bộ;
• Registry định danh gắn trực tiếp với search, conformance, package governance và readiness triển khai.

---

Định danh quốc gia và liên tổ chức

Định danh	NamingSystem	URI chuẩn	Cơ quan quản lý	Trạng thái	Ghi chú triển khai
CCCD	vn-cccd-ns	http://fhir.hl7.org.vn/core/sid/cccd	Bộ Công an	Hiện hành	Định danh cá nhân chính; tìm kiếm: vn-sp-patient-cccd
CMND	vn-cmnd-ns	http://fhir.hl7.org.vn/core/sid/cmnd	Bộ Công an	Lịch sử / ngừng dùng	Chỉ dùng cho dữ liệu lịch sử hoặc chuyển đổi
BHXH	vn-bhxh-ns	http://fhir.hl7.org.vn/core/sid/bhxh	BHXH Việt Nam	Hiện hành	Tìm kiếm: vn-sp-patient-bhxh
BHYT	vn-bhyt-ns	http://fhir.hl7.org.vn/core/sid/bhyt	BHXH Việt Nam	Hiện hành	Hỗ trợ 3 format song song; tìm kiếm: vn-sp-patient-bhyt, vn-sp-coverage-bhyt
GKS	vn-gks-ns	http://fhir.hl7.org.vn/core/sid/gks	UBND cấp xã/phường/đặc khu	Hiện hành	Quan trọng cho trẻ em và luồng không dùng CCCD; tìm kiếm: vn-sp-patient-gks
Hộ chiếu	vn-passport-ns	http://fhir.hl7.org.vn/core/sid/passport	Bộ Công an / cơ quan cấp hộ chiếu hợp pháp	Hiện hành	Dùng cho người nước ngoài hoặc định danh thay thế hợp lệ
VNeID	vn-vneid-ns	http://fhir.hl7.org.vn/core/sid/vneid	Bộ Công an	Integration-only / retired	Chỉ giữ cho lớp tích hợp ứng dụng người dân; không dùng như định danh bệnh nhân lõi song song với CCCD
GPHN	vn-gphn-ns	http://fhir.hl7.org.vn/core/sid/gphn	Bộ Y tế / cơ quan cấp phép	Hiện hành	Tìm kiếm: vn-sp-practitioner-gphn
CCHN	vn-cchn-ns	http://fhir.hl7.org.vn/core/sid/cchn	Bộ Y tế	Lịch sử	Chỉ giữ cho liên thông hồ sơ cũ; tìm kiếm: vn-sp-practitioner-cchn
CSKCB	vn-ma-cskcb-ns	http://fhir.hl7.org.vn/core/sid/ma-cskcb	BHXH Việt Nam	Hiện hành	Tìm kiếm: vn-sp-organization-cskcb
Cổng gdbhyt	vn-gdbhyt-portal-ns	https://gdbhyt.baohiemxahoi.gov.vn	BHXH Việt Nam	Hiện hành trong v0.5	Dùng cho VNCoreEndpointBHYT và Organization.endpoint; không dùng như identifier hồ sơ
MA_LK	vn-ma-lk-ns	http://fhir.hl7.org.vn/core/sid/ma-lk	Cơ sở KCB / lớp liên thông hồ sơ BHYT	Hiện hành	Tìm kiếm: vn-sp-claim-ma-lk
XML1_ID / mã phản hồi gateway BHYT	vn-bhyt-gateway-response-id-ns	http://fhir.hl7.org.vn/core/sid/bhyt-gateway-response-id	Cổng tiếp nhận dữ liệu BHYT	Hiện hành trong lớp BHYT Submission	Dùng cho ClaimResponse.identifier[gatewayResponseId]; không thay thế MA_LK; tìm kiếm: vn-sp-claim-response-xml1-id
MA_LUOT_KCB	vn-ma-luot-kcb-ns	http://fhir.hl7.org.vn/core/sid/ma-luot-kcb	Cơ sở KCB	Hiện hành	Tìm kiếm: vn-sp-encounter-ma-luot-kcb

---

Định danh cục bộ theo cơ sở hoặc hệ thống

Định danh	NamingSystem	URI chuẩn	Phạm vi	Trạng thái	Ghi chú triển khai
MRN	vn-mrn-ns	http://fhir.hl7.org.vn/core/sid/mrn	Từng cơ sở y tế	Hiện hành	Không dùng như định danh gốc liên tổ chức
Mã tổ chức nội bộ	vn-organization-local-id-ns	http://fhir.hl7.org.vn/core/sid/organization-local-id	Từng tổ chức	Hiện hành	Không thay thế CSKCB
Mã địa điểm nội bộ	vn-location-local-id-ns	http://fhir.hl7.org.vn/core/sid/location-local-id	Từng tổ chức	Hiện hành	Dùng cho Location.identifier
Mã tài liệu nội bộ	vn-document-number-ns	http://fhir.hl7.org.vn/core/sid/document-number	Từng tổ chức	Hiện hành	Dùng cho Composition.identifier, DocumentReference.identifier
Mã specimen nội bộ	vn-specimen-local-id-ns	http://fhir.hl7.org.vn/core/sid/specimen-local-id	Từng tổ chức	Hiện hành	Dùng cho accession number của LIS/HIS
Số accession CĐHA	vn-imaging-accession-number-ns	http://fhir.hl7.org.vn/core/sid/imaging-accession-number	Từng RIS/PACS/HIS	Hiện hành từ v0.4	Dùng cho ImagingStudy.identifier để đối soát chỉ định, thực hiện và lưu trữ hình ảnh
Mã vật tư/thiết bị y tế	vn-medical-device-item-code-ns	http://fhir.hl7.org.vn/core/sid/medical-device-item-code	Nghiệp vụ nội bộ / BHYT	Hiện hành	Dùng cho Device.identifier[medicalDeviceItemCode] trong ngữ cảnh legacy/BHYT; dòng chi phí ưu tiên Claim.item.productOrService
Số lưu hành thiết bị y tế	vn-medical-device-registration-number-ns	http://fhir.hl7.org.vn/core/sid/medical-device-registration-number	Bộ Y tế / Cục Hạ tầng và Thiết bị y tế	Hiện hành từ v0.5	Định danh regulatory ở mức sản phẩm/model; không thay UDI, serial number hoặc MA_VAT_TU

---

Định danh Device, CĐHA, khoa/phòng và gateway v0.4-v0.5

Các identifier dưới đây được dùng bởi các profile bổ sung từ v0.4 đến v0.5.0. Một số là slice trên Identifier, một số là vị trí FHIR base, endpoint URL hoặc CodeSystem dùng như Identifier.system.

Tên	System URI	Nguồn	Ghi chú
Mã VTYT/TBYT (MA_VAT_TU)	http://fhir.hl7.org.vn/core/sid/medical-device-item-code	BHXH/BYT, dữ liệu đầu ra KCB	Mã vật tư/thiết bị y tế trong XML đầu ra KCB; dùng cho slice medicalDeviceItemCode của VNCoreDevice.identifier khi cần trace legacy, không dùng thay UDI
Số lưu hành TBYT	http://fhir.hl7.org.vn/core/sid/medical-device-registration-number	NĐ 98/2021/NĐ-CP, NĐ 07/2023/NĐ-CP, NĐ 04/2025/NĐ-CP và cơ quan quản lý thiết bị y tế	Bổ sung trong v0.5.0 cho VNCoreExtDeviceRegistrationNumber; định danh regulatory ở mức sản phẩm/model, không phải instance identifier
UDI Device Identifier	FHIR base Device.udiCarrier.deviceIdentifier; search bằng core parameter udi-di	IMDRF/GS1/HIBCC	Best practice quốc tế; không tạo local NamingSystem khi FHIR base đã có vị trí chuẩn
Mã danh pháp thiết bị y tế	Không phải Identifier.system trong Core; VNMedicalDeviceNomenclatureCS thuộc package .device theo ADR-0011	QĐ 3107/QĐ-BYT, QĐ 847/QĐ-BYT	Dùng cho Device.type/DeviceDefinition.type trong package .device với binding preferred; không dùng thay UDI, MA_VAT_TU, số lưu hành hoặc mã tài sản
Số accession CĐHA	http://fhir.hl7.org.vn/core/sid/imaging-accession-number	Cơ sở vận hành RIS/PACS/HIS	Dùng cho VNCoreImagingStudy.identifier để nối chỉ định, kết quả, hình ảnh và lưu trữ PACS
Mã khoa K01-K53, K99	http://fhir.hl7.org.vn/core/CodeSystem/vn-department-cs	QĐ 2010/QĐ-BYT ngày 19/06/2025 Phụ lục 6	Dùng cho VNCoreOrganizationDepartment.identifier[departmentCode]
Endpoint cổng gdbhyt	https://gdbhyt.baohiemxahoi.gov.vn	NĐ 164/2025/NĐ-CP và quy định giao dịch điện tử BHXH/BHYT	Bổ sung trong v0.5.0 cho VNCoreEndpointBHYT; đây là endpoint/gateway address, không phải mã hồ sơ

---

Cách dùng registry này

Khi nào dùng URI của VN Core

Dùng system URI của VN Core khi:

• Cần định danh rõ một loại identifier trong resource FHIR.
• Cần ánh xạ từ HIS/XML lịch sử sang FHIR.
• Cần xây chỉ mục tìm kiếm rõ ràng theo loại định danh.
• Cần phân biệt định danh hiện hành với định danh lịch sử.

Khi nào không nên dùng định danh cục bộ để liên thông rộng

Không nên dùng MRN, organization-local-id, location-local-id, specimen-local-id, hoặc document-number như định danh master liên tổ chức nếu chưa có thỏa thuận liên thông rõ.

Quy tắc chọn định danh ưu tiên

Ngữ cảnh	Ưu tiên khuyến nghị
Bệnh nhân công dân Việt Nam	CCCD
Bệnh nhân trẻ nhỏ / chưa có CCCD	GKS và/hoặc BHXH/BHYT
Bệnh nhân người nước ngoài	Hộ chiếu + citizenship phù hợp
Người hành nghề hiện hành	GPHN
Người hành nghề dữ liệu lịch sử	CCHN như cầu nối
Tổ chức KCB cho BHYT	CSKCB
Endpoint cổng gửi/tra cứu BHYT	gdbhyt portal URI trên Endpoint.address
Đợt gửi hồ sơ thanh toán BHYT	MA_LK
Lượt khám cụ thể	MA_LUOT_KCB
Thiết bị y tế loại B/C/D theo regulatory context	Số lưu hành thiết bị y tế

---

Ánh xạ URI và OID

Nguyên tắc canonical

VN Core áp dụng các nguyên tắc sau ở lớp canonical:

• Không phục dựng URI hoặc OID cũ nếu chúng không còn phù hợp với canonical discipline hiện tại;
• Không để một loại identifier mang nhiều ngữ nghĩa tùy bối cảnh;
• Không trộn canonical của định danh công dân, định danh payer, định danh tổ chức và định danh cục bộ.

Nguyên tắc chung

URI-first

VN Core ưu tiên URI làm định danh chuẩn cho:

• NamingSystem
• Identifier.system
• CodeSystem.url
• ValueSet.url

Điều này giúp:

• Nhất quán với FHIR tooling hiện nay
• Dễ triển khai hơn cho HIS vendor
• Tránh phải phát minh thêm OID không thật sự cần thiết

OID chỉ là cầu nối khi có lý do rõ ràng

OID hoặc urn:oid: chỉ nên được dùng khi:

• Bộ mã gốc quốc tế đã có OID ổn định
• Hệ thống legacy hoặc hồ sơ cũ đang dùng OID
• Cần bridge với tài liệu/bảng mã không thể đổi ngay

VN Core không đặt mục tiêu gán OID cho mọi định danh Việt Nam.

Không tự tạo OID chỉ để "giống JP Core"

JP Core có nhiều bối cảnh liên thông lịch sử đã dùng OID từ lâu. Việt Nam không nên sao chép máy móc mô hình đó.

Đối với phần lớn định danh Việt Nam như CCCD, BHYT, BHXH, GPHN, GKS, MA_LK, MA_LUOT_KCB, URI của VN Core là định danh chuẩn được ưu tiên.

Ánh xạ khuyến nghị cho định danh Việt Nam

Miền	Chuẩn VN Core nên dùng	OID/URN legacy	Khuyến nghị
CCCD	http://fhir.hl7.org.vn/core/sid/cccd	Không công bố OID trong VN Core	Dùng URI của VN Core
CMND	http://fhir.hl7.org.vn/core/sid/cmnd	Không công bố OID trong VN Core	Chỉ dùng cho cầu nối dữ liệu lịch sử
BHXH	http://fhir.hl7.org.vn/core/sid/bhxh	Không công bố OID trong VN Core	Dùng URI của VN Core
BHYT	http://fhir.hl7.org.vn/core/sid/bhyt	Không công bố OID trong VN Core	Dùng URI của VN Core
GKS	http://fhir.hl7.org.vn/core/sid/gks	Không công bố OID trong VN Core	Dùng URI của VN Core
Hộ chiếu	http://fhir.hl7.org.vn/core/sid/passport	Không công bố OID trong VN Core	Dùng URI của VN Core
GPHN	http://fhir.hl7.org.vn/core/sid/gphn	Không công bố OID trong VN Core	Dùng URI của VN Core
CCHN	http://fhir.hl7.org.vn/core/sid/cchn	Không công bố OID trong VN Core	Chỉ dùng cho dữ liệu lịch sử
CSKCB	http://fhir.hl7.org.vn/core/sid/ma-cskcb	Không công bố OID trong VN Core	Dùng URI của VN Core
Cổng gdbhyt	https://gdbhyt.baohiemxahoi.gov.vn	Không công bố OID trong VN Core	Dùng URL endpoint chính thức cho Endpoint.address
MA_LK	http://fhir.hl7.org.vn/core/sid/ma-lk	Không công bố OID trong VN Core	Dùng URI của VN Core
XML1_ID / mã phản hồi gateway BHYT	http://fhir.hl7.org.vn/core/sid/bhyt-gateway-response-id	Không công bố OID trong VN Core	Chỉ dùng cho phản hồi tiếp nhận/giám định; không thay MA_LK
MA_LUOT_KCB	http://fhir.hl7.org.vn/core/sid/ma-luot-kcb	Không công bố OID trong VN Core	Dùng URI của VN Core
Số accession CĐHA	http://fhir.hl7.org.vn/core/sid/imaging-accession-number	Không công bố OID trong VN Core	Dùng cho accession number theo cơ sở/hệ RIS/PACS
Số lưu hành TBYT	http://fhir.hl7.org.vn/core/sid/medical-device-registration-number	Không công bố OID trong VN Core	Dùng cho regulatory identifier ở mức sản phẩm/model

Ánh xạ khuyến nghị cho bộ mã quốc tế hoặc lịch sử

Miền	Canonical khuyến nghị	OID legacy hay gặp	Ghi chú
ICD-10	http://hl7.org/fhir/sid/icd-10 hoặc CodeSystem chính thức đang dùng trong VN Core	2.16.840.1.113883.6.3	OID tồn tại hợp lệ, nhưng URI/canonical vẫn là lớp chính trong FHIR
LOINC	http://loinc.org	2.16.840.1.113883.6.1	Ưu tiên URI
SNOMED CT	http://snomed.info/sct	2.16.840.1.113883.6.96	Ưu tiên URI
ISO 3166 country code	official FHIR/THO canonical	tùy bối cảnh legacy	Không nên tự tạo local OID mapping nếu không có lý do rõ

Mapping từ gateway/XML layer sang FHIR

Với field định danh trong XML hoặc payload cũ

Khuyến nghị:

• Giữ nguyên value nếu giá trị gốc còn hợp lệ
• Map sang Identifier.system bằng URI của NamingSystem tương ứng
• Chỉ thêm alias OID/URN ở integration adapter nếu hệ thống ngoài FHIR vẫn cần

Ví dụ:

Field legacy	FHIR target
SO_CCCD	Identifier.system = http://fhir.hl7.org.vn/core/sid/cccd
MA_LK	Identifier.system = http://fhir.hl7.org.vn/core/sid/ma-lk
XML1_ID	ClaimResponse.identifier.system = http://fhir.hl7.org.vn/core/sid/bhyt-gateway-response-id
MA_LUOT_KCB	Identifier.system = http://fhir.hl7.org.vn/core/sid/ma-luot-kcb
số thẻ BHYT	Identifier.system = http://fhir.hl7.org.vn/core/sid/bhyt
số accession CĐHA	ImagingStudy.identifier.system = http://fhir.hl7.org.vn/core/sid/imaging-accession-number
số lưu hành TBYT	Device.identifier.system = http://fhir.hl7.org.vn/core/sid/medical-device-registration-number
cổng gửi BHYT	Endpoint.address = https://gdbhyt.baohiemxahoi.gov.vn

Với bộ mã có OID gốc

Nếu hệ thống cũ lưu OID cho ICD-10/LOINC/SNOMED CT:

• Adapter MAY chuyển đổi về canonical URI trước khi xuất FHIR
• Resource FHIR nên dùng canonical URI/coding system chuẩn
• OID chỉ nên giữ ở lớp mapping hoặc audit log nếu cần traceability

Những gì không nên làm

• Không tạo OID nội bộ mới cho mọi bộ mã hoặc định danh Việt Nam.
• Không để cùng một loại định danh xuất hiện lúc thì dùng URI, lúc thì dùng OID, mà không có policy mapping rõ.
• Không coi OID là lớp định danh chính trong artifact FHIR mới.

---

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

Nếu cần	Nên đọc tiếp
Hiểu hành vi tìm kiếm theo token cho các identifier	Hành vi tìm kiếm
Xem quy tắc định danh và luồng không dùng CCCD	Hướng dẫn chung
Nắm quy tắc gói phát hành và mức độ tuân thủ	Ổn định và tuân thủ

---

English Summary

This page is the published identifier registry for VN Core v0.5.0 NamingSystems. It shows which identifier URI to use, who governs it, and how it relates to search and interoperability. The v0.5 update adds BHYT gateway endpoint, imaging accession, and medical device registration identifiers. VN Core remains URI-first; OID/URN aliases are only historical bridges.