VN Core BHYT Gateway Server CapabilityStatement

HL7 Vietnam VN Core FHIR Implementation Guide

Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide
0.10.0 - Draft for Community Review Viet Nam cờ

Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.10.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

CapabilityStatement: VN Core BHYT Gateway Server CapabilityStatement — Yêu cầu tuân thủ tối thiểu cho máy chủ cổng BHYT (Thử nghiệm)

URL chính thức: http://fhir.hl7.org.vn/core/CapabilityStatement/vn-core-bhyt-gateway-server	Phiên bản: 0.10.0	Làm nổi bật phần thay đổi?
		Computable Name: VNBHYTGatewayServerCapabilityStatement
Định danh khác: OID:2.25.161089673617632664299011809196868855799.13.2

Yêu cầu tuân thủ tối thiểu theo từng vai trò triển khai dành cho máy chủ/facade tiếp nhận hồ sơ thanh toán BHYT từ HIS/EMR. Tập trung vào lớp liên thông hồ sơ BHYT, MA_LK, các operation kiểm tra hợp lệ/gửi/thu hồi và các quy tắc định dạng xuất cổng. / Minimum conformance requirements for payer-facing BHYT submission servers. THỜI HẠN GỬI DỮ LIỆU (TT 48/2017/TT-BYT): dữ liệu KCB gửi NGAY sau khi kết thúc lần khám/đợt điều trị (Điều 6); dữ liệu đề nghị thanh toán trong 07 ngày làm việc, dữ liệu cuối tháng/quý/năm trước ngày 05 tháng kế tiếp (Điều 7; TT 12/2026/TT-BTC Điều 9.1 dẫn chiếu). Mốc 24 giờ hiển thị VNeID là SLA downstream của BHXH (QĐ 2733/QĐ-BYT), không phải thời hạn gửi của CSKCB.

Raw OpenAPI-Swagger Definition file | Tải xuống

Language: vi

Implementation Guide Version: 0.10.0
FHIR Version: 4.0.1
Supported Formats: json, xml
Published on: 2026-03-23
Published by: Omi HealthTech / VN Core FHIR Community Initiative

Note to Implementers: FHIR Capabilities
Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.

FHIR RESTful Capabilities

Mode: `server`

Máy chủ cổng/facade nên công bố rõ khả năng kiểm tra hợp lệ hồ sơ, nhận VNCoreBHYTSubmissionBundle, truy vết theo MA_LK và phản hồi lỗi bằng OperationOutcome.

Security

Enable CORS: no

Security services supported: SMART-on-FHIR

Khuyến nghị token máy chủ - máy chủ, danh sách IP cho phép hoặc mTLS theo quy định vận hành, ghi log đầy đủ truy cập và quá trình tiếp nhận hồ sơ BHYT.

Capabilities by Resource/Profile

Summary

The summary table lists the resources that are part of this configuration, and for each resource it lists:

