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

• Nội dung
• Mô tả chi tiết
• Ánh xạ
• XML
• JSON
• TTL

Mô hình logic: Bản tin đồng bộ hồ sơ sức khỏe BHXH → CSDL sức khỏe BYT (resource-sync) — Logical Model (Phụ lục 03)

Logical model cho bản tin (envelope) đồng bộ tập dữ liệu hồ sơ sức khỏe từ Bảo hiểm xã hội Việt Nam (bên phát tin, ví dụ sender_id = G12/VSS) về Cơ sở dữ liệu sức khỏe cá nhân của Bộ Y tế qua Trục dữ liệu Bộ Y tế (api.emrhub.vn). API: POST /api/platform/resource-sync/push. Xác thực: OAuth2 + Bearer Token (lấy từ /api/auth/login, role=department). Định dạng JSON (UTF-8). service-type=100. Payload XML tuân theo mẫu QĐ 3176/QĐ-BYT (GIAMDINHHS). KHÁC với luồng BHYT Gateway thanh toán (gdbhyt.baohiemxahoi.gov.vn, XML 4210) — đây là surface đồng bộ hồ sơ sức khỏe BHXH → CSDL sức khỏe cá nhân. INFORMATIVE / non-normative: mô hình ánh xạ transport envelope resource-sync (không phải FHIR resource normative) — mapping aid cho implementer. Căn cứ: QĐ 2062/QĐ-BYT (07/7/2026) Phụ lục 03 (Phương án đồng bộ dữ liệu từ BHXH Việt Nam) — THAY Phụ lục 03 QĐ 1551/QĐ-BYT (31/5/2026); đọc hợp nhất. API OAuth2 + Bearer, POST /api/platform/resource-sync/push (service-type=100, txn_type=sync_ehr, msg_type=101/102), checksum RSASHA256.

Usages:

• This Logical Model is not used by any profiles in this Specification

You can also check for usages in the FHIR IG Statistics

Các dạng xem hình thức của nội dung hồ sơ

Mô tả profile, differential, snapshot và các biểu diễn liên quan.

• Bảng Differential
• Bảng Snapshot
• Thống kê/Tham chiếu
• Tất cả

