API Reference

BHYT AI · API tích hợp HIS

API giám định BHYT cho HIS: nhận hồ sơ XML QĐ130, chạy engine K1–K12 (gồm nhóm G gộp theo người bệnh và định mức theo lô), trả DỰ BÁO nguy cơ xuất toán kèm mã lỗi cố định + trích dẫn văn bản. Tài liệu này mô tả đầy đủ đầu vào và đầu ra của từng endpoint: tên trường, ý nghĩa, kiểu dữ liệu và phạm vi giá trị.

Base URL https://tt06byt.com/v1Xác thực X-API-KeyLỗi RFC 9457171 mã cố định

Nền tảng

Quy ước chung

Xác thực

Gửi header X-API-Key: <key> (sandbox: sandbox-demo-key) hoặc OAuth2 Bearer qua POST /v1/auth/token. Endpoint công khai (health/errors/constants) không cần key.

Kiểu dữ liệu

string chuỗi UTF-8 · int/number số · bool true/false · enum tập giá trị cố định (ghi ở cột phạm vi) · object/[] lồng nhau (trường con hiển thị thụt vào).

Trường bắt buộc / tuỳ chọn

Trong bảng "Đầu vào", cột Bắt buộc ghi rõ: ✔ bắt buộc = phải có; tuỳ chọn = có thể bỏ trống. Trường không đánh dấu (—) là trường con của response.

Phân biệt "mã SAI" vs "dữ liệu riêng của bệnh viện"

Khi gặp mã thuốc / DVKT KHÔNG có trong danh mục QUỐC GIA, hệ thống phân biệt 2 trường hợp bằng định dạng & nhóm/chương mã:

Mã SAI — sai định dạng hoặc nhóm/chương không tồn tại (vd thuốc 99.999, DVKT 99.9999.9999): báo lỗi (kèm maKhongHopLe: true) — "mã không hợp lệ, nhập lại".
Dữ liệu riêng của bệnh viện — mã ĐÚNG định dạng, nhóm/chương hợp lệ nhưng không có trong danh mục quốc gia (vd 40.99999): báo "Lỗi do hồ sơ chứa dữ liệu riêng của bệnh viện — cần phối hợp làm việc để giải quyết" (kèm coTheDangKyRieng: true + canhBaoDangKyRieng).

Các lỗi khác (sai cấu trúc XML, chống chỉ định, sai giới/tuổi, ICD lạ) luôn được báo là lỗi.

Lỗi (RFC 9457)

Mọi lỗi trả application/problem+json: {type, title, status, code, detail, traceId}. Mã code tra ở GET /v1/errors. Mọi response đều có traceId để đối soát log.

Mã HTTP	Ý nghĩa
`200`	Thành công.
`202`	Đã nhận (batch) — trả jobId.
`400`	Yêu cầu không hợp lệ (API-REQ-400).
`401`	Thiếu/sai xác thực (API-AUTH-401).
`404`	Không tìm thấy (API-NOTFOUND-404).
`409`	Xung đột Idempotency-Key (API-IDEMP-409).
`413`	Payload quá lớn (API-REQ-413).
`415`	Sai Content-Type (API-REQ-415).
`422`	Hồ sơ chứa PII chưa ẩn danh.
`429`	Vượt tần suất (API-RATE-429).

Cấu trúc dùng chung

Finding — một phát hiện giám định

Mọi endpoint giám định trả mảng findings[] gồm các phát hiện với cùng cấu trúc sau. Mỗi phát hiện gắn một mã cố định tra được.

Trường của Finding

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`code`	`string`	Mã lỗi cố định (tra ở GET /v1/errors). vd K2001, XML001…
`severity`	`enum`	Mức độ. CHAN \| CANHBAO \| GHICHU
`layer`	`string`	Tầng kiểm (XML/K1…K9).
`title`	`string`	Tiêu đề lỗi.
`message`	`string`	Diễn giải cụ thể theo hồ sơ.
`canCu`	`string`	Căn cứ pháp lý (trích dẫn văn bản).
`khacPhuc`	`string`	Cách khắc phục đề xuất.
`coTheDangKyRieng`	`bool`	[Lớp 1 — CẢNH BÁO] = true: mã ĐÚNG định dạng VÀ đúng nhóm/chương mã QUỐC GIA nhưng ngoài danh mục — nhiều khả năng DỮ LIỆU RIÊNG / mã mới của bệnh viện, cần phối hợp bổ sung.
`maNghiNgo`	`bool`	[Lớp 2 — CẢNH BÁO] = true: mã ĐÚNG định dạng nhưng tiền tố NGOÀI bộ mã quốc gia (vd nhóm '99','H') — NHIỀU KHẢ NĂNG SAI, đề nghị kiểm tra lại; KHÔNG khẳng định là mã đăng ký riêng.
`maKhongHopLe`	`bool`	[Lớp 3 — CHẶN] = true: mã CÓ KÝ TỰ LẠ / sai định dạng (lớp format QĐ130) → mã sai chắc chắn, nhập lại (không phải mã đăng ký riêng).

Giám định hồ sơ

Endpoint · Chủ đạo

Giám định hồ sơ từ XML QĐ130

POST/v1/claims/audit

Endpoint chủ đạo. Nhận TOÀN VĂN hồ sơ XML theo chuẩn QĐ130/QĐ-BYT (XML1 tổng hợp KCB + XML2 thuốc + XML3 DVKT/VTYT), chạy toàn bộ engine K1–K12 (cấu trúc · thuốc · chẩn đoán · DVKT/CLS · VTYT · giá · mức hưởng), nhóm G gộp theo người bệnh và định mức theo lô, rồi trả DỰ BÁO nguy cơ xuất toán kèm từng phát hiện có mã cố định + trích dẫn văn bản.

Đầu vào application/xml

Thân request là XML QĐ130 (UTF-8, tối đa 12MB). Sandbox CHỈ nhận hồ sơ ĐÃ ẩn danh — bỏ trống SO_CCCD/SO_CMND (nếu phát hiện số định danh → 422).

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`MA_LK`	`string`	✔ bắt buộc	Mã liên kết hồ sơ (khoá KCB). Xuất hiện trong cả 3 XML để ghép.
`MA_BENH`	`string`	✔ bắt buộc	Mã bệnh chính (ICD-10). Ràng buộc theo cờ TT06 (giới/tuổi/cấm bệnh chính). mã ICD-10 hợp lệ TT06
`MA_BENH_KHAC`	`string`	tuỳ chọn	Các mã bệnh kèm, ngăn bằng ';'. CV4059: ≤12 bệnh kèm. danh sách mã ICD-10
`GIOI_TINH`	`int`	✔ bắt buộc	Giới tính người bệnh. 1\|2\|3 — xem bộ mã GIOI_TINH
`NGAY_SINH / TUOI`	`string/int`	tuỳ chọn	Ngày sinh (yyyymmdd…) hoặc tuổi — để kiểm ràng buộc tuổi của mã bệnh.
`MA_LOAI_KCB`	`string`	tuỳ chọn	Hình thức KCB. 01–09 — xem bộ mã MA_LOAI_KCB
`MA_DOI_TUONG_KCB`	`string`	tuỳ chọn	Trường hợp đến KCB (nền tảng tính mức hưởng). xem bộ mã MA_DOITUONG_KCB
`CHI_TIET_THUOC[]`	`object`	tuỳ chọn	Danh sách thuốc (XML2): MA_THUOC, TEN_THUOC, SO_LUONG, THANH_TIEN, PHAM_VI…
`CHI_TIET_DVKT[]`	`object`	tuỳ chọn	Danh sách DVKT/VTYT (XML3): MA_DICH_VU, TEN_DICH_VU, DON_GIA, NGAY_TH_YL…
`MA_CSKCB`	`string`	tuỳ chọn	Mã cơ sở KCB. Nếu đã đăng ký danh mục cơ sở (POST /v1/co-so/danh-muc) → bật thêm K6003/K9003/K6004/K8002.
`CHUKYDONVI`	`string`	tuỳ chọn	Chữ ký số của cơ sở — thiếu sẽ bị cảnh báo cấu trúc.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`maHoSo`	`string`	Mã liên kết hồ sơ (từ MA_LK).
`benhChinh`	`string`	Mã bệnh chính đọc được.
`parseOk`	`bool`	Đọc được cấu trúc XML hay không. true\|false
`duBao`	`enum`	Dự báo tổng hồ sơ. DU_DIEU_KIEN \| CAN_DOI_CHIEU \| NGUY_CO_XUAT_TOAN
`diem`	`int`	Điểm rủi ro (tính minh bạch theo quy tắc). 0–100
`muc`	`string`	Diễn giải mức (Thấp/TB/Cao).
`tienNguyCo`	`number`	Tiền dòng có nguy cơ bị loại (đồng).
`tienTongNguyCo`	`number`	Tổng tiền nguy cơ (đồng).
`lyDo`	`string[]`	Danh sách lý do cộng điểm (giải thích minh bạch).
`soLoiChan`	`int`	Số phát hiện mức CHẶN.
`soCanhBao`	`int`	Số phát hiện mức CẢNH BÁO.
`soGhiChu`	`int`	Số phát hiện mức GHI CHÚ.
`soThuoc`	`int`	Số dòng thuốc trong hồ sơ.
`soDvkt`	`int`	Số dòng DVKT trong hồ sơ.
`phanTich[]`	`object`	Đếm phát hiện theo LĨNH VỰC: {linhVuc, chan, canhBao, ghiChu}.
`phanTichThuoc`	`object`	Quy về từng thuốc: {tong, thongQua, canhBao, loi, ghiChu, chiTiet[]}.
`mucHuong`	`object`	Mức hưởng: {the_pct, the_mo_ta, dong_pct[], tuyen}.
`findings[]`	`object`	Danh sách phát hiện — xem cấu trúc Finding bên dưới.
`canhBaoDangKyRieng`	`object`	CHỈ có khi có mã ngoài danh mục quốc gia: {so, moTa, danhSach[]} — hồ sơ chứa DỮ LIỆU RIÊNG của bệnh viện, cần phối hợp làm việc để giải quyết.
`tomTat`	`string`	Tóm tắt kết luận engine.
`luuY`	`string`	Ghi chú pháp lý: đây là DỰ BÁO hỗ trợ, không thay kết luận BHXH.
`traceId`	`string`	Mã truy vết log.

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/claims/audit \
  -H "X-API-Key: sandbox-demo-key" \
  -H "Content-Type: application/xml" \
  --data-binary @hoso.xml

Response

{
  "maHoSo": "HSVIDU001",
  "benhChinh": "J18",
  "parseOk": true,
  "duBao": "NGUY_CO_XUAT_TOAN",
  "ruiRo": {
    "diem": 58,
    "muc": "Trung bình",
    "tienNguyCo": 64000,
    "tienTongNguyCo": 64000,
    "lyDo": [
      "Thuốc có điều kiện +12",
      "..."
    ]
  },
  "tongKet": {
    "soLoiChan": 1,
    "soCanhBao": 1,
    "soGhiChu": 0,
    "soThuoc": 3,
    "soDvkt": 2
  },
  "findings": [
    {
      "code": "K2001",
      "severity": "CANHBAO",
      "layer": "K2",
      "title": "Thuốc có điều kiện thanh toán TT20",
      "message": "Thuốc Amoxicilin: …",
      "canCu": "TT20/2022/TT-BYT",
      "khacPhuc": "Bổ sung chứng từ…"
    }
  ],
  "traceId": "trc_xxx"
}

Endpoint

Báo cáo giám định (HTML in được)

POST/v1/claims/audit/report

Giống /claims/audit nhưng trả về BÁO CÁO HTML in được (một hồ sơ) — định danh → dự báo → bảng thuốc thông qua/cảnh báo/lỗi → chi tiết phát hiện. Dùng để in/đính kèm.

