Tiếng Việt Sign inGet free API key

BHYT XML 130/4750 Validator (VN) API

Check the health-insurance assessment XML (QĐ 130/4750/3176/1931) before sending: envelope, base64 tables, fields, codes, formulas and XML1 totals.

POSThttps://apibox.io.vn/v1/vn-bhyt-xml
Data & JSON▶ Try it online

Send the GIAMDINHHS file (as xml, a raw XML body or a multipart file) or a single table (e.g. <TONG_HOP>). The API decodes every FILEHOSO (XML1–XML11, XML13–XML15, base64) and checks it against the schema of QĐ 130/QĐ-BYT as amended by QĐ 4750/QĐ-BYT, QĐ 3176/QĐ-BYT and QĐ 1931/QĐ-BYT (from 1/7/2026): required fields, numbers with a dot separator, maximum lengths, yyyyMMddHHmm / yyyyMMdd dates, code lists (MA_LOAI_KCB, KET_QUA_DTRI, MA_LOAI_RV, GIOI_TINH, PHAM_VI…), ICD-10 format, BHYT card codes with matching MA_DKBD / GT_THE_* lists, 5-character facility codes and NGAY_VAO ≤ NGAY_RA.

Cross-checks: MA_LK identical in every table of a HOSO, STT sequences, the QĐ 3176 line formulas of XML2 / XML3 (THANH_TIEN_BV, THANH_TIEN_BH, T_BHTT, T_BNTT, T_BNCCT) as warnings, and the XML1 totals (T_THUOC, T_VTYT, T_TONGCHI_BV, T_TONGCHI_BH, T_BNTT, T_BNCCT, T_BHTT, T_NGUONKHAC, T_BHTT_GDV) against the sums of XML2 + XML3 as errors, with a tolerance of 1 VND per 10 lines (tolerance). Every problem comes with HOSO, MA_LK, table, row, field and a code. list=schema returns the field tables; include_data=true returns the decoded tables as JSON.

This is a pre-submission check: the BHXH assessment rules are more detailed and not all public, so a clean result does not guarantee acceptance. Files are processed in memory and never stored.

Parameters

NameInTypeRequiredDefault
xmlbodystringyesGIAMDINHHS envelope or one table; or a raw XML body / multipart file.
filebodyfilenoThe XML file (multipart).
tolerancebodynumberno1Rounding tolerance in VND per line.
include_databodybooleannofalseReturn the decoded tables.
listbodystringnoschema: return the field tables (with table=XML1…).

Example

curl -X POST "https://apibox.io.vn/v1/vn-bhyt-xml" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xml":"<TONG_HOP><MA_LK>LK0001</MA_LK><STT>1</STT><MA_BN>BN01</MA_BN><HO_TEN>Nguyễn Văn An</HO_TEN><NGAY_SINH>199003150000</NGAY_SINH><GIOI_TINH>1</GIOI_TINH><MA_QUOCTICH>000</MA_QUOCTICH><MA_DANTOC>01</MA_DANTOC><MA_NGHE_NGHIEP>00</MA_NGHE_NGHIEP><MA_THE_BHYT>DN4797931234567</MA_THE_BHYT><MA_DKBD>79001</MA_DKBD><GT_THE_TU>20260101</GT_THE_TU><GT_THE_DEN>20261231</GT_THE_DEN><MA_BENH_CHINH>J18.9</MA_BENH_CHINH><MA_DOITUONG_KCB>1</MA_DOITUONG_KCB><NGAY_VAO>202611100800</NGAY_VAO><NGAY_RA>202611091000</NGAY_RA><SO_NGAY_DTRI>1</SO_NGAY_DTRI><KET_QUA_DTRI>1</KET_QUA_DTRI><MA_LOAI_RV>1</MA_LOAI_RV><T_THUOC>50000</T_THUOC><T_VTYT>0</T_VTYT><T_TONGCHI_BV>88700</T_TONGCHI_BV><T_TONGCHI_BH>88700</T_TONGCHI_BH><T_BNTT>0</T_BNTT><T_BNCCT>17740</T_BNCCT><T_BHTT>70960</T_BHTT><T_NGUONKHAC>0</T_NGUONKHAC><T_BHTT_GDV>70960</T_BHTT_GDV><NAM_QT>2026</NAM_QT><THANG_QT>11</THANG_QT><MA_LOAI_KCB>1</MA_LOAI_KCB><MA_KHOA>K01</MA_KHOA><MA_CSKCB>79001</MA_CSKCB><MA_TTDV>000123/HCM-GPHN</MA_TTDV></TONG_HOP>"}'

Response

{
  "version": "QĐ 130/QĐ-BYT as amended by QĐ 4750/QĐ-BYT, QĐ 3176/QĐ-BYT and QĐ 1931/QĐ-BYT (from 01/07/2026)",
  "valid": false,
  "error_count": 2,
  "warning_count": 0,
  "envelope": null,
  "hoso": [
    {
      "hoso": 1,
      "ma_lk": "LK0001",
      "tables": {
        "XML1": 1
      }
    }
  ],
  "errors": [
    {
      "hoso": 1,
      "ma_lk": "LK0001",
      "row": null,
      "table": "XML1",
      "field": "MA_LOAI_KCB",
      "code": "invalid_code",
      "message": "MA_LOAI_KCB must be one of 01, 02, 03, 04, 05, 06, 07, 08, 09"
    },
    {
      "hoso": 1,
      "ma_lk": "LK0001",
      "row": null,
      "table": "XML1",
      "field": "NGAY_RA",
      "code": "date_order",
      "message": "NGAY_RA is before NGAY_VAO"
    }
  ],
  "warnings": [],
  "truncated": false,
  "checks": "Structure, required fields, types, lengths, date formats, code lists, ICD-10 and BHYT card format, MA_LK consistency, line formulas (QĐ 3176) and XML1 totals against XML2 + XML3.",
  "legal": [
    {
      "ref": "QĐ 130/QĐ-BYT (18/01/2023)",
      "effective_from": "2023-01-18"
    },
    {
      "ref": "QĐ 4750/QĐ-BYT (29/12/2023)",
      "effective_from": "2024-07-01"
    }
  ],
  "reviewed": "2026-11-11",
  "disclaimer": "Pre-submission check only: the BHXH assessment rules are more detailed and not all public; passing here does not guarantee acceptance. Not legal advice; check the official text."
}

Use cases

  • Validate XML exports of a clinic system before sending them to BHXH
  • Find which line breaks the XML1 totals
  • Test a new HIS integration against QĐ 4750 / 3176
  • Convert the base64 tables of a GIAMDINHHS file to JSON

FAQ

Which version is implemented?

QĐ 130/QĐ-BYT with QĐ 4750 (1/7/2024), QĐ 3176 (1/1/2025) and the verified part of QĐ 1931/QĐ-BYT (MUC_HUONG size 4, from 1/7/2026).

Does it check drug and service codes against the catalogues?

No: codes are checked for format only. Catalogue lookups (drugs, services, departments, doctors) need the facility’s registered lists.

Is the digital signature verified?

No: the response only says whether CHUKYDONVI is present.

Related APIs

{✓}

JSON Validator

Check JSON syntax with exact line and column of errors, and validate data against a JSON Schema (draft 4, 7, 2019-09 or 2020-12).

{ }

JSON Formatter

Pretty print JSON with 0-8 spaces or tabs, minify it, or sort object keys recursively. Syntax errors are reported with line and column.

CSV

CSV to JSON

Convert CSV into an array of JSON objects using the header row, with delimiter auto-detection, number and boolean typing, and row-level errors.

Start with 1,000 free requests every month. Get free API key →