Name	Flags	Card.	Type	Description & Constraints    Filter: Bindings Constraints Obligations
vnHealthCheckupG12EnvelopeLm		0..*	Base	Bản tin đồng bộ hồ sơ sức khỏe BHXH → CSDL sức khỏe BYT (resource-sync) — Logical Model (Phụ lục 03)
httpHeader		1..1	BackboneElement	HTTP headers của request
contentType		1..1	string	Content-Type = application/json
accept		1..1	string	Accept = */*
acceptEncoding		1..1	string	Accept-Encoding = gzip,deflate,br
authorization		1..1	string	Authorization = Bearer + Access Token (lấy từ POST /api/auth/login, role=department)
serviceType		1..1	string	service-type = 100 (Dịch vụ data sync vào Trục dữ liệu Bộ Y tế)
header		1..1	BackboneElement	header - Thông tin header bản tin (JSON Object)
version		1..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		1..1	string	sender_id - Mã định danh bên phát tin (ví dụ: G12/VSS — BHXH Việt Nam)
receiverId		1..1	string	receiver_id - Mã bên nhận tin (ví dụ: TDLBYT)
txnType		1..1	string	txn_type - Loại giao dịch. Giá trị cố định: sync_ehr (đồng bộ tập dữ liệu hồ sơ sức khỏe theo QĐ 3176/QĐ-BYT)
msgId		1..1	string	msg_id - Mã giao dịch = sender_id + YY (2 ký tự năm) + MM (2 ký tự tháng) + DD (2 ký tự ngày) + UUIDv4 (không gạch)
msgType		1..1	string	msg_type - REQUEST cố định = 101 (thông điệp phát tin đồng bộ). Response dùng 102 (xem nhóm response bên dưới)
dataType		1..1	string	data_type - Định dạng file. Giá trị: xml/base64 (Phụ lục 03)
sendDatetime		1..1	string	send_datetime - Thời điểm đẩy dữ liệu, Unix timestamp 13 số (ms). VĂN BẢN GỐC kiểu Long; mô hình hóa string vì vượt phạm vi FHIR R4 integer 32-bit (INFORMATIVE)
data		1..1	string	data - File dữ liệu (XML hồ sơ sức khỏe mẫu GIAMDINHHS QĐ 3176/QĐ-BYT) đã encode Base64. VĂN BẢN GỐC ghi Object ở bảng request nhưng phần checksum ghi STRING BASE64 (văn bản tự mâu thuẫn) — mô hình hóa string base64. Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
signature		1..1	string	signature - Chữ ký số checksum RSASHA256 giữa header và data (bên phát tin tạo). Công thức: bỏ whitespace/newline → Uppercase(SHA256(header)) + '.' + Uppercase(SHA256(data)) → RSASHA256 bằng private key → Uppercase(base64). Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
response		0..1	BackboneElement	Bản tin phản hồi từ Trục BYT (msg_type=102)
version		0..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		0..1	string	sender_id (response) - Mã bên nhận-nay-phát (ví dụ TDLBYT)
receiverId		0..1	string	receiver_id (response) - Mã bên phát tin gốc (ví dụ G12/VSS)
txnType		0..1	string	txn_type (response) = sync_ehr
msgType		0..1	string	msg_type (response) = 102
msgId		0..1	string	msg_id (response) - Mã giao dịch phía Trục (sender_id + YY+MM+DD + UUIDv4)
refMsgId		0..1	string	ref_msg_id - msg_id của bên phát tin gốc
sendDatetime		0..1	string	send_datetime (response) - Unix timestamp 13 số
resDatetime		0..1	string	res_datetime - Ngày phản hồi (Unix timestamp 13 số)
resCode		0..1	string	res_code - Mã trạng thái tiếp nhận (CM_SUCCESS | CM_INVALID_REQUEST | PS_DS_RSA_SIGNATURE_INVALID/MISSING | PS_DS_CA_SIGNATURE_INVALID/MISSING | PS_DS_VERIFY_SUCCESS/FAIL | PS_DS_SAVE_SUCCESS/FAIL)
resMsg		0..1	string	res_msg - Diễn giải trạng thái tiếp nhận
dataState		0..1	string	data.data_state - Mã trạng thái dữ liệu sau khi về kho
dataStateMsg		0..1	string	data.data_state_msg - Chi tiết trạng thái dữ liệu (vd 'Data is received')
messageCheckCa		0..1	string	data.message_check_ca - Trạng thái kiểm tra chữ ký số bản tin
messageNotify		0..1	string	data.message_notify - Trạng thái hệ thống với bản tin (vd 'Successfully inserted data to DATA LAKE')
signature		0..1	string	signature (response) - Chữ ký RSASHA256 của bên nhận tin (Trục BYT)
Documentation for this format

Name	Flags	Card.	Type	Description & Constraints    Filter: Bindings Constraints Obligations
vnHealthCheckupG12EnvelopeLm		0..*	Base	Bản tin đồng bộ hồ sơ sức khỏe BHXH → CSDL sức khỏe BYT (resource-sync) — Logical Model (Phụ lục 03)
httpHeader		1..1	BackboneElement	HTTP headers của request
@id		0..1	string	Unique id for inter-element referencing
extension		0..*	Extension	Additional content defined by implementations Slice: Unordered, Open by value:url
modifierExtension	?!Σ	0..*	Extension	Extensions that cannot be ignored even if unrecognized
contentType		1..1	string	Content-Type = application/json
accept		1..1	string	Accept = */*
acceptEncoding		1..1	string	Accept-Encoding = gzip,deflate,br
authorization		1..1	string	Authorization = Bearer + Access Token (lấy từ POST /api/auth/login, role=department)
serviceType		1..1	string	service-type = 100 (Dịch vụ data sync vào Trục dữ liệu Bộ Y tế)
header		1..1	BackboneElement	header - Thông tin header bản tin (JSON Object)
@id		0..1	string	Unique id for inter-element referencing
extension		0..*	Extension	Additional content defined by implementations Slice: Unordered, Open by value:url
modifierExtension	?!Σ	0..*	Extension	Extensions that cannot be ignored even if unrecognized
version		1..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		1..1	string	sender_id - Mã định danh bên phát tin (ví dụ: G12/VSS — BHXH Việt Nam)
receiverId		1..1	string	receiver_id - Mã bên nhận tin (ví dụ: TDLBYT)
txnType		1..1	string	txn_type - Loại giao dịch. Giá trị cố định: sync_ehr (đồng bộ tập dữ liệu hồ sơ sức khỏe theo QĐ 3176/QĐ-BYT)
msgId		1..1	string	msg_id - Mã giao dịch = sender_id + YY (2 ký tự năm) + MM (2 ký tự tháng) + DD (2 ký tự ngày) + UUIDv4 (không gạch)
msgType		1..1	string	msg_type - REQUEST cố định = 101 (thông điệp phát tin đồng bộ). Response dùng 102 (xem nhóm response bên dưới)
dataType		1..1	string	data_type - Định dạng file. Giá trị: xml/base64 (Phụ lục 03)
sendDatetime		1..1	string	send_datetime - Thời điểm đẩy dữ liệu, Unix timestamp 13 số (ms). VĂN BẢN GỐC kiểu Long; mô hình hóa string vì vượt phạm vi FHIR R4 integer 32-bit (INFORMATIVE)
data		1..1	string	data - File dữ liệu (XML hồ sơ sức khỏe mẫu GIAMDINHHS QĐ 3176/QĐ-BYT) đã encode Base64. VĂN BẢN GỐC ghi Object ở bảng request nhưng phần checksum ghi STRING BASE64 (văn bản tự mâu thuẫn) — mô hình hóa string base64. Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
signature		1..1	string	signature - Chữ ký số checksum RSASHA256 giữa header và data (bên phát tin tạo). Công thức: bỏ whitespace/newline → Uppercase(SHA256(header)) + '.' + Uppercase(SHA256(data)) → RSASHA256 bằng private key → Uppercase(base64). Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
response		0..1	BackboneElement	Bản tin phản hồi từ Trục BYT (msg_type=102)
@id		0..1	string	Unique id for inter-element referencing
extension		0..*	Extension	Additional content defined by implementations Slice: Unordered, Open by value:url
modifierExtension	?!Σ	0..*	Extension	Extensions that cannot be ignored even if unrecognized
version		0..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		0..1	string	sender_id (response) - Mã bên nhận-nay-phát (ví dụ TDLBYT)
receiverId		0..1	string	receiver_id (response) - Mã bên phát tin gốc (ví dụ G12/VSS)
txnType		0..1	string	txn_type (response) = sync_ehr
msgType		0..1	string	msg_type (response) = 102
msgId		0..1	string	msg_id (response) - Mã giao dịch phía Trục (sender_id + YY+MM+DD + UUIDv4)
refMsgId		0..1	string	ref_msg_id - msg_id của bên phát tin gốc
sendDatetime		0..1	string	send_datetime (response) - Unix timestamp 13 số
resDatetime		0..1	string	res_datetime - Ngày phản hồi (Unix timestamp 13 số)
resCode		0..1	string	res_code - Mã trạng thái tiếp nhận (CM_SUCCESS | CM_INVALID_REQUEST | PS_DS_RSA_SIGNATURE_INVALID/MISSING | PS_DS_CA_SIGNATURE_INVALID/MISSING | PS_DS_VERIFY_SUCCESS/FAIL | PS_DS_SAVE_SUCCESS/FAIL)
resMsg		0..1	string	res_msg - Diễn giải trạng thái tiếp nhận
dataState		0..1	string	data.data_state - Mã trạng thái dữ liệu sau khi về kho
dataStateMsg		0..1	string	data.data_state_msg - Chi tiết trạng thái dữ liệu (vd 'Data is received')
messageCheckCa		0..1	string	data.message_check_ca - Trạng thái kiểm tra chữ ký số bản tin
messageNotify		0..1	string	data.message_notify - Trạng thái hệ thống với bản tin (vd 'Successfully inserted data to DATA LAKE')
signature		0..1	string	signature (response) - Chữ ký RSASHA256 của bên nhận tin (Trục BYT)
Documentation for this format