Đầu vào application/xml

Thân là XML QĐ130 (như /claims/audit).

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`(thân XML)`	`xml`	✔ bắt buộc	Toàn văn hồ sơ XML QĐ130.

Đầu ra text/html

Trả về trang HTML (không phải JSON).

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/claims/audit/report \
  -H "X-API-Key: sandbox-demo-key" -H "Content-Type: application/xml" \
  --data-binary @hoso.xml -o baocao.html

Response

<!doctype html> … trang báo cáo giám định …

Endpoint

Giám định LÔ (bất đồng bộ)

POST/v1/claims/audit/batch

Nhận nhiều hồ sơ XML, trả jobId ngay (202). Xử lý nền; có thể nhận webhook khi xong. Tối đa 100 hồ sơ/lô.

HTTP 202 Accepted + header Location: /v1/jobs/{jobId}.

Thân request application/json

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`hoSo`	`string[]`	✔ bắt buộc	Mảng các XML QĐ130 (mỗi phần tử là 1 hồ sơ). tối đa 100 phần tử
`callbackUrl`	`string`	tuỳ chọn	(tuỳ chọn) URL webhook nhận kết quả khi xong. http/https tới host công khai (chặn nội bộ)
`secret`	`string`	tuỳ chọn	(tuỳ chọn) khoá ký HMAC-SHA256 cho webhook (header X-BHYT-Signature).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`jobId`	`string`	Mã job để tra cứu.
`status`	`enum`	Trạng thái. PROCESSING
`tong`	`int`	Số hồ sơ trong lô.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/claims/audit/batch \
  -H "X-API-Key: sandbox-demo-key" -H "Content-Type: application/json" \
  -d '{"hoSo":["<XML>","<XML>"],"callbackUrl":"https://his.vn/hook"}'

Response

{
  "jobId": "job_ab12",
  "status": "PROCESSING",
  "tong": 2,
  "traceId": "trc_x"
}

Endpoint

Trạng thái job lô

GET/v1/jobs/{id}

Tra trạng thái tiến độ của một job giám định lô.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`id`	`string`	✔ bắt buộc	Mã job (jobId) từ /claims/audit/batch.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`id`	`string`	Mã job.
`status`	`enum`	Trạng thái. PROCESSING \| DONE
`tong`	`int`	Tổng số hồ sơ.
`done`	`int`	Số hồ sơ đã xử lý.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/jobs/job_ab12

Response

{
  "id": "job_ab12",
  "status": "DONE",
  "tong": 2,
  "done": 2,
  "traceId": "trc_x"
}

Endpoint

Kết quả job lô + tổng hợp xếp hạng

GET/v1/jobs/{id}/results

Trả kết quả từng hồ sơ + thẻ tổng hợp, xếp hạng theo tiền rủi ro (cho dashboard).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`id`	`string`	✔ bắt buộc	Mã job.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`status`	`enum`	Trạng thái job. PROCESSING \| DONE
`soHoSo`	`int`	Tổng số hồ sơ.
`soNguyCo`	`int`	Số hồ sơ NGUY_CO_XUAT_TOAN.
`soCanDoiChieu`	`int`	Số hồ sơ CAN_DOI_CHIEU.
`soDat`	`int`	Số hồ sơ DU_DIEU_KIEN.
`soLoi`	`int`	Số hồ sơ lỗi xử lý.
`tongTienNguyCo`	`number`	Tổng tiền nguy cơ toàn lô (đồng).
`results[]`	`object`	Mảng kết quả giám định từng hồ sơ (như response /claims/audit), xếp theo tiền rủi ro giảm dần.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/jobs/job_ab12/results

Response

{
  "status": "DONE",
  "tongHop": {
    "soHoSo": 2,
    "soNguyCo": 1,
    "soCanDoiChieu": 0,
    "soDat": 1,
    "soLoi": 0,
    "tongTienNguyCo": 64000
  },
  "results": [
    "…"
  ],
  "traceId": "trc_x"
}

Endpoint

Giám định từ JSON (trợ lý dựng đơn)

POST/v1/claim-audits

Nhận hồ sơ dạng JSON đơn giản (không cần XML). Kiểm K1–K8 (thuốc/chẩn đoán/DVKT/tương tác); KHÔNG kiểm cấu trúc XML, giá K9 hay mức hưởng — dùng khi HIS đang dựng đơn.

Thân request application/json

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`gioi`	`int`	tuỳ chọn	Giới tính. 1\|2\|3
`tuoi`	`int`	tuỳ chọn	Tuổi (số).
`benh_chinh`	`string`	✔ bắt buộc	Mã bệnh chính (ICD-10).
`benh_kt`	`string\|string[]`	tuỳ chọn	Bệnh kèm.
`thuoc[]`	`object`	tuỳ chọn	Mảng thuốc {ma, ten, sl}.
`dvkt[]`	`object`	tuỳ chọn	Mảng DVKT {ma, ten}.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`duBao`	`enum`	Dự báo. DU_DIEU_KIEN \| CAN_DOI_CHIEU \| NGUY_CO_XUAT_TOAN
`ruiRo`	`object`	{diem, muc, tienTongNguyCo, lyDo[]}.
`tongKet`	`object`	{soLoiChan, soCanhBao, soGhiChu, soThuoc, soDvkt}.
`findings[]`	`object`	Danh sách phát hiện (cấu trúc Finding).
`ketLuan`	`string`	Kết luận engine.
`luuY`	`string`	Ghi chú phạm vi (đường JSON không kiểm K9/mức hưởng).
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/claim-audits \
  -H "X-API-Key: sandbox-demo-key" -H "Content-Type: application/json" \
  -d '{"gioi":1,"tuoi":50,"benh_chinh":"E11.9","thuoc":[{"ma":"40.807","ten":"Metformin","sl":30}]}'

Response

{
  "duBao": "DU_DIEU_KIEN",
  "ruiRo": {
    "diem": 0,
    "muc": "Thấp",
    "tienTongNguyCo": 0,
    "lyDo": []
  },
  "tongKet": {
    "soLoiChan": 0,
    "soCanhBao": 0,
    "soGhiChu": 0,
    "soThuoc": 1,
    "soDvkt": 0
  },
  "findings": [],
  "ketLuan": "…",
  "traceId": "trc_x"
}

Endpoint

Kiểm đơn thuốc (tương tác + BHYT)

POST/v1/prescriptions/check

Kiểm nhanh một đơn thuốc: tương tác chống chỉ định (DDI QĐ5948) + thuốc có thuộc danh mục BHYT (TT20) không. Trả findings có mã.

Thân request application/json

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`thuoc[]`	`object`	✔ bắt buộc	Mảng thuốc {ma, ten}. Cần ít nhất ma hoặc ten mỗi phần tử.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`duBao`	`enum`	Dự báo. DU_DIEU_KIEN \| CAN_DOI_CHIEU \| NGUY_CO_XUAT_TOAN
`tongKet`	`object`	{soThuoc, soLoiChan, soCanhBao}.
`findings[]`	`object`	Phát hiện tương tác / ngoài danh mục (cấu trúc Finding).
`luuY`	`string`	Ghi chú phạm vi.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/prescriptions/check \
  -H "X-API-Key: sandbox-demo-key" -H "Content-Type: application/json" \
  -d '{"thuoc":[{"ten":"Warfarin"},{"ten":"Tamoxifen"}]}'

Response

