Đọc XML tờ khai thuế, bảng kê 05-1/BK API

Đọc XML tờ khai thuế HTKK / eTax (01/GTGT, 05/QTT-TNCN…) thành JSON có tên chỉ tiêu và kiểm tra, hoặc lập bảng kê 05-1/BK-QTT-TNCN dạng XLSX.

POSThttps://apibox.io.vn/v1/vn-tax-form-xml

Dữ liệu & JSON▶ Dùng thử online

action=parse (mặc định) đọc file XML tờ khai đã nộp, xuất từ HTKK hoặc tải từ cổng eTax: mã và tên mẫu, thông tư, tờ khai chính thức hay bổ sung, kỳ tính thuế, người nộp thuế, cơ quan thuế, từng chỉ tiêu [NN] và giá trị, các phụ lục và file có chữ ký số hay không. Tên chỉ tiêu và kiểm tra số học có cho 01/GTGT (TT 80/2021 và TT 89/2026, áp dụng từ kỳ tính thuế 01/7/2026, có chỉ tiêu mới [32b], [34a]) và 05/QTT-TNCN (TT 80/2021); các mẫu khác trả mã chỉ tiêu và giá trị. Dùng để tổng hợp nhiều kỳ hoặc nhiều khách hàng vào bảng tính.

action=bk05_1 lập Phụ lục 05-1/BK-QTT-TNCN (cá nhân cư trú có hợp đồng lao động) từ các dòng JSON / CSV / XLSX: họ tên, mã số thuế hoặc số định danh, thu nhập chịu thuế, bảo hiểm, số người phụ thuộc, thuế đã khấu trừ, có ủy quyền quyết toán hay không. API kiểm tra mã số thuế (số kiểm tra, số định danh 12 chữ số), tính giảm trừ gia cảnh, thu nhập tính thuế [21] và với người ủy quyền: thuế phải nộp [24] theo biểu lũy tiến năm year (lấy từ /v1/vn-pit-annual), nộp thừa [25], còn phải nộp [26] và các chỉ tiêu tổng [28]–[43]. format=xlsx trả các cột theo thứ tự HTKK ([06]–[27]) để dán vào mẫu bảng kê của phiên bản HTKK bạn dùng. API không sinh file XML để nộp.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`action`	body\|query	string	không	`parse`	`parse` (đọc XML tờ khai) hoặc `bk05_1` (lập bảng kê 05-1/BK).
`xml`	body	string	không		parse: nội dung XML tờ khai (hoặc `file`, hoặc body thô).
`file`	body	file	không		parse: file XML; bk05_1: file XLSX / CSV danh sách nhân viên.
`employees`	body	array	không		bk05_1: `[{"name":"Nguyễn Văn A","tax_code":"8000000004","taxable_income":300000000,"insurance":25200000,"dependants":1,"tax_withheld":6000000,"authorized":true}]`.
`year`	body\|query	number	không		bk05_1: năm quyết toán (2024–2027, mặc định năm trước).
`format`	body\|query	string	không	`json`	bk05_1: `json` hoặc `xlsx`.
`strict`	body\|query	boolean	không	`true`	bk05_1 xlsx: từ chối khi có dòng lỗi (false = vẫn xuất).

Ví dụ

curl -X POST "https://apibox.io.vn/v1/vn-tax-form-xml" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary '<HSoThueDTu><HSoKhaiThue><TTinChung><TTinTKhaiThue><TKhaiThue><maTKhai>842</maTKhai><tenTKhai>TỜ KHAI THUẾ GIÁ TRỊ GIA TĂNG (Mẫu số 01/GTGT)</tenTKhai><moTaBMau>(Ban hành kèm theo Thông tư số 89/2026/TT-BTC…)</moTaBMau><loaiTKhai>C</loaiTKhai><KyKKhaiThue><kieuKy>M</kieuKy><kyKKhai>08/2026</kyKKhai></KyKKhaiThue></TKhaiThue><NNT><mst>0100109106</mst><tenNNT>CÔNG TY TNHH DEMO</tenNNT></NNT></TTinTKhaiThue></TTinChung><CTieuTKhaiChinh><ct22>5000000</ct22><ct25>20000000</ct25>…<ct40>5000000</ct40></CTieuTKhaiChinh></HSoKhaiThue></HSoThueDTu>'