The relevant profiles (if any)
The interactions supported by each resource (Read, Search, Update, and Create, are always shown, while VRead, Patch, Delete, History on Instance, or History on Type are only present if at least one of the resources has support for them.
The required, recommended, and some optional search parameters (if any).
The linked resources enabled for _include
The other resources enabled for _revinclude
The operations on the resource (if any)

Resource Type	Profile	R	V-R	S	C	Searches	`_include`	`_revinclude`	Operations
Bundle	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-bhyt-submission-bundle	Y			Y	identifier			`$validate-bhyt-claim`, `$submit-bhyt-claim`
Claim	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-claim	Y	Y	Y	Y	identifier, vn-ma-lk	`Claim:patient`, `Claim:insurer`, `Claim:provider`		`$reverse-bhyt-claim`
Coverage	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-coverage	Y	Y	Y		vn-ma-dkbd	`Coverage:beneficiary`, `Coverage:payor`
CoverageEligibilityRequest	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-coverage-eligibility-request	Y	Y		Y	identifier
CoverageEligibilityResponse	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-coverage-eligibility-response	Y	Y	Y			`CoverageEligibilityResponse:request`
ClaimResponse	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-claim-response	Y	Y	Y		request, status, vn-xml1-id	`ClaimResponse:patient`, `ClaimResponse:request`
Patient	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-patient	Y	Y	Y		vn-cccd		`Coverage:beneficiary`
PaymentReconciliation	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-payment-reconciliation	Y	Y	Y		created, status
Account	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-account	Y	Y	Y		patient
Task	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-claim-appeal-task	Y	Y	Y	Y	status, identifier
Organization	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-organization Additional supported profiles: Khoa/Phòng VN Core — VN Core Organization Department Profile	Y	Y	Y
Endpoint	http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-endpoint-bhyt	Y	Y	Y

Resource Conformance: unspecifiedBundle

Base System Profile
Bundle hồ sơ thanh toán BHYT — VN Core BHYT Submission Bundle

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support read.
SHOULD support create.

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	identifier	`token`

Extended Operations

Conformance	Operation	Documentation
SHOULD	$validate-bhyt-claim	Validate hồ sơ theo profile và quy tắc của lớp liên thông hồ sơ BHYT (POST Bundle/$validate-bhyt-claim)
SHOULD	$submit-bhyt-claim	Tiếp nhận hồ sơ thanh toán BHYT theo `VNCoreBHYTSubmissionBundle` (POST Bundle/$submit-bhyt-claim)

Resource Conformance: unspecifiedClaim

Base System Profile
Yêu cầu thanh toán KCB VN Core — VN Core Claim Profile

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support read, search-type.
SHOULD support create, vread.

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	identifier	`token`
SHOULD	vn-ma-lk	`token`

Extended Operations

Conformance	Operation	Documentation
SHOULD	$reverse-bhyt-claim	Thu hồi hoặc huỷ hồ sơ đã gửi (Claim/$reverse-bhyt-claim hoặc Claim/[id]/$reverse-bhyt-claim)

Resource Conformance: unspecifiedCoverage

Base System Profile
Thẻ BHYT VN Core — VN Core Coverage Profile

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support read, search-type.
SHOULD support vread.

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	vn-ma-dkbd	`token`

Resource Conformance: unspecifiedCoverageEligibilityRequest

Base System Profile
Yêu cầu tra cứu quyền lợi BHYT VN Core — VN Core Coverage Eligibility Request Profile

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support create, read.
SHOULD support vread.

Documentation

Tra cứu hiệu lực/quyền lợi thẻ BHYT tại tiếp đón (NĐ 164/2025/NĐ-CP)

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	identifier	`token`	Tiêu chí đối sánh của `If-None-Exist` khi tạo có điều kiện — bên gửi dùng `identifier={system}\|{value}` để lần gửi lại không sinh bản ghi thứ hai.

Resource Conformance: unspecifiedCoverageEligibilityResponse

Base System Profile
Kết quả tra cứu quyền lợi BHYT VN Core — VN Core Coverage Eligibility Response Profile

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support read.
SHOULD support search-type, vread.

Documentation

Phản hồi kết quả tra cứu thẻ BHYT từ Cổng giám định BHXH

Resource Conformance: unspecifiedClaimResponse

Base System Profile
Kết quả giải quyết BHYT VN Core — VN Core ClaimResponse Profile

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support read, search-type.
SHOULD support vread.

Search Parameters

Conformance	Parameter	Type
SHOULD	request	`reference`
SHOULD	status	`token`
SHOULD	vn-xml1-id	`token`

Resource Conformance: unspecifiedPatient

Base System Profile
Bệnh nhân VN Core — VN Core Patient Profile

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHALL support read, search-type.
SHOULD support vread.

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	vn-cccd	`token`

Resource Conformance: unspecifiedPaymentReconciliation

Base System Profile
Đối soát và phân bổ khoản thanh toán BHYT — VN Core BHYT Payment Reconciliation

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHOULD support read, search-type, vread.

Documentation

Kết quả đối soát, quyết toán chi phí KCB BHYT — VNCorePaymentReconciliation profile (TT 12/2026/TT-BTC)

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	created	`date`	Tìm theo kỳ đối soát
SHOULD	status	`token`

Resource Conformance: unspecifiedAccount

Base System Profile
Tài khoản viện phí — VN Core Account

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHOULD support read, search-type, vread.

Documentation

Tài khoản viện phí của đợt điều trị — VNCoreAccount profile

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	patient	`reference`	Tìm theo người bệnh

Resource Conformance: unspecifiedTask

Base System Profile
Kiến nghị xem xét lại chi phí BHYT — VN Core BHYT Cost Appeal Task

Profile Conformance
SHALL

Reference Policy
literal

Interaction summary

SHOULD support create, read, search-type, vread.

Documentation

Kiến nghị của cơ sở KCB về kết quả giám định — VNCoreClaimAppealTask profile

Search Parameters

Conformance	Parameter	Type	Documentation
SHOULD	status	`token`	Tìm theo trạng thái xử lý kiến nghị
SHOULD	identifier	`token`	Tiêu chí đối sánh của `If-None-Exist` khi tạo có điều kiện — bên gửi dùng `identifier={system}\|{value}` để lần gửi lại không sinh bản ghi thứ hai.