{
  "duBao": "NGUY_CO_XUAT_TOAN",
  "tongKet": {
    "soThuoc": 2,
    "soLoiChan": 1,
    "soCanhBao": 0
  },
  "findings": [
    {
      "code": "K7001",
      "severity": "CHAN",
      "title": "Tương tác chống chỉ định",
      "message": "Warfarin + Tamoxifen (QĐ5948)."
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Đăng ký danh mục + bảng giá cơ sở

POST/v1/co-so/danh-muc

Cơ sở KCB đăng ký danh mục kỹ thuật ĐƯỢC DUYỆT + bảng giá + phạm vi khoa. Sau đó mọi hồ sơ có MA_CSKCB tương ứng tự bật giám định theo cơ sở: K6003 (DVKT ngoài DM duyệt) · K9003 (giá vượt) · K6004 (ngoài phạm vi khoa/CCHN) · K8002 (tách dịch vụ). Sandbox lưu tạm theo (API key, MA_CSKCB), TTL 24h.

Thân request application/json

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`maCSKCB`	`string`	✔ bắt buộc	Mã cơ sở KCB (khớp MA_CSKCB trong XML).
`dvktDuyet`	`string[]`	tuỳ chọn	Danh sách mã DVKT được duyệt (cùng hệ mã XML).
`bangGia`	`object`	tuỳ chọn	Bản đồ {mã DVKT: đơn giá đã duyệt (đồng)}.
`khoaDuyet`	`string[]`	tuỳ chọn	Danh sách mã khoa được duyệt.
`dvktTheoKhoa`	`object`	tuỳ chọn	{MA_KHOA: [DVKT được phép]} — phạm vi khoa/CCHN (#12).
`khongTach`	`object`	tuỳ chọn	{mã chính: [mã con không được tách]} — chống tách dịch vụ (#7/#10).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`maCSKCB`	`string`	Mã cơ sở đã đăng ký.
`soDvktDuyet`	`int`	Số mã DVKT được duyệt.
`soGia`	`int`	Số dòng bảng giá.
`soKhoaDuyet`	`int`	Số khoa được duyệt.
`soKhoaCoPhamVi`	`int`	Số khoa có phạm vi DVKT.
`soCapKhongTach`	`int`	Số cặp chống tách.
`hieuLuc`	`string`	Thời hạn hồ sơ (sandbox 24h).
`luuY`	`string`	Giải thích các mã sẽ được bật.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/co-so/danh-muc \
  -H "X-API-Key: sandbox-demo-key" -H "Content-Type: application/json" \
  -d '{"maCSKCB":"47001","dvktDuyet":["02.0314.0001"],"bangGia":{"02.0314.0001":50000}}'

Response

{
  "maCSKCB": "47001",
  "soDvktDuyet": 1,
  "soGia": 1,
  "soKhoaDuyet": 0,
  "soKhoaCoPhamVi": 0,
  "soCapKhongTach": 0,
  "hieuLuc": "24h (sandbox in-memory)",
  "traceId": "trc_x"
}

Endpoint

Xem hồ sơ danh mục cơ sở

GET/v1/co-so/{ma}

Xem lại số liệu danh mục cơ sở đã đăng ký.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	MA_CSKCB đã đăng ký.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`maCSKCB`	`string`	Mã cơ sở.
`soDvktDuyet`	`int`	Số DVKT duyệt.
`soGia`	`int`	Số dòng giá.
`soKhoaDuyet`	`int`	Số khoa duyệt.
`soKhoaCoPhamVi`	`int`	Số khoa có phạm vi.
`soCapKhongTach`	`int`	Số cặp chống tách.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/co-so/47001

Response

{
  "maCSKCB": "47001",
  "soDvktDuyet": 1,
  "soGia": 1,
  "soKhoaDuyet": 0,
  "soKhoaCoPhamVi": 0,
  "soCapKhongTach": 0,
  "traceId": "trc_x"
}

Mã bệnh ICD-10

Endpoint

Gợi ý mã ICD-10 (chịu lỗi chính tả)

GET/v1/icd/suggest

Autocomplete mã ICD-10 theo tên bệnh. Bỏ dấu vẫn ra; GÕ SAI CHÍNH TẢ vẫn gợi ý từ gần nhất (như YouTube). Kèm cờ quy tắc TT06 + số thuốc chỉ định.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	✔ bắt buộc	Từ khoá (tên bệnh hoặc mã), có/không dấu, chịu lỗi chính tả.
`limit`	`int`	tuỳ chọn	Số kết quả tối đa. 1–100 (mặc định 15)
`offset`	`int`	tuỳ chọn	Bỏ qua N kết quả đầu. ICD trả tối đa ~12 gợi ý (autocomplete, không phân trang sâu). ≥0

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`items[]`	`object`	Mảng gợi ý — mỗi phần tử {ma, ten, co, n_thuoc}.
`ma`	`string`	Mã ICD-10.
`ten`	`string`	Tên bệnh.
`co`	`string`	Cờ nổi bật (vd 'mã cha', 'chỉ Nữ').
`n_thuoc`	`int`	Số thuốc có chỉ định cho bệnh.
`q`	`string`	Từ khoá đã dùng.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" \
  "https://tt06byt.com/v1/icd/suggest?q=dai%20tao%20duong&limit=5"

Response

{
  "ket_qua": {
    "items": [
      {
        "ma": "E11",
        "ten": "Bệnh đái tháo đường típ 2",
        "co": "mã cha",
        "n_thuoc": 153
      }
    ],
    "q": "dai tao duong"
  },
  "traceId": "trc_x"
}

Endpoint

Chi tiết mã ICD + 6 cờ TT06 + kiểm theo bệnh nhân

GET/v1/icd/{code}

Chi tiết một mã bệnh: tên, hợp lệ, 6 cờ quy tắc (cột 24–29 TT06). Truyền thêm gioi/tuoi để KIỂM mã có hợp lệ với bệnh nhân không (ràng buộc giới cứng; tuổi thận trọng).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	✔ bắt buộc	Mã ICD-10 (vd E11.9, O80).
`gioi`	`enum`	tuỳ chọn	Giới bệnh nhân → kiểm ràng buộc giới của mã. 1\|2\|3
`tuoi`	`int`	tuỳ chọn	Tuổi bệnh nhân (năm) → kiểm giới hạn tuổi.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã ICD-10.
`ten`	`string`	Tên bệnh.
`hopLe`	`bool`	Mã có trong danh mục TT06. true\|false
`camBenhChinh`	`bool`	Không được dùng làm bệnh chính.
`chiNu`	`bool`	Chỉ ở nữ.
`chiNam`	`bool`	Chỉ ở nam.
`gioiHanTuoi`	`string\|null`	Giới hạn tuổi (free-text, nếu có).
`chuong`	`object`	Chương ICD-10 của mã: {ma (khoảng), ten (nhóm bệnh)}.
`kiemTra`	`object`	Chỉ có khi truyền gioi/tuoi: {gioi, tuoi, hopLe, viPham[], luuY[]}.
`canCu`	`string`	Căn cứ pháp lý.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/icd/O80?gioi=1&tuoi=30"

Response

{
  "ma": "O80",
  "ten": "Đẻ thường",
  "hopLe": true,
  "co": {
    "camBenhChinh": false,
    "chiNu": true,
    "chiNam": false,
    "gioiHanTuoi": null
  },
  "kiemTra": {
    "gioi": "1",
    "tuoi": 30,
    "hopLe": false,
    "viPham": [
      "Mã chỉ dùng cho NỮ nhưng bệnh nhân khai là NAM."
    ],
    "luuY": []
  },
  "canCu": "TT06/2026/TT-BYT",
  "traceId": "trc_x"
}

Endpoint

22 chương phân loại ICD-10

GET/v1/icd/chuong

Danh sách 22 chương ICD-10 (khoảng mã đầu → nhóm bệnh). Mỗi mã ICD ở /v1/icd/{code} cũng kèm chương.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`soChuong`	`int`	Số chương. 22
`ket_qua[]`	`object`	{ma (khoảng, vd A00–B99), ten (nhóm bệnh)}.
`canCu`	`string`	Căn cứ.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/icd/chuong

Response

{
  "soChuong": 22,
  "ket_qua": [
    {
      "ma": "A00–B99",
      "ten": "Bệnh nhiễm khuẩn và ký sinh vật"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Mã bệnh con (từ mã cha)

GET/v1/icd/{code}/con

Trả các mã con cụ thể hơn của một mã cha (vd E11 → E11.0…E11.9). Giúp chọn mã 4–5 ký tự thay mã cha 3 ký tự (CV4059).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	✔ bắt buộc	Mã ICD cha (vd E11).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`maCha`	`string`	Mã cha.
`tenCha`	`string`	Tên mã cha.
`soMaCon`	`int`	Số mã con.
`maCon[]`	`object`	{ma, ten, camBenhChinh, maChaCoMaCon}.
`luuY`	`string`	Khuyến nghị ghi mã con.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/icd/E11/con

Response

{
  "maCha": "E11",
  "tenCha": "Bệnh đái tháo đường típ 2",
  "soMaCon": 10,
  "maCon": [
    {
      "ma": "E11.9",
      "ten": "… không biến chứng",
      "camBenhChinh": false
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Mã bệnh cha (3 ký tự)

GET/v1/icd/{code}/cha

Trả mã cha 3 ký tự của một mã con.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	✔ bắt buộc	Mã ICD con (vd E11.9).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã đầu vào.
`maCha`	`string`	Mã cha 3 ký tự (nếu có).
`tenCha`	`string`	Tên mã cha.
`coMaCha`	`bool`	false nếu bản thân là mã gốc 3 ký tự.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/icd/E11.9/cha

Response

{
  "ma": "E11.9",
  "maCha": "E11",
  "tenCha": "Bệnh đái tháo đường típ 2",
  "hopLe": true,
  "traceId": "trc_x"
}

Endpoint

Thuốc BHYT chi trả cho một bệnh

GET/v1/icd/{code}/drugs

Danh sách thuốc BHYT dùng cho một mã bệnh (tham khảo, theo chỉ định Dược thư/phác đồ).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	✔ bắt buộc	Mã ICD-10 (vd E11).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma_icd`	`string`	Mã bệnh.
`ten_benh`	`string`	Tên bệnh.
`tong`	`int`	Số thuốc tìm thấy.
`so_bhyt`	`int`	Số thuốc thuộc BHYT.
`so_chinh_chu`	`int`	Số thuốc chỉ định chính chủ.
`so_dieu_kien`	`int`	Số thuốc có điều kiện thanh toán.
`thuoc[]`	`object`	Danh sách thuốc {ma, ten, …}.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/icd/E11/drugs

Response

{
  "ma_icd": "E11",
  "ten_benh": "Bệnh đái tháo đường típ 2",
  "tong": 153,
  "so_bhyt": 153,
  "thuoc": [
    "…"
  ],
  "traceId": "trc_x"
}

Thuốc & kê đơn

Endpoint

Gợi ý tên thuốc/hoạt chất

GET/v1/drugs/suggest

Autocomplete tên thuốc/hoạt chất BHYT (TT20). Bỏ dấu + chịu lỗi chính tả.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	✔ bắt buộc	Từ khoá (tên/mã), chịu lỗi chính tả.
`limit`	`int`	tuỳ chọn	Số kết quả tối đa. 1–100 (mặc định 15)

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`items[]`	`object`	{ma, ten}.
`q`	`string`	Từ khoá đã dùng.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" \
  "https://tt06byt.com/v1/drugs/suggest?q=metfomin&limit=5"

Response

{
  "ket_qua": {
    "items": [
      {
        "ma": "40.807",
        "ten": "Metformin"
      }
    ],
    "q": "metfomin"
  },
  "traceId": "trc_x"
}

Endpoint

Chi tiết thuốc + điều kiện thanh toán + giá

GET/v1/drugs/{code}

Chi tiết một thuốc theo mã: thuộc BHYT không, tỷ lệ %, NỘI DUNG điều kiện thanh toán TT20 (nếu có), và khoảng giá trúng thầu.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	✔ bắt buộc	Mã thuốc (vd 40.807).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã thuốc.
`ten`	`string`	Tên hoạt chất/thuốc.
`bhyt`	`bool\|null`	Thuộc danh mục BHYT chi trả. true\|false\|null
`tyLe`	`int`	Tỷ lệ thanh toán BHYT. %
`coDieuKien`	`bool`	Thuốc có điều kiện thanh toán TT20 hay không.
`dieuKien`	`string`	Nội dung điều kiện thanh toán TT20 (rỗng nếu không có).
`gia`	`object\|null`	Khoảng giá: {min, max, donVi, nguon} (KQ trúng thầu).
`canCu`	`string`	Căn cứ (TT20/2022 + TT37/2024).
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/drugs/40.277

Response

{
  "ma": "40.277",
  "ten": "Tenofovir (TDF)",
  "bhyt": true,
  "tyLe": 100,
  "coDieuKien": true,
  "dieuKien": "Đối với điều trị HIV/AIDS: thuốc được cấp phát tại trạm y tế xã…",
  "gia": {
    "min": "1400",
    "max": "2500",
    "donVi": "Viên",
    "nguon": "BHXH VN – KQ trúng thầu 2024"
  },
  "canCu": "TT20/2022/TT-BYT + TT37/2024",
  "traceId": "trc_x"
}

Endpoint

Chỉ định của thuốc (bệnh thường dùng)

GET/v1/drugs/{code}/icd

Reverse mapping thuốc → bệnh (chỉ định). THAM KHẢO, mapping còn thưa; không dùng tự xuất toán.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	✔ bắt buộc	Mã thuốc (vd 40.807).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`maThuoc`	`string`	Mã thuốc.
`chiDinh[]`	`object`	Danh sách bệnh {ma, ten}.
`luuY`	`string`	Ghi chú tham khảo.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/drugs/40.807/icd

Response

{
  "maThuoc": "40.807",
  "chiDinh": [
    {
      "ma": "E11",
      "ten": "Bệnh đái tháo đường típ 2"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Thuốc thay thế được BHYT

GET/v1/drugs/alternatives

Khi một thuốc bị loại, gợi ý thuốc thay thế được BHYT: cùng hoạt chất hoặc cùng chỉ định với bệnh.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`code`	`string`	tuỳ chọn	Mã thuốc gốc (tuỳ chọn).
`name`	`string`	tuỳ chọn	Tên thuốc gốc.
`icd`	`string`	tuỳ chọn	Mã bệnh để lọc theo chỉ định.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`goc`	`string`	Thuốc gốc.
`icd`	`string`	Mã bệnh.
`ten_benh`	`string`	Tên bệnh.
`goc_bad`	`bool`	Thuốc gốc có bị loại không.
`cung_hoat_chat[]`	`object`	Thuốc thay thế cùng hoạt chất.
`cung_chi_dinh[]`	`object`	Thuốc thay thế cùng chỉ định.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" \
  "https://tt06byt.com/v1/drugs/alternatives?icd=J18&name=Levofloxacin"

Response

{
  "goc": "Levofloxacin",
  "icd": "J18",
  "ten_benh": "Viêm phổi",
  "cung_hoat_chat": [
    "…"
  ],
  "cung_chi_dinh": [
    "…"
  ],
  "traceId": "trc_x"
}

Dịch vụ kỹ thuật · VTYT · Danh mục kỹ thuật

Endpoint

Gợi ý dịch vụ kỹ thuật (QĐ2010)

GET/v1/dvkt/suggest

Autocomplete DVKT/CLS (9.213 mã QĐ2010). Bỏ dấu + chịu lỗi chính tả.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	✔ bắt buộc	Từ khoá.
`limit`	`int`	tuỳ chọn	Số kết quả. 1–100 (mặc định 15)

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	Mảng {ma, ten}.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/dvkt/suggest?q=sieu%20am"

Response

{
  "ket_qua": [
    {
      "ma": "14.0240.0845",
      "ten": "Siêu âm mắt"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Chi tiết DVKT + phân loại kỹ thuật

GET/v1/dvkt/{ma}

Chi tiết một DVKT: tên gọn + phân loại (Phẫu thuật/Thủ thuật/Loại 1–3).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã DVKT (vd 01.0303.0001).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã DVKT.
`ten`	`string`	Tên dịch vụ (đã làm sạch).
`phanLoai`	`enum`	Mã phân loại. PT\|TT\|TDB\|T1\|T2\|T3 — xem DVKT_PHAN_LOAI
`phanLoaiTen`	`string`	Tên phân loại.
`nhom`	`enum`	Nhóm. DVKT \| GIUONG
`canCu`	`string`	Căn cứ QĐ2010.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/dvkt/01.0303.0001

Response

{
  "ma": "01.0303.0001",
  "ten": "Siêu âm cấp cứu tại giường bệnh",
  "phanLoai": "T2",
  "phanLoaiTen": "Loại 2",
  "nhom": "DVKT",
  "traceId": "trc_x"
}

Endpoint

Danh mục tiền giường

GET/v1/dvkt/giuong

Danh sách 78 mã tiền giường (PL3/4 QĐ2010).

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`soGiuong`	`int`	Số mã giường.
`ket_qua[]`	`string`	Mảng mã giường.
`canCu`	`string`	Căn cứ.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/dvkt/giuong

Response

{
  "soGiuong": 75,
  "ket_qua": [
    "K02.HSCC",
    "K02.HSTC"
  ],
  "traceId": "trc_x"
}

Endpoint

Danh mục chuyên khoa khám bệnh

GET/v1/dvkt/chuyen-khoa

Danh sách 36 chuyên khoa khám bệnh (QĐ2010).

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`soChuyenKhoa`	`int`	Số chuyên khoa.
`ket_qua[]`	`object`	{ma, ten}.
`canCu`	`string`	Căn cứ.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/dvkt/chuyen-khoa

Response

{
  "soChuyenKhoa": 36,
  "ket_qua": [
    {
      "ma": "01.02",
      "ten": "Hồi sức cấp cứu và chống độc"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Tra vật tư y tế (VTYT) + trần thanh toán

GET/v1/vtyt/suggest

Gợi ý thiết bị/vật tư y tế BHYT (TT04/2017 + TT24/2025, 351 mục) kèm trần thanh toán. TRA CỨU THAM CHIẾU — mã TT04 khác hệ mã XML3, không auto-audit.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Từ khoá (bỏ trống = nhóm đầu).
`limit`	`int`	tuỳ chọn	Số kết quả. 1–50 (mặc định 15)

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{ma, ten, donVi, tranTt, ghiChu, nguon}.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/vtyt/suggest?q=stent"

Response

{
  "ket_qua": [
    {
      "ma": "N06.02.040",
      "ten": "Stent động mạch chi",
      "donVi": "Cái",
      "tranTt": "20.000.000 đồng/1 stent",
      "nguon": "TT04/2017"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Chi tiết VTYT theo mã TT04

GET/v1/vtyt/{ma}

Chi tiết một VTYT: tên, đơn vị, trần thanh toán, nguồn.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã nhóm TT04 (vd N06.02.020).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã VTYT.
`ten`	`string`	Tên.
`donVi`	`string`	Đơn vị tính.
`tranTt`	`string`	Trần thanh toán.
`ghiChu`	`string`	Ghi chú.
`nguon`	`string`	Nguồn văn bản (TT04/2017 hay TT24/2025).
`canCu`	`string`	Căn cứ hợp nhất.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/vtyt/N06.02.020

Response

{
  "ma": "N06.02.020",
  "ten": "Stent phủ thuốc",
  "donVi": "Cái",
  "tranTt": "36.000.000 đồng/1 stent",
  "nguon": "TT04/2017",
  "traceId": "trc_x"
}

Endpoint

Tra danh mục kỹ thuật chuẩn (TT23/2024)

GET/v1/dmkt/suggest

Gợi ý danh mục kỹ thuật KCB chuẩn quốc gia. Bản HIỆN HÀNH = Phụ lục 01 (18.205 KT, dùng đến 31/12/2027 theo TT25/2026/TT-BYT); Phụ lục 02 áp dụng từ 01/01/2028. Lọc theo chương. TRA CỨU THAM CHIẾU — mã liên kết khác hệ mã DVKT 9 số.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Từ khoá.
`limit`	`int`	tuỳ chọn	Số kết quả. 1–50 (mặc định 15)
`chuong`	`string`	tuỳ chọn	Lọc theo tên chương (vd 'Tiêu hóa').

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{stt, chuong, maLienKet, ten}.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/dmkt/suggest?q=noi%20soi"

Response

{
  "ket_qua": [
    {
      "stt": "4077",
      "chuong": "13. Sinh dục nữ",
      "maLienKet": "",
      "ten": "Nội soi âm đạo"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Kỹ thuật theo mã liên kết TT23

GET/v1/dmkt/{ma}

Trả các kỹ thuật có cùng mã liên kết chương.số.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã liên kết (vd 10.7).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`maLienKet`	`string`	Mã liên kết.
`ketQua[]`	`object`	{stt, chuong, maLienKet, ten}.
`canCu`	`string`	Căn cứ TT23/2024.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/dmkt/10.7

Response

{
  "maLienKet": "10.7",
  "ketQua": [
    {
      "stt": "1",
      "chuong": "1. Thần kinh",
      "ten": "Phẫu thuật lấy máu tụ…"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Danh sách 30 chương kỹ thuật

GET/v1/dmkt/chuong

Danh sách 30 chương kỹ thuật TT23/2024 + số kỹ thuật mỗi chương.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`soChuong`	`int`	Số chương.
`chuong[]`	`object`	{chuong, soKyThuat}.
`canCu`	`string`	Căn cứ.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/dmkt/chuong

Response

{
  "soChuong": 30,
  "chuong": [
    {
      "chuong": "1. Thần kinh",
      "soKyThuat": 259
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Tra cứu hợp nhất

GET/v1/search

Một endpoint tra mọi danh mục: bệnh, thuốc, DVKT, tương tác, VTYT, kỹ thuật.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`type`	`enum`	✔ bắt buộc	Loại danh mục. icd \| thuoc \| dvkt \| ddi \| vtyt \| dmkt \| icd9 \| yhct
`q`	`string`	✔ bắt buộc	Từ khoá.
`limit`	`int`	tuỳ chọn	Số kết quả. 1–100 (mặc định 15)

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`array`	Mảng kết quả (cấu trúc tuỳ theo type).
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/search?type=icd&q=viem%20phoi"

Response

{
  "ket_qua": [
    {
      "ma": "J18",
      "ten": "Viêm phổi"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Tra mã ICD-9-CM phẫu thuật/thủ thuật (QĐ387)

GET/v1/icd9/suggest

Gợi ý mã ICD-9-CM (bảng phân loại phẫu thuật, thủ thuật QĐ387/QĐ-BYT, 3.660 mã SONG NGỮ) — nền cho thanh toán theo nhóm chẩn đoán DRG. Điền vào trường MA_PTTT_QT của hồ sơ.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	✔ bắt buộc	Từ khoá tên phẫu thuật/thủ thuật (có/không dấu).
`limit`	`int`	tuỳ chọn	Số kết quả. 1–100 (mặc định 15)

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{ma, loai, tenVi, tenEn, chuong, chuongTen}.
`canCu`	`string`	QĐ387/QĐ-BYT.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/icd9/suggest?q=cat%20tui%20mat"

Response

{
  "ket_qua": [
    {
      "ma": "51.22",
      "loai": "ma",
      "tenVi": "Phẫu thuật cắt túi mật",
      "tenEn": "Cholecystectomy",
      "chuong": "09"
    }
  ],
  "canCu": "QĐ387/QĐ-BYT (05/02/2026)",
  "traceId": "trc_x"
}

Endpoint

Chi tiết mã ICD-9-CM

GET/v1/icd9/{ma}

Chi tiết 1 mã ICD-9-CM (tên Việt + Anh + chương) theo QĐ387/QĐ-BYT.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã ICD-9-CM (vd 51.22).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã.
`tenVi`	`string`	Tên tiếng Việt.
`tenEn`	`string`	Tên tiếng Anh (CMS).
`chuong`	`string`	Mã chương.
`chuongTen`	`string`	Tên chương.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/icd9/51.22

Response

{
  "ma": "51.22",
  "tenVi": "Phẫu thuật cắt túi mật",
  "tenEn": "Cholecystectomy",
  "chuong": "09",
  "traceId": "trc_x"
}

Endpoint

Danh mục 252 bệnh mạn tính kê đơn dài ngày (TT26/2025)

GET/v1/benh-mantinh

252 bệnh/nhóm bệnh được kê đơn ngoại trú trên 30 ngày, tối đa 90 ngày (TT26/2025 Phụ lục VII, thay TT52/2017). Truyền icd= để kiểm 1 mã có thuộc danh mục không.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`icd`	`string`	tuỳ chọn	Mã ICD-10 → kiểm có thuộc danh mục bệnh mạn tính không.
`q`	`string`	tuỳ chọn	Tìm theo tên bệnh.
`limit`	`int`	tuỳ chọn	Số kết quả. mặc định 30

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`laBenhManTinh`	`bool`	(khi truyền icd) mã có thuộc 252 bệnh không.
`chiTiet`	`object`	{tenBenh, maTT, chuyenKhoa}.
`ket_qua[]`	`object`	(khi không truyền icd) danh sách bệnh.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/benh-mantinh?icd=C50"

Response

{
  "icd": "C50",
  "laBenhManTinh": true,
  "chiTiet": {
    "tenBenh": "Ung thư vú",
    "maTT": "2.1"
  },
  "canCu": "TT26/2025/TT-BYT Phụ lục VII",
  "traceId": "trc_x"
}

Endpoint

Danh mục 282 bệnh cần chữa trị dài ngày (TT25/2025)

GET/v1/benh-dai-ngay

282 bệnh cần chữa trị dài ngày (TT25/2025 Phụ lục I) — dùng cho loại hình KCB điều trị dài ngày (MA_LOAI_KCB 05/08). KHÁC 252 bệnh mạn tính kê đơn (TT26). Truyền icd= để kiểm 1 mã.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`icd`	`string`	tuỳ chọn	Mã ICD-10 → kiểm có thuộc 282 bệnh dài ngày không.
`q`	`string`	tuỳ chọn	Tìm theo tên bệnh.
`limit`	`int`	tuỳ chọn	Số kết quả. mặc định 30

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`laBenhDaiNgay`	`bool`	(khi truyền icd) mã có thuộc 282 bệnh không.
`ket_qua[]`	`object`	(khi không truyền icd) danh sách bệnh {stt, tenBenh, maICD}.
`canCu`	`string`	TT25/2025 PL I.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/benh-dai-ngay?icd=A15"

Response

{
  "icd": "A15",
  "laBenhDaiNgay": true,
  "canCu": "TT25/2025/TT-BYT Phụ lục I (282 bệnh)",
  "traceId": "trc_x"
}

Endpoint

Cấp thông cấp KCB của mã bệnh (TT01/2025)

GET/v1/thong-cap

Trả cấp thông cấp của 1 mã bệnh theo TT01/2025 + Điều 22 Luật BHYT 51/2024: chuyen_sau (62 bệnh đi thẳng cấp chuyên sâu, hưởng 100%, không cần giấy chuyển) / co_ban (106) / phieu_chuyen (37) / cap_ban_dau (11).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`icd`	`string`	tuỳ chọn	Mã ICD-10 → trả cấp thông cấp.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`cap`	`string`	chuyen_sau \| co_ban \| phieu_chuyen \| cap_ban_dau \| null.
`yNghia`	`string`	Diễn giải quyền lợi.
`canCu`	`string`	TT01/2025 + Luật 51/2024.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/thong-cap?icd=A17.0"

Response

{
  "icd": "A17.0",
  "cap": "chuyen_sau",
  "yNghia": "Cấp chuyên sâu — đi thẳng, hưởng 100%, không cần giấy chuyển (Phụ lục I, 62 bệnh)",
  "traceId": "trc_x"
}

Endpoint

Tra thuốc cổ truyền/dược liệu YHCT (TT05/2015 + TT27/2025)

GET/v1/yhct/suggest

Gợi ý thuốc cổ truyền, thuốc từ dược liệu (mã 05C = chế phẩm) và vị thuốc cổ truyền/dược liệu (mã 05V) được BHYT chi trả — KHÁC danh mục hoá dược TT20. Engine nhận diện mã 05C/05V để KHÔNG báo nhầm thuốc YHCT là 'ngoài danh mục' (mã YHCT001/YHCT002).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	✔ bắt buộc	Tên/mã thuốc YHCT (có/không dấu).
`limit`	`int`	tuỳ chọn	Số kết quả. 1–100 (mặc định 15)

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{ma, loai (che_pham\|vi_thuoc), ten, thanhPhan, duongDung}.
`canCu`	`string`	TT05/2015 + TT27/2025.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/yhct/suggest?q=cam%20thao"

Response

{
  "ket_qua": [
    {
      "ma": "05V.329",
      "loai": "vi_thuoc",
      "ten": "Cam thảo"
    }
  ],
  "canCu": "TT05/2015 + TT27/2025/TT-BYT",
  "traceId": "trc_x"
}

Endpoint

Chi tiết thuốc YHCT

GET/v1/yhct/{ma}

Chi tiết 1 thuốc cổ truyền/dược liệu (chế phẩm 05C hoặc vị thuốc 05V) + thành phần + đường dùng.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã thuốc YHCT (vd 05V.80).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã.
`loai`	`string`	che_pham \| vi_thuoc.
`ten`	`string`	Tên.
`thanhPhan`	`string`	Thành phần.
`duongDung`	`string`	Đường dùng.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/yhct/05V.80

Response

{
  "ma": "05V.80",
  "loai": "vi_thuoc",
  "ten": "Cam thảo dây",
  "canCu": "TT05/2015 + TT27/2025/TT-BYT",
  "traceId": "trc_x"
}

Endpoint

Tra cứu HÀNG LOẠT (nhiều mã 1 request)

POST/v1/lookup

Đối chiếu cả bộ mã của một lượt khám trong 1 request: gửi mảng mã ICD/thuốc/DVKT/VTYT/DMKT → trả chi tiết từng mã + danh sách mã không tồn tại. Tối đa 200 mã/lần.

Thân request application/json

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`icd`	`string[]`	tuỳ chọn	Danh sách mã ICD-10.
`thuoc`	`string[]`	tuỳ chọn	Danh sách mã thuốc.
`dvkt`	`string[]`	tuỳ chọn	Danh sách mã DVKT.
`vtyt`	`string[]`	tuỳ chọn	Danh sách mã VTYT (TT04).
`dmkt`	`string[]`	tuỳ chọn	Danh sách mã liên kết DMKT (TT23).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`icd[]`	`object`	Chi tiết ICD hợp lệ {ma, ten, co}.
`thuoc[]`	`object`	Chi tiết thuốc (như /drugs/{code}).
`dvkt[]`	`object`	Chi tiết DVKT.
`vtyt[]`	`object`	Chi tiết VTYT.
`dmkt[]`	`object`	Kỹ thuật theo mã liên kết.
`khongTonTai[]`	`object`	Mã không tìm thấy {loai, ma}.
`tongTra`	`int`	Tổng số mã đã tra.
`soKhongTonTai`	`int`	Số mã không tồn tại.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/lookup \
  -H "X-API-Key: sandbox-demo-key" -H "Content-Type: application/json" \
  -d '{"icd":["E11.9"],"thuoc":["40.807"],"dvkt":["01.0303.0001"]}'

Response

{
  "icd": [
    {
      "ma": "E11.9",
      "ten": "…",
      "co": {}
    }
  ],
  "thuoc": [
    {
      "ma": "40.807",
      "ten": "Metformin",
      "bhyt": true
    }
  ],
  "dvkt": [
    {
      "ma": "01.0303.0001",
      "ten": "Siêu âm…"
    }
  ],
  "vtyt": [],
  "dmkt": [],
  "khongTonTai": [],
  "tongTra": 3,
  "soKhongTonTai": 0,
  "traceId": "trc_x"
}

Hệ thống & tra cứu chung

Endpoint · Công khai

Kiểm tra sức khoẻ (công khai)

GET/v1/health

Trạng thái API + quy mô engine. KHÔNG cần API key.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ok`	`bool`	API sống. true
`version`	`string`	Phiên bản API.
`engine`	`object`	{ddi, catalog, icd} — quy mô danh mục nạp.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl https://tt06byt.com/v1/health

Response

{
  "ok": true,
  "version": "2.12.1",
  "engine": {
    "ddi": 647,
    "catalog": 1095,
    "icd": 15844
  },
  "traceId": "trc_x"
}

Endpoint · Công khai

Phiên bản API + changelog (công khai)

GET/v1/version

Phiên bản hiện tại + lịch sử thay đổi (changelog) để đối tác theo dõi cập nhật.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`version`	`string`	Phiên bản API (semver).
`engine`	`object`	Quy mô danh mục nạp {icd, thuoc, ddi}.
`changelog[]`	`object`	Danh sách phiên bản {version, thayDoi[]}.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl https://tt06byt.com/v1/version

Response

{
  "version": "2.12.1",
  "engine": {
    "icd": 15844,
    "thuoc": 1095,
    "ddi": 647
  },
  "changelog": [
    {
      "version": "2.0",
      "thayDoi": [
        "Giám định K1–K12 + nhóm G + định mức theo lô…",
        "/lookup…"
      ]
    }
  ],
  "traceId": "trc_x"
}

Endpoint · Công khai

Bảng 171 mã lỗi/cảnh báo (công khai)

GET/v1/errors

Toàn bộ mã cố định để tra bằng máy. Mỗi mã gắn severity + căn cứ pháp lý + cách khắc phục.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`codes[]`	`object`	Danh sách mã — mỗi mã {code, severity, layer, title, meaning, trigger, basis, action}.
`total`	`int`	Tổng số mã. 57
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl https://tt06byt.com/v1/errors

Response

{
  "codes": [
    {
      "code": "K2001",
      "severity": "CANHBAO",
      "layer": "K2",
      "title": "Thuốc có điều kiện thanh toán TT20"
    }
  ],
  "total": 57,
  "traceId": "trc_x"
}

Endpoint · Công khai

Danh sách bộ mã giá trị (công khai)

GET/v1/constants

Danh sách 14 bộ mã giá trị dùng trong XML BHYT (QĐ130 + sửa đổi). Chi tiết: mục “Bộ mã giá trị” bên dưới hoặc GET /v1/constants/{ma}.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`boMa[]`	`object`	{ma, truong, moTa, canCu, doTinCay, soGiaTri}.
`total`	`int`	Số bộ mã. 14
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl https://tt06byt.com/v1/constants

Response

{
  "boMa": [
    {
      "ma": "GIOI_TINH",
      "truong": "GIOI_TINH (XML1)",
      "doTinCay": "CAO",
      "soGiaTri": 3
    }
  ],
  "total": 14,
  "traceId": "trc_x"
}

Endpoint · Công khai

Chi tiết một bộ mã giá trị (công khai)

GET/v1/constants/{ma}

Chi tiết một bộ mã: danh sách giá trị + ý nghĩa + căn cứ + độ tin cậy.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã bộ (vd MA_DOITUONG_KCB, GIOI_TINH).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ma`	`string`	Mã bộ.
`truong`	`string`	Trường XML tương ứng.
`moTa`	`string`	Mô tả.
`canCu`	`string`	Căn cứ pháp lý.
`doTinCay`	`enum`	Độ tin cậy. CAO \| THAM_KHAO \| CAN_KIEM
`giaTri[]`	`object`	Danh sách giá trị {ma, ten, (mucHuong)}.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl https://tt06byt.com/v1/constants/MA_DOITUONG_KCB

Response

{
  "ma": "GIOI_TINH",
  "truong": "GIOI_TINH (XML1)",
  "moTa": "Giới tính người bệnh",
  "canCu": "QĐ130 Bảng 1 (STT7)",
  "doTinCay": "CAO",
  "giaTri": [
    {
      "ma": "1",
      "ten": "Nam"
    },
    {
      "ma": "2",
      "ten": "Nữ"
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Danh mục dùng chung + phiên bản văn bản

GET/v1/catalogs

Liệt kê các danh mục (ICD/thuốc/DVKT/DDI/VTYT/DMKT/mức hưởng) + số văn bản + hiệu lực + số dòng.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`danhMuc[]`	`object`	{ten, docNo, hieuLuc, moTa, soDong, (ghiChu)}.
`luuY`	`string`	Ghi chú phiên bản.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/catalogs

Response

{
  "danhMuc": [
    {
      "ten": "icd10",
      "docNo": "TT06/2026/TT-BYT",
      "hieuLuc": "2026-07-01",
      "soDong": 15844
    }
  ],
  "traceId": "trc_x"
}

Endpoint

Chi tiết một danh mục

GET/v1/catalogs/{name}

Thông tin phiên bản một danh mục.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`name`	`enum`	✔ bắt buộc	Tên danh mục. icd10 \| drugs \| dvkt \| ddi \| vtyt \| dmkt \| muc-huong

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ten/docNo/hieuLuc/moTa/soDong`	`…`	Như một phần tử của /catalogs.
`traceId`	`string`	Mã truy vết.

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/catalogs/icd10

Response

{
  "ten": "icd10",
  "docNo": "TT06/2026/TT-BYT",
  "hieuLuc": "2026-07-01",
  "soDong": 15844,
  "traceId": "trc_x"
}

Endpoint · Công khai

Lấy access token (OAuth2, sandbox stub)

POST/v1/auth/token

Cấp Bearer token theo client-credentials. SANDBOX: cấp token cho mọi client_id/secret (stub); production sẽ xác thực client thật.

Thân request application/json

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`client_id`	`string`	✔ bắt buộc	Định danh client.
`client_secret`	`string`	✔ bắt buộc	Khoá bí mật client.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`access_token`	`string`	Bearer token (dùng ở header Authorization).
`token_type`	`string`	Loại token. Bearer
`expires_in`	`int`	Số giây hết hạn. 3600
`scope`	`string`	Phạm vi. audit read

Ví dụ

Request

curl -X POST https://tt06byt.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"his_demo","client_secret":"..."}'

Response

{
  "access_token": "tok_ab12…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "audit read"
}

Tiện ích & danh mục mới

Endpoint

Giải mã thẻ BHYT 15 ký tự

GET/v1/the/decode

Giải mã cấu trúc mã thẻ BHYT (QĐ1351): 2 ký tự đầu = đối tượng, ký tự 3 = mức hưởng, ký tự 4–5 = mã tỉnh, 6–15 = mã số BHXH.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`ma`	`string`	✔ bắt buộc	Mã thẻ BHYT 15 ký tự.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`doiTuong`	`object`	{ma, ten}.
`mucHuong`	`object`	{kyTu3, phanTram, moTa}.
`maTinh`	`string`	Mã tỉnh.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/the/decode?ma=HT2010112345678"

Response

{
  "maThe": "HT2010112345678",
  "doiTuong": {
    "ma": "HT",
    "ten": "Hưu trí"
  },
  "mucHuong": {
    "kyTu3": "2",
    "phanTram": 100
  },
  "maTinh": "01"
}

Endpoint

Tra giá thuốc tham khảo

GET/v1/gia-thuoc

Tra giá trúng thầu (cổng VSS/BHXH: min/trung vị/max) + giá kê khai (Cục QLD) theo SĐK hoặc tên thuốc.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`sdk`	`string`	tuỳ chọn	Số đăng ký thuốc.
`q`	`string`	tuỳ chọn	Tên thuốc.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`giaTrungThau`	`object`	{min, trungVi, max, soGoiThau, thang}.
`giaKeKhai`	`object`	{gia, ten, ngay}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/gia-thuoc?q=paracetamol"

Response

{
  "ketQua": [
    {
      "sodk": "300110016525",
      "ten": "Paracetamol",
      "trungVi": 39500,
      "max": 40000
    }
  ]
}

Endpoint

Mức hưởng theo mã đối tượng KCB (QĐ3276)

GET/v1/muc-huong

Tra mức hưởng/tuyến theo mã đối tượng KCB (QĐ3276/QĐ-BYT). Không truyền maDoiTuong = liệt kê 22 mã.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`maDoiTuong`	`string`	tuỳ chọn	Mã đối tượng KCB (vd 1.1).

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ketQua`	`object/array`	{truong_hop, muc_huong, pct_tuyen, trai_tuyen}.
`canCu`	`string`	QĐ3276.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/muc-huong?maDoiTuong=1.1"

Response

{
  "maDoiTuong": "1.1",
  "hopLe": true,
  "ketQua": {
    "muc_huong": "100% chi phí KCB",
    "pct_tuyen": 100,
    "trai_tuyen": false
  }
}

Endpoint

Kiểm tương tác chống chỉ định 2 thuốc (QĐ5948)

GET/v1/ddi

Kiểm nhanh cặp hoạt chất có thuộc danh mục tương tác thuốc CHỐNG CHỈ ĐỊNH (QĐ5948/QĐ-BYT) không.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`a`	`string`	✔ bắt buộc	Tên/hoạt chất thuốc 1.
`b`	`string`	✔ bắt buộc	Tên/hoạt chất thuốc 2.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`tuongTacChongChiDinh`	`bool`	Có/không tương tác CCĐ.
`khuyenCao`	`string`
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/ddi?a=Warfarin&b=Tamoxifen"

Response

{
  "thuocA": "Warfarin",
  "thuocB": "Tamoxifen",
  "tuongTacChongChiDinh": true,
  "canCu": "QĐ5948/QĐ-BYT"
}

Endpoint

14 nhóm chi phí MA_NHOM (QĐ5937)

GET/v1/nhom-chi-phi

Danh mục 14 nhóm chi phí của trường MA_NHOM trong XML2/XML3 (QĐ5937 PL3).

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ketQua[]`	`object`	{ma, ten}.
`canCu`	`string`	QĐ5937 PL3.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/nhom-chi-phi

Response

{
  "ketQua": [
    {
      "ma": "4",
      "ten": "Thuốc"
    },
    {
      "ma": "1",
      "ten": "Xét nghiệm"
    }
  ]
}

Endpoint

Cổng chẩn đoán TT20 (điều kiện thanh toán gắn ICD)

GET/v1/dieu-kien-thuoc

12 thuốc mà TT20/2022 CHỈ thanh toán cho chẩn đoán cụ thể (engine tự kiểm — mã DK001).

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{hoatChat, benh, maICD[], canCu}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/dieu-kien-thuoc

Response

{
  "tong": 12,
  "ket_qua": [
    {
      "hoatChat": "Oseltamivir",
      "benh": "nhiễm vi rút cúm",
      "maICD": [
        "J09",
        "J10",
        "J11"
      ]
    }
  ]
}

Endpoint

Thuốc phải hội chẩn (dấu * TT20 Đ2.7)

GET/v1/thuoc-hoi-chan

Danh mục thuốc phải hội chẩn trước khi dùng (dấu * — TT20/2022 Điều 2.7 + QĐ5631). Engine cảnh báo mã HC001.

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`string`	Tên hoạt chất.
`canCu`	`string`
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/thuoc-hoi-chan

Response

{
  "tong": 16,
  "ket_qua": [
    "Meropenem Tiêm",
    "Colistin Tiêm"
  ]
}

Endpoint

Thuốc kiểm soát đặc biệt (TT18/2026)

GET/v1/thuoc-kiem-soat

125 hoạt chất gây nghiện/hướng thần/tiền chất (TT18/2026/TT-BYT, hiệu lực 16/7/2026). Engine gắn cờ GHI CHÚ (KS001).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{hoatChat, nhom}.
`canCu`	`string`
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/thuoc-kiem-soat?q=morphin"

Response

{
  "tong": 1,
  "ket_qua": [
    {
      "hoatChat": "Morphine",
      "nhom": "gây nghiện"
    }
  ]
}

Endpoint

Thuốc phóng xạ (TT20 Phụ lục II)

GET/v1/thuoc-phong-xa

59 thuốc phóng xạ & chất đánh dấu thuộc BHYT (TT20/2022 PL II) — engine nhận là trong danh mục (fix báo nhầm ngoài DM).

Đầu vào

Không có tham số.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{ten, duongDung, dangDung}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" https://tt06byt.com/v1/thuoc-phong-xa

Response

{
  "tong": 59,
  "ket_qua": [
    {
      "ten": "Technetium 99m (Tc-99m)",
      "duongDung": "Tiêm tĩnh mạch"
    }
  ]
}

Endpoint

Thuốc đàm phán giá (TT05/2024)

GET/v1/thuoc-dam-phan-gia

597 thuốc biệt dược gốc/sinh phẩm áp dụng hình thức đàm phán giá (TT05/2024/TT-BYT).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{tenThuoc, hoatChat, hamLuong}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/thuoc-dam-phan-gia?q=tocilizumab"

Response

{
  "tong": 1,
  "ket_qua": [
    {
      "tenThuoc": "Actemra",
      "hoatChat": "Tocilizumab"
    }
  ]
}

Endpoint

Thuốc mua sắm tập trung QG (TT04/2024)

GET/v1/thuoc-mua-sam-tap-trung

50 thuốc thuộc danh mục mua sắm tập trung cấp quốc gia (TT04/2024/TT-BYT).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{hoatChat, hamLuong, dangBaoChe}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/thuoc-mua-sam-tap-trung?q=atorvastatin"

Response

{
  "tong": 1,
  "ket_qua": [
    {
      "hoatChat": "Atorvastatin",
      "hamLuong": "20mg"
    }
  ]
}

Endpoint

Thuốc thu hồi/đình chỉ chất lượng (Cục QLD)

GET/v1/thuoc-thu-hoi

Thuốc bị thu hồi/đình chỉ do vi phạm chất lượng (Cục QLD). loai=SDK: thu hồi toàn bộ theo SĐK (engine tự cảnh báo THU001); loai=LO: thu hồi 1 số lô (tra cứu — hồ sơ BHYT thường không có số lô).

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên/SĐK/số lô.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{sodk, ten, soLo, mucDo, soQD, loai}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/thuoc-thu-hoi?q=ranitidine"

Response

{
  "tong": 1,
  "ket_qua": [
    {
      "sodk": "VN-17188-13",
      "ten": "Aciloc 150",
      "mucDo": "",
      "loai": "SDK"
    }
  ]
}

Endpoint

Thuốc biệt dược gốc (Cục QLD)

GET/v1/thuoc-biet-duoc-goc

523 thuốc biệt dược gốc (tổng hợp QĐ-QLD 2023–2026). Biệt dược gốc thanh toán theo GIÁ CÔNG BỐ, không áp trần đấu thầu generic — tra cứu để đối chiếu giá đúng chuẩn.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên/SĐK/hoạt chất.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{sodk, ten, hoatChat, soQD, nam}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/thuoc-biet-duoc-goc?q=crestor"

Response

{
  "tong": 1,
  "ket_qua": [
    {
      "sodk": "VN-18150-14",
      "ten": "Crestor 10mg",
      "hoatChat": "Rosuvastatin 10mg"
    }
  ]
}

Endpoint

Giá DVKT baseline (TT22/2023)

GET/v1/gia-dvkt

1.053 mã giá dịch vụ kỹ thuật BHYT (TT22/2023/TT-BYT PL III). GIÁ THAM CHIẾU baseline (lương cơ sở 1,8tr); mã theo hệ TT37 (khác mã QĐ2010 ở XML3) — dùng TRA CỨU, không chấm tự động.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên/mã DVKT.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{ma, ten, gia}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/gia-dvkt?q=sieu%20am"

Response

{
  "tong": 1,
  "ket_qua": [
    {
      "ma": "03C4.1.1",
      "ten": "Siêu âm Doppler màu tim/mạch máu",
      "gia": "233000"
    }
  ]
}

Endpoint

DVKT có điều kiện thanh toán (TT39/2024)

GET/v1/dvkt-dieu-kien

63 dịch vụ kỹ thuật có quy định điều kiện/tỷ lệ thanh toán BHYT (TT39/2024 sửa TT35/2016). Nhận diện theo tên — tra cứu đối chiếu.

Tham số query / path

Trường	Kiểu	Bắt buộc	Ý nghĩa & phạm vi giá trị
`q`	`string`	tuỳ chọn	Lọc theo tên DVKT.

Đầu ra application/json

Trường	Kiểu	Ý nghĩa & phạm vi giá trị
`ket_qua[]`	`object`	{tenDvkt, dieuKien, tyLeGia}.
`traceId`	`string`

Ví dụ

Request

curl -H "X-API-Key: sandbox-demo-key" "https://tt06byt.com/v1/dvkt-dieu-kien?q=loc%20mau"

Response

{
  "tong": 3,
  "ket_qua": [
    {
      "tenDvkt": "Lọc máu cấp cứu",
      "dieuKien": "Thực hiện đối với..."
    }
  ]
}

Bộ mã giá trị

Bộ mã giá trị trong XML BHYT

Các bộ mã dùng trong hồ sơ XML QĐ130 để HIS render dropdown, kiểm dữ liệu trước khi gửi cổng, và tra ý nghĩa mã. Truy cập bằng máy: GET /v1/constants và GET /v1/constants/{ma} (công khai). Độ tin cậy: Cao = trích nguyên văn văn bản gốc · Tham khảo = suy từ bản cũ, nên đối chiếu bản hiện hành · Cần kiểm = giá trị ở phụ lục chưa trích được (không liệt kê giá trị suy đoán).

Bộ mã · GIOI_TINH (XML1)

GIOI_TINH Cao

Giới tính người bệnh

Căn cứ: QĐ130/QĐ-BYT Bảng 1 (STT7)

Mã	Ý nghĩa
`1`	Nam
`2`	Nữ
`3`	Chưa xác định

Bộ mã · MA_LOAI_KCB (XML1)

MA_LOAI_KCB Cao

Hình thức khám chữa bệnh

Căn cứ: QĐ1804/QĐ-BYT (19/6/2026, áp dụng chậm nhất 01/8/2026) — Phụ lục 01; bãi bỏ PL1 QĐ824

Mã	Ý nghĩa
`01`	Khám bệnh
`02`	Điều trị ngoại trú
`03`	Điều trị nội trú
`04`	Điều trị ban ngày
`05`	Điều trị ngoại trú bệnh cần chữa trị dài ngày (khám + lĩnh thuốc, TT25/2025 PL I)
`06`	Lưu người bệnh tại PKĐK/PKĐK khu vực/nhà hộ sinh/trạm y tế xã, phường
`07`	Nhận thuốc theo hẹn (không khám bệnh)
`08`	Điều trị ngoại trú bệnh dài ngày (khám + DVKT và/hoặc thuốc)
`09`	Điều trị nội trú dưới 04 giờ
`10`	Các trường hợp khác
`11`	Khám bệnh, chữa bệnh lưu động
`12`	Khám bệnh, chữa bệnh tại nhà
`13`	Khám bệnh, chữa bệnh y học gia đình
`14`	Khám bệnh, chữa bệnh từ xa
`15`	Khám sức khoẻ định kỳ
`16`	Khám sàng lọc

Bộ mã · KET_QUA_DTRI (XML1)

KET_QUA_DTRI Cao

Kết quả điều trị

Căn cứ: QĐ130/QĐ-BYT Bảng 1 (STT40)

QĐ3176/2024 có sửa Bảng 1 — nên đối chiếu bản hiện hành trước khi khoá cứng.

Mã	Ý nghĩa
`1`	Khỏi
`2`	Đỡ
`3`	Không thay đổi
`4`	Nặng hơn
`5`	Tử vong
`6`	Tiên lượng nặng xin về
`7`	Chưa xác định

Bộ mã · MA_LOAI_RV (XML1)

MA_LOAI_RV Cao

Loại/tình trạng ra viện

Căn cứ: QĐ130/QĐ-BYT Bảng 1 (STT41)

Tử vong không nằm ở đây mà ở KET_QUA_DTRI=5. QĐ3176/2024 có sửa Bảng 1 — nên đối chiếu.

Mã	Ý nghĩa
`1`	Ra viện
`2`	Chuyển tuyến theo yêu cầu chuyên môn
`3`	Trốn viện
`4`	Xin ra viện
`5`	Chuyển tuyến theo yêu cầu người bệnh

Bộ mã · MA_DOITUONG_KCB (XML1)

MA_DOITUONG_KCB Cao

Trường hợp đến KCB (nền tảng tính mức hưởng — thay hệ 'tuyến' cũ bằng cấp ban đầu/cơ bản/chuyên sâu theo Luật BHYT 2025)

Căn cứ: QĐ3276/QĐ-BYT (17/10/2025) Phụ lục 1 — bản mới nhất

Xác định sau khi kết thúc KCB; nếu áp được nhiều mã thì chọn mã theo thứ tự từ trên xuống.

Mã	Ý nghĩa	Mức hưởng
`1.1`	Đúng cơ sở đăng ký ban đầu (trừ 1.2)	100%
`1.2`	KCB tại cơ sở cấp ban đầu (TYT, YHGĐ, TTYT huyện…)	100% (không phụ thuộc mức hưởng thẻ)
`1.3`	Có phiếu chuyển cơ sở KCB (kể cả phiếu 1 năm)	100%
`1.4`	Thay đổi nơi lưu trú/cư trú (Đ4 TT01/2025)	100%
`1.5`	Theo phiếu hẹn khám lại (Đ11 TT01/2025)	100%
`1.6`	Người đã hiến bộ phận cơ thể, điều trị ngay sau hiến	100%
`1.7`	Trẻ sơ sinh phải điều trị ngay sau sinh	100%
`1.11`	Tự đến cơ sở cấp ban đầu còn lại (không thuộc 1.2)	100%
`1.12`	Tự đến KCB ngoại trú cơ sở cấp cơ bản <50 điểm	100%
`1.13`	Tự đến KCB ngoại trú cơ sở cấp cơ bản 50–70 điểm	0% (đến 30/6/2026); 50% (từ 01/7/2026)
`1.14`	Tự đến ngoại trú cơ sở cấp cơ bản (trước 2025 là tuyến tỉnh/TW)	0% (đến 30/6/2026); 50% (từ 01/7/2026)
`1.15`	Tự đến KCB nội trú cơ sở cấp cơ bản	100%
`1.16`	Tự đến cơ sở cấp cơ bản với bệnh thuộc Phụ lục II TT01/2025	100%
`1.17`	Tự đến cơ sở cấp chuyên sâu với bệnh thuộc Phụ lục I TT01/2025	100%
`1.18`	Tự đến ngoại trú cơ sở cấp chuyên sâu (trước 2025 là tuyến tỉnh)	0% (đến 30/6/2026); 50% (từ 01/7/2026)
`2`	Cấp cứu	100%
`3.1`	Tự đến cơ sở cấp chuyên sâu (trước 2025 là tuyến TW, trừ 1.17)	40% nội trú; 0% ngoại trú
`3.2`	Tự đến nội trú cơ sở cấp chuyên sâu (trước 2025 là tuyến tỉnh, trừ 1.17)	100%
`3.3`	Tự đến cơ sở cấp cơ bản/chuyên sâu (trước 2025 là tuyến huyện)	100%
`3.6`	DTTS/hộ nghèo vùng KTXH khó khăn…, KCB nội trú cơ sở cấp chuyên sâu	100%
`7`	Lĩnh thuốc theo giấy hẹn khi dịch bệnh nhóm A/bất khả kháng (không khám)	100%
`7.2`	Uỷ quyền người khác đến lĩnh thuốc (TT37/2024, TT26/2025)
`7.3`	Đến lĩnh thuốc tại cơ sở KCB khác (dịch bệnh nhóm A)
`7.4`	Cơ sở KCB chuyển thuốc đến cho người bệnh (dịch bệnh nhóm A)
`8`	Thu hồi đề nghị thanh toán
`9`	Người bệnh KHÔNG KCB BHYT	0%
`10`	Đến cơ sở KCB lĩnh thuốc theo giấy hẹn (không khám, trừ mã 7)	Tuỳ trường hợp

Bộ mã · PHAM_VI (XML2 thuốc / XML3 DVKT-VTYT)

PHAM_VI Cao

Phạm vi hưởng BHYT của dòng chi phí

Căn cứ: QĐ130/QĐ-BYT Bảng 2 (STT16) & Bảng 3 (STT12)

Mã	Ý nghĩa
`1`	Trong phạm vi hưởng BHYT (trong danh mục quỹ chi trả)
`2`	Ngoài phạm vi hưởng BHYT (ngoài danh mục quỹ chi trả)
`3`	Ngoài danh mục quỹ BHYT nhưng chi trả cho quân đội/công an/cơ yếu (NĐ70/2015)

Bộ mã · MA_KHUVUC (XML1)

MA_KHUVUC Cao

Mã khu vực nơi sinh sống của người bệnh ghi trên thẻ BHYT

Căn cứ: QĐ130/QĐ-BYT Bảng 1 (STT58)

Mã	Ý nghĩa
`K1`	Khu vực 1
`K2`	Khu vực 2
`K3`	Khu vực 3

Bộ mã · MUC_HUONG (XML2/XML3)

MUC_HUONG Cao

Mức hưởng của dòng chi phí — GHI SỐ PHẦN TRĂM, không phải bộ mã cố định

Căn cứ: QĐ130/QĐ-BYT Bảng 2 (STT27) & Bảng 3

Đúng tuyến: ghi 80/95/100. Trái tuyến: ghi mức SAU khi nhân hệ số trái tuyến (vd thẻ 80%, nội trú trái tuyến TW hệ số 40% → ghi 32). Miễn cùng chi trả / KCB tại TYT xã / chi phí <15% lương cơ sở → ghi 100.

Không phải bộ mã cố định — xem ghi chú.

Bộ mã · MA_TAI_NAN (XML1)

MA_TAI_NAN Cao

Mã tai nạn thương tích (Số, 1 ký tự 0–9)

Căn cứ: QĐ130 Bảng 1 (STT33) tham chiếu Phụ lục 4 QĐ5937/QĐ-BYT (30/12/2021)

Trích nguyên văn Phụ lục 4 QĐ5937/QĐ-BYT (30/12/2021) — Danh mục mã tai nạn, thương tích.

Mã	Ý nghĩa
`0`	Không xác định
`1`	Tai nạn giao thông
`2`	Tai nạn lao động
`3`	Tai nạn dưới nước
`4`	Bỏng
`5`	Bạo lực, xung đột
`6`	Tự tử
`7`	Ngộ độc các loại
`8`	Khác

Bộ mã · MA_KHOA (XML1)

MA_KHOA Cao

Mã khoa điều trị dùng chung

Căn cứ: QĐ1804/QĐ-BYT (19/6/2026, áp dụng chậm nhất 01/8/2026) — Phụ lục 02; bãi bỏ PL6 QĐ2010

Mã	Ý nghĩa
`K01`	Khoa Khám bệnh
`K02`	Khoa Hồi sức cấp cứu
`K03`	Khoa Nội tổng hợp
`K04`	Khoa Nội tim mạch
`K05`	Khoa Nội tiêu hoá
`K06`	Khoa Nội cơ - xương - khớp
`K07`	Khoa Nội thận - tiết niệu
`K08`	Khoa Nội tiết
`K09`	Khoa Dị ứng
`K10`	Khoa Huyết học lâm sàng
`K11`	Khoa Truyền nhiễm
`K12`	Khoa Lao
`K13`	Khoa Da liễu
`K14`	Khoa Thần kinh
`K15`	Khoa Tâm thần
`K16`	Áp dụng đối với các cơ sở KCB không tách lĩnh vực Y học cổ truyền thành các khoa chuyên môn
`K17`	Hoặc Khoa Lão, Khoa Người cao tuổi
`K18`	Khoa Nhi
`K19`	Khoa Ngoại tổng hợp
`K20`	Khoa Ngoại thần kinh
`K21`	Khoa Ngoại lồng ngực
`K22`	Khoa Ngoại tiêu hoá
`K23`	Khoa Ngoại thận - tiết niệu
`K24`	Khoa Chấn thương chỉnh hình
`K26`	Khoa Phẫu thuật - Gây mê hồi sức
`K27`	Khoa Phụ sản
`K28`	Khoa Tai - Mũi - Họng
`K29`	Khoa Răng - Hàm - Mặt
`K30`	Khoa Mắt
`K31`	Khoa Hồi chức năng và/hoặc Vật lý trị liệu
`K32`	Trường hợp cơ sở KCB không có Khoa Y học hạt nhân riêng thì sử dụng mã “K33”
`K33`	Khoa Ung bướu
`K34`	Khoa Truyền máu
`K35`	Khoa Lọc máu nhân tạo
`K36`	Khoa Huyết học
`K37`	Hoặc Khoa Hoá sinh
`K38`	Khoa Vi sinh
`K39`	Khoa Chẩn đoán hình ảnh
`K40`	Khoa Thăm dò chức năng
`K41`	Khoa Nội soi
`K42`	Khoa Giải phẫu bệnh
`K43`	Hoặc Khoa Chống nhiễm khuẩn
`K44`	Khoa Dược
`K45`	Khoa Dinh dưỡng
`K46`	Khoa Sinh học phân tử
`K47`	Khoa Xét nghiệm
`K48`	Khoa Hồi sức tích cực
`K49`	Khoa Chống độc
`K50`	Khoa Nội hô hấp
`K51`	Khoa Đột quỵ
`K52`	Khoa Phẫu thuật tạo hình thẩm mỹ
`K53`	Khoa Nam học
`K55`	Khoa Y học dưới nước
`K56`	Khoa Hỗ trợ sinh sản
`K57`	Khoa Điều trị ban ngày
`K58`	Khoa Ký sinh trùng
`K59`	Khoa Khám, chữa bệnh theo yêu cầu
`K60`	Khoa Di truyền lâm sàng
`K99`	Khoa Điều trị bệnh truyền nhiễm nhóm A

Bộ mã · MA_NHOM (XML2/XML3)

MA_NHOM_CHIPHI Cao

Nhóm chi phí của dòng thuốc/DVKT/VTYT

Căn cứ: Phụ lục 3 QĐ5937/QĐ-BYT (30/12/2021)

Dịch vụ cận lâm sàng/CĐHA/thăm dò chức năng có phân loại thủ thuật vẫn xếp theo nhóm CLS/CĐHA/TDCN, không xếp vào nhóm thủ thuật.

Mã	Ý nghĩa
`1`	Xét nghiệm
`2`	Chẩn đoán hình ảnh
`3`	Thăm dò chức năng
`4`	Thuốc
`7`	Máu
`8`	Phẫu thuật
`10`	Vật tư y tế
`12`	Vận chuyển
`13`	Khám bệnh
`14`	Ngày giường bệnh ban ngày
`15`	Ngày giường bệnh điều trị nội trú
`16`	Ngày giường lưu
`17`	Chế phẩm máu
`18`	Thủ thuật

Bộ mã · Nhóm đối tượng → mức hưởng

NHOM_DOI_TUONG Cao

Nhóm đối tượng tham gia BHYT và mức hưởng % tương ứng (khi đi KCB đúng quy định)

Căn cứ: Điều 22 Luật BHYT (sửa đổi bởi Luật 51/2024/QH15) + NĐ188/2025 + NĐ161/2026

Khung 3 bậc 100/95/80 giữ nguyên sau Luật 51/2024 (đổi 'tuyến'→'cấp chuyên môn'). Ranh giới một số nhóm (thân nhân người có công, hộ cận nghèo) nên đối chiếu nguyên văn Điều 22.

Mã	Ý nghĩa
`100%`	Người có công · trẻ em dưới 6 tuổi · hộ nghèo · DTTS vùng KTXH khó khăn/đặc biệt khó khăn · xã/huyện đảo · thân nhân liệt sĩ · bảo trợ xã hội · cựu chiến binh · người ≥75 tuổi hưởng trợ cấp tuất; và: KCB tại cơ sở cấp ban đầu, chi phí 1 lần thấp hơn mức quy định, đủ 5 năm liên tục + cùng chi trả trong năm > 6 tháng lương cơ sở
`100% (+)`	Lực lượng vũ trang tại ngũ: quân nhân (QĐND) · công an (CAND) · cơ yếu — 100% kể cả chi phí NGOÀI phạm vi hưởng + chi phí vận chuyển
`95%`	Người hưởng lương hưu/trợ cấp mất sức lao động hàng tháng · thân nhân người có công (nhóm 95%) · hộ cận nghèo
`80%`	Người lao động (doanh nghiệp/HTX) · cán bộ, công chức, viên chức · học sinh, sinh viên · tham gia theo hộ gia đình · các đối tượng khác

Bộ mã · MA_THE_BHYT (15 ký tự)

THE_CAU_TRUC Cao

Cấu trúc mã thẻ BHYT dùng trong trường MA_THE_BHYT của XML QĐ130

Căn cứ: QĐ1351/QĐ-BHXH (2015) + sửa đổi QĐ1697/2023, QĐ1018/2024

Mẫu thẻ vật lý mới (từ 01/4/2021) chỉ in 10 số mã số BHXH, nhưng trường dữ liệu XML vẫn dùng 15 ký tự.

Mã	Ý nghĩa
`ký tự 1–2`	Mã đối tượng (2 chữ, vd HT/TE/GD…) — xem MA_DOITUONG_THE
`ký tự 3`	Mức hưởng (số 1–5) — xem KYTU3_THE
`ký tự 4–5`	Mã tỉnh/thành nơi phát hành thẻ (2 số)
`ký tự 6–15`	Mã số BHXH định danh (10 số)

Bộ mã · 2 ký tự đầu mã thẻ BHYT

MA_DOITUONG_THE Tham khảo

Mã đối tượng (2 chữ) ở đầu mã thẻ — CHỈ liệt kê các mã đối chiếu được nguồn

Căn cứ: QĐ1351/QĐ-BHXH + QĐ1697/2023 + QĐ1018/2024

Nhiều bản 'giải mã thẻ' trôi nổi bịa nghĩa — chỉ dùng mã đã xác thực dưới đây; các mã còn lại cần tra PDF gốc.

Mã	Ý nghĩa
`CC`	Người có công với cách mạng
`TE`	Trẻ em dưới 6 tuổi
`QN`	Quân nhân tại ngũ (QĐND)
`CA`	Sĩ quan/hạ sĩ quan/chiến sĩ Công an nhân dân
`CY`	Người làm công tác cơ yếu
`HT`	Người hưởng lương hưu/trợ cấp mất sức lao động
`DN`	Người lao động trong doanh nghiệp
`HX`	Người lao động trong HTX/liên hiệp HTX
`HS`	Học sinh
`SV`	Sinh viên
`GD`	Tham gia BHYT theo hộ gia đình
`HN`	Người thuộc hộ nghèo
`DT`	Người DTTS sinh sống vùng KTXH khó khăn/đặc biệt khó khăn
`TS`	Thân nhân liệt sĩ
`BT`	Người hưởng trợ cấp bảo trợ xã hội hàng tháng
`KC`	Người tham gia kháng chiến, bảo vệ Tổ quốc
`GB`	Hộ nông/lâm/ngư/diêm nghiệp mức sống trung bình

Bộ mã · Ký tự thứ 3 mã thẻ BHYT

KYTU3_THE Cao

Mức hưởng gắn ký tự thứ 3 của mã thẻ BHYT

Căn cứ: QĐ1351/QĐ-BHXH (2015, sửa đổi QĐ1697/2023, QĐ1018/2024) — KHÔNG thuộc QĐ130

Cơ chế 5 mức đã đối chiếu chéo nhiều nguồn. Trường dữ liệu MA_THE_BHYT trong XML vẫn dùng chuỗi 15 ký tự.

Mã	Ý nghĩa
`1`	100% chi phí KCB, không giới hạn tỷ lệ thuốc/hoá chất/VTYT/DVKT (vd CC, TE)
`2`	100% chi phí KCB, CÓ giới hạn tỷ lệ một số thuốc/DVKT (vd HN, DT, TS, BT, KC)
`3`	95% (100% tại cơ sở cấp ban đầu; 100% nếu chi phí < 15% lương cơ sở) — vd HT
`4`	80% (vd DN, HX, HS, SV, GD)
`5`	100%, không cùng chi trả

Bộ mã · Phân loại kỹ thuật (DVKT)

DVKT_PHAN_LOAI Cao

Phân loại phẫu thuật/thủ thuật của dịch vụ kỹ thuật (dùng cho định mức)

Căn cứ: QĐ2010/2025/QĐ-BYT (định mức kinh tế – kỹ thuật)

Mã	Ý nghĩa
`PT`	Phẫu thuật
`TT`	Thủ thuật
`TDB`	Loại đặc biệt
`T1`	Loại 1
`T2`	Loại 2
`T3`	Loại 3

Bộ mã · Cờ quy tắc trên mã ICD (cột 24–29 danh mục)

ICD_FLAG Cao

6 cờ quy tắc gắn trên mã bệnh ICD-10 dùng để hậu kiểm hồ sơ

Căn cứ: TT06/2026/TT-BYT (danh mục ICD-10 + quy tắc)

Mã	Ý nghĩa
`gioiTinh`	Ràng buộc giới tính (bệnh chỉ ở nam hoặc nữ)
`tuoiMin`	Giới hạn tuổi tối thiểu
`tuoiMax`	Giới hạn tuổi tối đa
`camBenhChinh`	Cấm dùng làm bệnh chính (chỉ được là bệnh kèm)
`maCha`	Mã cha (nhóm 3 ký tự) — không dùng trực tiếp nếu có mã con
`canReview`	Cần rà soát/đối chiếu thêm khi xuất hiện

Bộ mã · 12 bảng chỉ tiêu (XML1–XML12)

XML_BANG Cao

Bộ 12 bảng dữ liệu điện tử KCB BHYT gửi cổng giám định

Căn cứ: QĐ130/QĐ-BYT (18/01/2023) — trích nguyên văn tiêu đề bảng

Mã	Ý nghĩa
`XML1`	Chỉ tiêu tổng hợp khám bệnh, chữa bệnh
`XML2`	Chỉ tiêu chi tiết thuốc
`XML3`	Chỉ tiêu chi tiết dịch vụ kỹ thuật và vật tư y tế
`XML4`	Chỉ tiêu chi tiết dịch vụ cận lâm sàng
`XML5`	Chỉ tiêu chi tiết diễn biến lâm sàng
`XML6`	Chỉ tiêu hồ sơ bệnh án chăm sóc và điều trị HIV/AIDS
`XML7`	Chỉ tiêu dữ liệu giấy ra viện
`XML8`	Chỉ tiêu dữ liệu tóm tắt hồ sơ bệnh án
`XML9`	Chỉ tiêu dữ liệu giấy chứng sinh
`XML10`	Chỉ tiêu dữ liệu giấy chứng nhận nghỉ dưỡng thai
`XML11`	Chỉ tiêu dữ liệu giấy chứng nhận nghỉ việc hưởng BHXH
`XML12`	Chỉ tiêu dữ liệu giám định y khoa

Bộ mã · Chương bệnh ICD-10 (nhóm mã)

ICD_CHUONG Cao

22 chương phân loại bệnh tật quốc tế ICD-10 (khoảng mã đầu → nhóm bệnh)

Căn cứ: ICD-10 (WHO) — danh mục ICD-10 Việt Nam TT06/2026/TT-BYT

Mã	Ý nghĩa
`A00–B99`	Bệnh nhiễm khuẩn và ký sinh vật
`C00–D48`	Khối u (tân sinh)
`D50–D89`	Bệnh máu, cơ quan tạo máu và rối loạn liên quan cơ chế miễn dịch
`E00–E90`	Bệnh nội tiết, dinh dưỡng và chuyển hoá
`F00–F99`	Rối loạn tâm thần và hành vi
`G00–G99`	Bệnh hệ thần kinh
`H00–H59`	Bệnh mắt và phần phụ
`H60–H95`	Bệnh tai và xương chũm
`I00–I99`	Bệnh hệ tuần hoàn
`J00–J99`	Bệnh hệ hô hấp
`K00–K93`	Bệnh hệ tiêu hoá
`L00–L99`	Bệnh da và mô dưới da
`M00–M99`	Bệnh hệ cơ – xương – khớp và mô liên kết
`N00–N99`	Bệnh hệ tiết niệu – sinh dục
`O00–O99`	Thai nghén, sinh đẻ và hậu sản
`P00–P96`	Một số bệnh lý xuất phát trong thời kỳ chu sinh
`Q00–Q99`	Dị tật bẩm sinh, biến dạng và bất thường nhiễm sắc thể
`R00–R99`	Triệu chứng, dấu hiệu và phát hiện bất thường lâm sàng/cận lâm sàng
`S00–T98`	Vết thương, ngộ độc và hậu quả của nguyên nhân bên ngoài
`V01–Y98`	Nguyên nhân bên ngoài của bệnh tật và tử vong
`Z00–Z99`	Yếu tố ảnh hưởng sức khoẻ và tiếp xúc dịch vụ y tế
`U00–U99`	Mã đặc biệt (tình huống mới, vd U07.1 COVID-19)

Bộ mã · severity (kết quả finding)

API_SEVERITY Cao

Mức độ nghiêm trọng của mỗi phát hiện giám định

Căn cứ: Nội bộ engine (ánh xạ mã lỗi K1–K12 + G + định mức)

Mã	Ý nghĩa
`CHAN`	Chặn — nguy cơ bị xuất toán, phải sửa trước khi gửi
`CANHBAO`	Cảnh báo — cần đối chiếu/bổ sung chứng cứ
`GHICHU`	Ghi chú — lưu ý tham khảo, không chặn

Bộ mã · duBao (dự báo tổng hồ sơ)

API_DUBAO Cao

Dự báo khả năng qua cổng giám định của cả hồ sơ

Căn cứ: Nội bộ engine (tổng hợp severity)

Mã	Ý nghĩa
`NGUY_CO_XUAT_TOAN`	Có phát hiện mức Chặn — nguy cơ bị xuất toán
`CAN_DOI_CHIEU`	Có cảnh báo — cần đối chiếu trước khi gửi
`DU_DIEU_KIEN`	Không phát hiện chặn/cảnh báo — đủ điều kiện gửi