const res = await fetch('https://apibox.io.vn/v1/vn-tax-form-xml', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/xml',
  },
  body: "<HSoThueDTu><HSoKhaiThue><TTinChung><TTinTKhaiThue><TKhaiThue><maTKhai>842</maTKhai><tenTKhai>TỜ KHAI THUẾ GIÁ TRỊ GIA TĂNG (Mẫu số 01/GTGT)</tenTKhai><moTaBMau>(Ban hành kèm theo Thông tư số 89/2026/TT-BTC…)</moTaBMau><loaiTKhai>C</loaiTKhai><KyKKhaiThue><kieuKy>M</kieuKy><kyKKhai>08/2026</kyKKhai></KyKKhaiThue></TKhaiThue><NNT><mst>0100109106</mst><tenNNT>CÔNG TY TNHH DEMO</tenNNT></NNT></TTinTKhaiThue></TTinChung><CTieuTKhaiChinh><ct22>5000000</ct22><ct25>20000000</ct25>…<ct40>5000000</ct40></CTieuTKhaiChinh></HSoKhaiThue></HSoThueDTu>",
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/vn-tax-form-xml",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/xml"},
    data="<HSoThueDTu><HSoKhaiThue><TTinChung><TTinTKhaiThue><TKhaiThue><maTKhai>842</maTKhai><tenTKhai>TỜ KHAI THUẾ GIÁ TRỊ GIA TĂNG (Mẫu số 01/GTGT)</tenTKhai><moTaBMau>(Ban hành kèm theo Thông tư số 89/2026/TT-BTC…)</moTaBMau><loaiTKhai>C</loaiTKhai><KyKKhaiThue><kieuKy>M</kieuKy><kyKKhai>08/2026</kyKKhai></KyKKhaiThue></TKhaiThue><NNT><mst>0100109106</mst><tenNNT>CÔNG TY TNHH DEMO</tenNNT></NNT></TTinTKhaiThue></TTinChung><CTieuTKhaiChinh><ct22>5000000</ct22><ct25>20000000</ct25>…<ct40>5000000</ct40></CTieuTKhaiChinh></HSoKhaiThue></HSoThueDTu>".encode(),
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-tax-form-xml');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/xml'],
    CURLOPT_POSTFIELDS => '<HSoThueDTu><HSoKhaiThue><TTinChung><TTinTKhaiThue><TKhaiThue><maTKhai>842</maTKhai><tenTKhai>TỜ KHAI THUẾ GIÁ TRỊ GIA TĂNG (Mẫu số 01/GTGT)</tenTKhai><moTaBMau>(Ban hành kèm theo Thông tư số 89/2026/TT-BTC…)</moTaBMau><loaiTKhai>C</loaiTKhai><KyKKhaiThue><kieuKy>M</kieuKy><kyKKhai>08/2026</kyKKhai></KyKKhaiThue></TKhaiThue><NNT><mst>0100109106</mst><tenNNT>CÔNG TY TNHH DEMO</tenNNT></NNT></TTinTKhaiThue></TTinChung><CTieuTKhaiChinh><ct22>5000000</ct22><ct25>20000000</ct25>…<ct40>5000000</ct40></CTieuTKhaiChinh></HSoKhaiThue></HSoThueDTu>',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "form": "01/GTGT",
  "form_code": "842",
  "form_name": "TỜ KHAI THUẾ GIÁ TRỊ GIA TĂNG (Mẫu số 01/GTGT)",
  "circular": "89/2026/TT-BTC",
  "xml_version": "2.7.0",
  "kind": "original",
  "amendment_no": "0",
  "period": {
    "type": "M",
    "period": "08/2026",
    "from": "01/08/2026",
    "to": "31/08/2026"
  },
  "taxpayer": {
    "tax_code": "0100109106",
    "name": "CÔNG TY TNHH DEMO",
    "address": "1 Tràng Tiền",
    "province": "Hà Nội",
    "phone": null,
    "email": null
  },
  "names_supported": true,
  "indicators": [
    {
      "code": "[22]",
      "name_vi": "Thuế GTGT còn được khấu trừ kỳ trước chuyển sang",
      "value": 5000000
    },
    {
      "code": "[25]",
      "name_vi": "Tổng số thuế GTGT được khấu trừ kỳ này",
      "value": 20000000
    },
    {
      "code": "[36]",
      "name_vi": "Thuế GTGT phát sinh trong kỳ",
      "value": 10000000
    },
    {
      "code": "[40]",
      "name_vi": "Thuế GTGT còn phải nộp trong kỳ",
      "value": 5000000
    }
  ],
  "checks": [
    {
      "check": "[28] = [31] + [33]",
      "ok": true,
      "expected": 30000000,
      "actual": 30000000
    },
    {
      "check": "[36] = [35] − [25]",
      "ok": true,
      "expected": 10000000,
      "actual": 10000000
    }
  ],
  "signed": true,
  "reviewed": "2026-11-11"
}

Ứng dụng

Tổng hợp tờ khai GTGT của nhiều khách hàng từ file XML
Kiểm tra số học tờ khai trước khi nộp
Lập bảng kê 05-1/BK từ bảng lương để quyết toán TNCN
Kiểm tra mã số thuế nhân viên trước kỳ quyết toán

Hỏi đáp

Hỗ trợ những phiên bản mẫu nào?

Tên chỉ tiêu và kiểm tra: 01/GTGT (TT 80/2021 và TT 89/2026) và 05/QTT-TNCN (TT 80/2021). Mọi mẫu HTKK khác được đọc thành mã chỉ tiêu và giá trị. Bảng kê 05-1/BK theo bố cục cột [06]–[27] của TT 80/2021.

Có nộp thẳng kết quả cho cơ quan thuế được không?

Không. API chỉ đọc tờ khai đã nộp và chuẩn bị các dòng bảng kê 05-1/BK; bạn nhập vào HTKK, kiểm tra và ký số tờ khai.

Số định danh cá nhân có dùng thay mã số thuế được không?

Có. Từ 01/7/2025 số định danh cá nhân 12 chữ số được dùng làm mã số thuế; mã 10 chữ số được kiểm tra bằng chữ số kiểm tra mod 11.

API liên quan

{✓}

Đọc XML tờ khai thuế, bảng kê 05-1/BK API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Kiểm tra JSON

Định dạng JSON

CSV sang JSON