Tiếng Việt Sign inGet free API key

Vietnam e-invoice XML reader API

Turn a Vietnamese e-invoice XML (QĐ 1450/QĐ-TCT) into clean JSON or CSV: seller, buyer, lines, VAT groups, totals, with arithmetic and symbol checks.

POSThttps://apibox.io.vn/v1/vn-einvoice
Files▶ Try it online

Send the XML file of a Vietnamese electronic invoice (hóa đơn điện tử, the format of QĐ 1450/QĐ-TCT used by every provider: MISA, Viettel, VNPT, BKAV, FPT…). The API reads the HDon / DLHDon structure, also inside the TDiep message wrapper and with namespace prefixes, and returns clean JSON: invoice template, symbol, number and date, currency, the seller and the buyer (name, tax code, address, bank account), each line (code, name, unit, quantity, unit price, discount, amount, VAT rate), the VAT groups, fees and totals, the tax authority code (MCCQT) and the signatures that are present (signer subject, signing time). format=csv returns the lines as CSV for a spreadsheet.

Every invoice is re-checked: quantity × price − discount per line, the sum of lines per VAT rate, VAT = amount × rate, the totals, and the amount in words (TgTTTBChu) read back as a number. The symbol (ký hiệu) such as 1C26TAA is explained part by part (VAT invoice, with a tax authority code, year 2026, registered by the seller…) and checked against the issue year, following TT 91/2026/TT-BTC (same structure as TT 32/2025 and TT 78/2021, plus letter F). Tax codes get a check-digit test.

Signatures are listed, not verified cryptographically, and the invoice is not looked up on the tax authority portal. Files are processed in memory (up to 5 MB) and never stored.

Parameters

NameInTypeRequiredDefault
filebodyfilenoThe invoice XML file (multipart, raw application/xml body or file_base64).
xmlbodystringnoThe XML as a string instead of a file.
formatquery|bodystringnojsonjson or csv (invoice lines, UTF-8 with BOM).

Example

curl -X POST "https://apibox.io.vn/v1/vn-einvoice" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary '<HDon><DLHDon Id="data"><TTChung><PBan>2.1.0</PBan><THDon>HÓA ĐƠN GIÁ TRỊ GIA TĂNG</THDon><KHMSHDon>1</KHMSHDon><KHHDon>C26TAA</KHHDon><SHDon>123</SHDon><NLap>2026-11-10</NLap><DVTTe>VND</DVTTe><HTTToan>TM/CK</HTTToan></TTChung>
<NDHDon><NBan><Ten>CÔNG TY TNHH THƯƠNG MẠI ABC</Ten><MST>0312345673</MST><DChi>12 Nguyễn Huệ, Phường Sài Gòn, TP. Hồ Chí Minh</DChi></NBan>
<NMua><Ten>CÔNG TY CỔ PHẦN XYZ</Ten><MST>0100109106</MST><DChi>1 Tràng Tiền, Phường Hoàn Kiếm, Hà Nội</DChi></NMua>
<DSHHDVu><HHDVu><TChat>1</TChat><STT>1</STT><THHDVu>Máy tính xách tay</THHDVu><DVTinh>Chiếc</DVTinh><SLuong>2</SLuong><DGia>15000000</DGia><ThTien>30000000</ThTien><TSuat>10%</TSuat></HHDVu>
<HHDVu><TChat>1</TChat><STT>2</STT><THHDVu>Dịch vụ cài đặt</THHDVu><DVTinh>Gói</DVTinh><SLuong>1</SLuong><DGia>1500000</DGia><STCKhau>150000</STCKhau><ThTien>1350000</ThTien><TSuat>8%</TSuat></HHDVu></DSHHDVu>
<TToan><THTTLTSuat><LTSuat><TSuat>10%</TSuat><ThTien>30000000</ThTien><TThue>3000000</TThue></LTSuat><LTSuat><TSuat>8%</TSuat><ThTien>1350000</ThTien><TThue>108000</TThue></LTSuat></THTTLTSuat>
<TgTCThue>31350000</TgTCThue><TgTThue>3108000</TgTThue><TgTTTBSo>34458000</TgTTTBSo><TgTTTBChu>Ba mươi tư triệu bốn trăm năm mươi tám nghìn đồng</TgTTTBChu></TToan></NDHDon></DLHDon></HDon>'

Response

