API Document
Giả lập Cổng BHYT
Tài liệu cho đội HTG.iHIS xây dựng luồng tra cứu quyền lợi, lập hồ sơ, gửi đề nghị thanh toán và nhận kết quả giám định.
Quy trình tích hợp
Cách đọc mã thẻ BHYT
| Phần | Ví dụ | Ý nghĩa |
|---|---|---|
| 2 chữ đầu | GD | Nhóm đối tượng tham gia: hộ gia đình |
| 1 chữ số | 4 | Mã mức hưởng BHYT |
| 2 chữ số | 79 | Mã địa phương phát hành: TP. Hồ Chí Minh |
| 10 chữ số cuối | 0000000001 | Mã số BHXH duy nhất của người tham gia |
Không nhầm: 79003 là mã cơ sở đăng ký KCB ban đầu, không phải phần mã tỉnh của thẻ.
Mã đối tượng thường gặp
| Mã | Nhóm đối tượng | Trong simulator |
|---|---|---|
| GD | Tham gia BHYT theo hộ gia đình | Có |
| DN | Người lao động trong doanh nghiệp | Có |
| CN | Công nhân quốc phòng, công an và nhóm tương ứng | Có |
| HT | Người hưởng lương hưu, trợ cấp mất sức hằng tháng | Có |
| TE | Trẻ em dưới 6 tuổi | Có |
| TN | Người đang hưởng trợ cấp thất nghiệp | Tham khảo |
| DT | Người dân tộc thiểu số thuộc nhóm được ngân sách đóng | Có |
| HN | Người thuộc hộ nghèo | Có |
| KC | Người tham gia kháng chiến và bảo vệ Tổ quốc | Có |
| CK | Người có công/cựu chiến binh thuộc nhóm mã tương ứng | Có |
| CC | Người có công với cách mạng theo nhóm hưởng tương ứng | Có |
| HS / SV | Học sinh / sinh viên | Tham khảo |
| QN / TQ | Quân nhân / thân nhân quân đội theo quy định | Tham khảo |
| TG | Nhóm đối tượng bổ sung theo quy định người có công | Tham khảo |
Mã có thể được sửa đổi theo văn bản BHXH từng thời kỳ. HIS phải lưu mã nhận từ kết quả tra cứu, không tự suy diễn chỉ từ tên nhóm.
Mã mức hưởng 1–5
| Mã | Mức cơ bản | Ghi chú tích hợp |
|---|---|---|
| 1 | 100% | Nhóm quyền lợi cao; có trường hợp không áp giới hạn tỷ lệ một số danh mục |
| 2 | 100% | Thanh toán trong phạm vi hưởng theo điều kiện tương ứng |
| 3 | 95% | Người bệnh cùng chi trả phần còn lại nếu không thuộc ngoại lệ |
| 4 | 80% | Mức phổ biến của hộ gia đình/người lao động |
| 5 | 100% | Mã quyền lợi đặc thù theo quy định |
Danh mục dùng chung
| Mã danh mục | Nội dung | Liên kết hồ sơ |
|---|---|---|
HEALTHCARE_SERVICES | Khám bệnh, chữa bệnh, ngày giường | XML3 · MA_DICH_VU/MA_GIUONG |
TECHNICAL_SERVICES | Xét nghiệm, CĐHA, thủ thuật, phẫu thuật | XML3/4 · MA_DICH_VU |
MEDICINES | Thuốc, hóa dược, YHCT, dược liệu — dữ liệu nguồn | XML2 · MA_THUOC |
MEDICAL_SUPPLIES | Chờ tệp nguồn vật tư y tế | XML3 · MA_VAT_TU/GOI_VTYT |
70.309 dòng kết quả trúng thầu thuốc
2023_KQTT_T9_Đến_T10.xlsx. Đây là dữ liệu nguồn do người vận hành cung cấp, không phải seed SIM-*.| Nhóm | Số dòng |
|---|---|
| Tân Dược | 63.719 |
| Chế phẩm YHCT | 5.983 |
| Vị thuốc/Dược liệu | 607 |
/api/v2/medicines/tenders/stats/api/v2/medicines/tenders?q=&provinceCode=&facilityCode=&category=&page=1&pageSize=50/api/v2/medicines/tenders/{id}Mỗi dòng giữ nguyên tên thuốc, hoạt chất, đường dùng, dạng bào chế, hàm lượng, đóng gói, số đăng ký, hãng/nước sản xuất, đơn vị tính, số lượng, giá, thành tiền, nhà thầu, quyết định, thời gian hiệu lực, gói và nhóm thầu, mã/tên cơ sở KCB.
AWAITING_SOURCE_FILE cho đến khi có đúng tệp vật tư.API danh mục
/api/v2/catalogsLiệt kê loại danh mục, căn cứ và mức bao phủ.
/api/v2/catalogs/{catalogCode}/versionsLiệt kê phiên bản, nguồn, thời hạn hiệu lực và số dòng.
/api/v2/catalogs/{catalogCode}/items?q=&version=&activeOn=&page=1&pageSize=50Tìm theo mã, tên hoặc hoạt chất; lọc phiên bản và ngày hiệu lực; tối đa 200 dòng/trang.
/api/v2/catalogs/{catalogCode}/importNạp/upsert một phiên bản. replaceVersion=true sẽ thay toàn bộ phiên bản cùng tên.
{
"version": "BHXH-CSKCB-2026-08",
"source": "Tệp danh mục do cơ quan có thẩm quyền cung cấp",
"replaceVersion": false,
"items": [{
"code": "MA-CUA-CSKCB", "name": "Tên danh mục",
"unit": "Lần", "price": 100000, "bhytRate": 100,
"effectiveFrom": "2026-01-01"
}]
}Cấu trúc dữ liệu danh mục
| Trường | Áp dụng | Ý nghĩa |
|---|---|---|
| code, name, groupCode | Tất cả | Mã, tên, nhóm |
| unit, price, bhytRate | Tất cả | Đơn vị, giá, tỷ lệ thanh toán |
| activeIngredient, strength, routeCode | Thuốc | Hoạt chất, hàm lượng, đường dùng |
| registrationNumber, manufacturer, country | Thuốc/VTYT | Đăng ký, hãng, nước sản xuất |
| paymentConditions | Tất cả | Điều kiện và giới hạn thanh toán |
| effectiveFrom, effectiveTo, version, source | Tất cả | Hiệu lực, phiên bản và nguồn truy vết |
| extensions | Tùy danh mục | Thuộc tính mở không làm vỡ API |
200 thẻ BHYT kiểm thử
Tên tiếng Việt tự nhiên, dữ liệu hoàn toàn tổng hợp. Tìm kiếm/phân trang qua /api/v1/simulator/cards/search hoặc mở trang tra cứu thẻ.
| Mã thẻ | Họ tên | Kịch bản |
|---|---|---|
GD4790000000001 | Nguyễn Minh Quân | VALID · 80% |
TE1790000000002 | Trần Gia Hân | VALID · 100% |
GD4790000000003 | Lê Hoàng Phúc | EXPIRED |
/api/v1/eligibility/checkTra cứu giá trị sử dụng thẻ
Gọi tại thời điểm tiếp nhận và lưu mã giao dịch để truy vết.
REQUEST
RESPONSE MẪU
Kết quả chạy thử sẽ hiển thị tại đây.
/api/v1/claims/validateTiền kiểm hồ sơ
Kiểm tra thời gian điều trị, ICD, chi phí, tỷ lệ hưởng, thời điểm thực hiện và cảnh báo trùng.
/api/v1/claimsGửi hồ sơ và giám định
HỒ SƠ MẪU
TẠO XUẤT TOÁN THỬ
Đổi code thành: "DV-KHONG-DANH-MUC" hoặc đặt quantity = 11.
Kết quả chạy thử sẽ hiển thị tại đây.
/api/v1/claims/{claimId}/assessmentKết quả giám định
Tách rõ tổng đề nghị, quỹ đề nghị, số được duyệt, số xuất toán và lỗi từng dòng.
Mã lỗi MVP
| Mã | Ý nghĩa |
|---|---|
| CARD_EXPIRED | Thẻ hết giá trị |
| IDENTITY_MISMATCH | Số định danh không khớp |
| SERVICE_OUTSIDE_VISIT | Dịch vụ ngoài thời gian điều trị |
| SERVICE_NOT_IN_CATALOG | Dịch vụ ngoài danh mục giả lập |
| QUANTITY_LIMIT_EXCEEDED | Số lượng vượt ngưỡng |