Constraints

Id	Grade	Path(s)	Description	Expression
ele-1	error	**ALL** elements	All FHIR elements must have a @value or children	hasValue() or (children().count() > id.count())
ext-1	error	**ALL** extensions	Must have either extensions or value[x], not both	extension.exists() != value.exists()

Summary

Mandatory: 0 element(17 nested mandatory elements)

Dạng xem Differential

Name	Flags	Card.	Type	Description & Constraints    Filter: Bindings Constraints Obligations
vnHealthCheckupG12EnvelopeLm		0..*	Base	Bản tin đồng bộ hồ sơ sức khỏe BHXH → CSDL sức khỏe BYT (resource-sync) — Logical Model (Phụ lục 03)
httpHeader		1..1	BackboneElement	HTTP headers của request
contentType		1..1	string	Content-Type = application/json
accept		1..1	string	Accept = */*
acceptEncoding		1..1	string	Accept-Encoding = gzip,deflate,br
authorization		1..1	string	Authorization = Bearer + Access Token (lấy từ POST /api/auth/login, role=department)
serviceType		1..1	string	service-type = 100 (Dịch vụ data sync vào Trục dữ liệu Bộ Y tế)
header		1..1	BackboneElement	header - Thông tin header bản tin (JSON Object)
version		1..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		1..1	string	sender_id - Mã định danh bên phát tin (ví dụ: G12/VSS — BHXH Việt Nam)
receiverId		1..1	string	receiver_id - Mã bên nhận tin (ví dụ: TDLBYT)
txnType		1..1	string	txn_type - Loại giao dịch. Giá trị cố định: sync_ehr (đồng bộ tập dữ liệu hồ sơ sức khỏe theo QĐ 3176/QĐ-BYT)
msgId		1..1	string	msg_id - Mã giao dịch = sender_id + YY (2 ký tự năm) + MM (2 ký tự tháng) + DD (2 ký tự ngày) + UUIDv4 (không gạch)
msgType		1..1	string	msg_type - REQUEST cố định = 101 (thông điệp phát tin đồng bộ). Response dùng 102 (xem nhóm response bên dưới)
dataType		1..1	string	data_type - Định dạng file. Giá trị: xml/base64 (Phụ lục 03)
sendDatetime		1..1	string	send_datetime - Thời điểm đẩy dữ liệu, Unix timestamp 13 số (ms). VĂN BẢN GỐC kiểu Long; mô hình hóa string vì vượt phạm vi FHIR R4 integer 32-bit (INFORMATIVE)
data		1..1	string	data - File dữ liệu (XML hồ sơ sức khỏe mẫu GIAMDINHHS QĐ 3176/QĐ-BYT) đã encode Base64. VĂN BẢN GỐC ghi Object ở bảng request nhưng phần checksum ghi STRING BASE64 (văn bản tự mâu thuẫn) — mô hình hóa string base64. Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
signature		1..1	string	signature - Chữ ký số checksum RSASHA256 giữa header và data (bên phát tin tạo). Công thức: bỏ whitespace/newline → Uppercase(SHA256(header)) + '.' + Uppercase(SHA256(data)) → RSASHA256 bằng private key → Uppercase(base64). Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
response		0..1	BackboneElement	Bản tin phản hồi từ Trục BYT (msg_type=102)
version		0..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		0..1	string	sender_id (response) - Mã bên nhận-nay-phát (ví dụ TDLBYT)
receiverId		0..1	string	receiver_id (response) - Mã bên phát tin gốc (ví dụ G12/VSS)
txnType		0..1	string	txn_type (response) = sync_ehr
msgType		0..1	string	msg_type (response) = 102
msgId		0..1	string	msg_id (response) - Mã giao dịch phía Trục (sender_id + YY+MM+DD + UUIDv4)
refMsgId		0..1	string	ref_msg_id - msg_id của bên phát tin gốc
sendDatetime		0..1	string	send_datetime (response) - Unix timestamp 13 số
resDatetime		0..1	string	res_datetime - Ngày phản hồi (Unix timestamp 13 số)
resCode		0..1	string	res_code - Mã trạng thái tiếp nhận (CM_SUCCESS | CM_INVALID_REQUEST | PS_DS_RSA_SIGNATURE_INVALID/MISSING | PS_DS_CA_SIGNATURE_INVALID/MISSING | PS_DS_VERIFY_SUCCESS/FAIL | PS_DS_SAVE_SUCCESS/FAIL)
resMsg		0..1	string	res_msg - Diễn giải trạng thái tiếp nhận
dataState		0..1	string	data.data_state - Mã trạng thái dữ liệu sau khi về kho
dataStateMsg		0..1	string	data.data_state_msg - Chi tiết trạng thái dữ liệu (vd 'Data is received')
messageCheckCa		0..1	string	data.message_check_ca - Trạng thái kiểm tra chữ ký số bản tin
messageNotify		0..1	string	data.message_notify - Trạng thái hệ thống với bản tin (vd 'Successfully inserted data to DATA LAKE')
signature		0..1	string	signature (response) - Chữ ký RSASHA256 của bên nhận tin (Trục BYT)
Documentation for this format

Dạng xem SnapshotView

Name	Flags	Card.	Type	Description & Constraints    Filter: Bindings Constraints Obligations
vnHealthCheckupG12EnvelopeLm		0..*	Base	Bản tin đồng bộ hồ sơ sức khỏe BHXH → CSDL sức khỏe BYT (resource-sync) — Logical Model (Phụ lục 03)
httpHeader		1..1	BackboneElement	HTTP headers của request
@id		0..1	string	Unique id for inter-element referencing
extension		0..*	Extension	Additional content defined by implementations Slice: Unordered, Open by value:url
modifierExtension	?!Σ	0..*	Extension	Extensions that cannot be ignored even if unrecognized
contentType		1..1	string	Content-Type = application/json
accept		1..1	string	Accept = */*
acceptEncoding		1..1	string	Accept-Encoding = gzip,deflate,br
authorization		1..1	string	Authorization = Bearer + Access Token (lấy từ POST /api/auth/login, role=department)
serviceType		1..1	string	service-type = 100 (Dịch vụ data sync vào Trục dữ liệu Bộ Y tế)
header		1..1	BackboneElement	header - Thông tin header bản tin (JSON Object)
@id		0..1	string	Unique id for inter-element referencing
extension		0..*	Extension	Additional content defined by implementations Slice: Unordered, Open by value:url
modifierExtension	?!Σ	0..*	Extension	Extensions that cannot be ignored even if unrecognized
version		1..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		1..1	string	sender_id - Mã định danh bên phát tin (ví dụ: G12/VSS — BHXH Việt Nam)
receiverId		1..1	string	receiver_id - Mã bên nhận tin (ví dụ: TDLBYT)
txnType		1..1	string	txn_type - Loại giao dịch. Giá trị cố định: sync_ehr (đồng bộ tập dữ liệu hồ sơ sức khỏe theo QĐ 3176/QĐ-BYT)
msgId		1..1	string	msg_id - Mã giao dịch = sender_id + YY (2 ký tự năm) + MM (2 ký tự tháng) + DD (2 ký tự ngày) + UUIDv4 (không gạch)
msgType		1..1	string	msg_type - REQUEST cố định = 101 (thông điệp phát tin đồng bộ). Response dùng 102 (xem nhóm response bên dưới)
dataType		1..1	string	data_type - Định dạng file. Giá trị: xml/base64 (Phụ lục 03)
sendDatetime		1..1	string	send_datetime - Thời điểm đẩy dữ liệu, Unix timestamp 13 số (ms). VĂN BẢN GỐC kiểu Long; mô hình hóa string vì vượt phạm vi FHIR R4 integer 32-bit (INFORMATIVE)
data		1..1	string	data - File dữ liệu (XML hồ sơ sức khỏe mẫu GIAMDINHHS QĐ 3176/QĐ-BYT) đã encode Base64. VĂN BẢN GỐC ghi Object ở bảng request nhưng phần checksum ghi STRING BASE64 (văn bản tự mâu thuẫn) — mô hình hóa string base64. Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
signature		1..1	string	signature - Chữ ký số checksum RSASHA256 giữa header và data (bên phát tin tạo). Công thức: bỏ whitespace/newline → Uppercase(SHA256(header)) + '.' + Uppercase(SHA256(data)) → RSASHA256 bằng private key → Uppercase(base64). Bắt buộc trong thực tế dù bảng gốc không đánh dấu 'x'
response		0..1	BackboneElement	Bản tin phản hồi từ Trục BYT (msg_type=102)
@id		0..1	string	Unique id for inter-element referencing
extension		0..*	Extension	Additional content defined by implementations Slice: Unordered, Open by value:url
modifierExtension	?!Σ	0..*	Extension	Extensions that cannot be ignored even if unrecognized
version		0..1	string	version - Phiên bản hệ thống Trục dữ liệu BYT
senderId		0..1	string	sender_id (response) - Mã bên nhận-nay-phát (ví dụ TDLBYT)
receiverId		0..1	string	receiver_id (response) - Mã bên phát tin gốc (ví dụ G12/VSS)
txnType		0..1	string	txn_type (response) = sync_ehr
msgType		0..1	string	msg_type (response) = 102
msgId		0..1	string	msg_id (response) - Mã giao dịch phía Trục (sender_id + YY+MM+DD + UUIDv4)
refMsgId		0..1	string	ref_msg_id - msg_id của bên phát tin gốc
sendDatetime		0..1	string	send_datetime (response) - Unix timestamp 13 số
resDatetime		0..1	string	res_datetime - Ngày phản hồi (Unix timestamp 13 số)
resCode		0..1	string	res_code - Mã trạng thái tiếp nhận (CM_SUCCESS | CM_INVALID_REQUEST | PS_DS_RSA_SIGNATURE_INVALID/MISSING | PS_DS_CA_SIGNATURE_INVALID/MISSING | PS_DS_VERIFY_SUCCESS/FAIL | PS_DS_SAVE_SUCCESS/FAIL)
resMsg		0..1	string	res_msg - Diễn giải trạng thái tiếp nhận
dataState		0..1	string	data.data_state - Mã trạng thái dữ liệu sau khi về kho
dataStateMsg		0..1	string	data.data_state_msg - Chi tiết trạng thái dữ liệu (vd 'Data is received')
messageCheckCa		0..1	string	data.message_check_ca - Trạng thái kiểm tra chữ ký số bản tin
messageNotify		0..1	string	data.message_notify - Trạng thái hệ thống với bản tin (vd 'Successfully inserted data to DATA LAKE')
signature		0..1	string	signature (response) - Chữ ký RSASHA256 của bên nhận tin (Trục BYT)
Documentation for this format

Constraints

Id	Grade	Path(s)	Description	Expression
ele-1	error	**ALL** elements	All FHIR elements must have a @value or children	hasValue() or (children().count() > id.count())
ext-1	error	**ALL** extensions	Must have either extensions or value[x], not both	extension.exists() != value.exists()

Summary

Mandatory: 0 element(17 nested mandatory elements)

Biểu diễn khác của hồ sơ: CSV, Excel