{
  "invoice": {
    "name": "HÓA ĐƠN GIÁ TRỊ GIA TĂNG",
    "version": "2.1.0",
    "template": "1",
    "symbol": "C26TAA",
    "number": "123",
    "issue_date": "2026-11-10",
    "currency": "VND",
    "exchange_rate": null,
    "payment_method": "TM/CK",
    "tax_authority_code": null,
    "provider_tax_code": null,
    "id": "data",
    "related_invoice": null
  },
  "symbol_info": {
    "template": "1",
    "symbol": "C26TAA",
    "full": "1C26TAA",
    "valid": true,
    "errors": [],
    "parts": {
      "template": {
        "value": "1",
        "vi": "Hóa đơn giá trị gia tăng",
        "en": "VAT invoice"
      },
      "authority_code": {
        "value": "C",
        "vi": "Hóa đơn có mã của cơ quan thuế",
        "en": "With a tax authority code"
      },
      "year": {
        "value": "26",
        "year": 2026
      },
      "type": {
        "value": "T",
        "vi": "Hóa đơn do doanh nghiệp, tổ chức, hộ, cá nhân kinh doanh đăng ký sử dụng với cơ quan thuế",
        "en": "Invoice registered with the tax authority by the seller"
      },
      "seller_code": {
        "value": "AA",
        "note": "Chosen by the seller to manage its invoice series"
      }
    }
  },
  "seller": {
    "name": "CÔNG TY TNHH THƯƠNG MẠI ABC",
    "tax_code": "0312345673",
    "tax_code_check": {
      "valid": true,
      "kind": "organisation"
    },
    "address": "12 Nguyễn Huệ, Phường Sài Gòn, TP. Hồ Chí Minh"
  },
  "buyer": {
    "name": "CÔNG TY CỔ PHẦN XYZ",
    "tax_code": "0100109106",
    "tax_code_check": {
      "valid": true,
      "kind": "organisation"
    },
    "address": "1 Tràng Tiền, Phường Hoàn Kiếm, Hà Nội"
  },
  "lines": [
    {
      "no": 1,
      "kind": "1",
      "kind_name": "goods/service",
      "code": null,
      "name": "Máy tính xách tay",
      "unit": "Chiếc",
      "quantity": 2,
      "unit_price": 15000000,
      "discount_rate": null,
      "discount_amount": null,
      "amount": 30000000,
      "vat_rate": "10%",
      "vat_amount": null
    },
    {
      "no": 2,
      "kind": "1",
      "kind_name": "goods/service",
      "code": null,
      "name": "Dịch vụ cài đặt",
      "unit": "Gói",
      "quantity": 1,
      "unit_price": 1500000,
      "discount_rate": null,
      "discount_amount": 150000,
      "amount": 1350000,
      "vat_rate": "8%",
      "vat_amount": null
    }
  ],
  "vat_groups": [
    {
      "vat_rate": "10%",
      "taxable_amount": 30000000,
      "vat_amount": 3000000
    },
    {
      "vat_rate": "8%",
      "taxable_amount": 1350000,
      "vat_amount": 108000
    }
  ],
  "fees": [],
  "totals": {
    "before_vat": 31350000,
    "vat": 3108000,
    "fees": null,
    "trade_discount": null,
    "total": 34458000,
    "total_in_words": "Ba mươi tư triệu bốn trăm năm mươi tám nghìn đồng"
  },
  "signatures": {
    "seller": null,
    "buyer": null,
    "tax_authority": null,
    "note": "Signatures are listed, not verified cryptographically."
  },
  "valid": false,
  "failed_checks": 1,
  "checks": [
    {
      "check": "line 1: quantity × unit price − discount = amount",
      "ok": true,
      "expected": 30000000,
      "actual": 30000000
    },
    {
      "check": "VAT 8%: amount × rate = VAT",
      "ok": true,
      "expected": 108000,
      "actual": 108000
    },
    {
      "check": "total = before VAT + VAT + fees",
      "ok": true,
      "expected": 34458000,
      "actual": 34458000
    },
    {
      "check": "amount in words matches the total",
      "ok": true,
      "expected": "Ba mươi tư triệu bốn trăm năm mươi tám nghìn đồng",
      "actual": "Ba mươi tư triệu bốn trăm năm mươi tám nghìn đồng",
      "message": "words read as 34458000"
    },
    {
      "check": "invoice symbol (ký hiệu) is well formed",
      "ok": true,
      "actual": "1C26TAA"
    },
    {
      "check": "invoice with tax authority code carries <MCCQT>",
      "ok": false,
      "message": "No MCCQT element (the file may be the seller copy before the tax authority code was granted)"
    }
  ],
  "legal_basis": "Thông tư 91/2026/TT-BTC (from 01/07/2026; same symbol structure as TT 32/2025 and TT 78/2021) and NĐ 254/2026/NĐ-CP; XML: QĐ 1450/QĐ-TCT (amended by QĐ 1510/QĐ-TCT)",
  "reviewed": "2026-11-11"
}

Use cases

  • Import purchase invoices into accounting software
  • Check supplier invoices before booking them
  • Export invoice lines to Excel for reconciliation
  • Index archived invoices by seller, date and amount

FAQ

Which providers are supported?

All that follow QĐ 1450/QĐ-TCT (the tax authority format). Provider-specific fields in TTKhac are returned as extra key / value pairs.

Is the digital signature verified?

No. The API lists the signatures present (subject, time, algorithm) but does not validate the certificate chain or the XML digest.

What does a failed check mean?

A total that does not add up within rounding (1 VND per line), a symbol whose year differs from the issue date, a tax code with a wrong check digit or amount-in-words that does not match the number.

Related APIs

EXIF

Image Metadata & EXIF

Read image dimensions, format, EXIF camera data, capture settings and GPS location from JPEG, PNG, WebP, HEIC, AVIF, GIF and more – upload or URL.

PDF

PDF Metadata

Read PDF metadata: page count, title, author, creator, producer, dates, PDF version, encryption, form fields and the size of each page (A4, Letter…).

PDF₫

Quote & Receipt PDF

Generate clean PDF quotations, receipts, orders and simple invoices from JSON, with Vietnamese text, VAT, totals in words and a VietQR code for payment.

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