HTKK tax return XML & 05-1/BK API

Read HTKK / eTax tax-return XML (01/GTGT, 05/QTT-TNCN…) into JSON with indicator names and checks, or build the 05-1/BK-QTT-TNCN employee list as XLSX.

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

Data & JSON▶ Try it online

action=parse (default) reads the XML of a filed return exported by HTKK or downloaded from the eTax portal: form code and name, circular, original or supplementary, tax period, taxpayer, tax office, every indicator [NN] with its value, the appendices and whether the file carries a signature. Indicator names and arithmetic checks are provided for 01/GTGT (TT 80/2021 and TT 89/2026, from periods starting 1 July 2026, with the new [32b] and [34a]) and 05/QTT-TNCN (TT 80/2021); other forms return codes and values only. Use it to aggregate many periods or clients into a spreadsheet.

action=bk05_1 builds Phụ lục 05-1/BK-QTT-TNCN (resident employees with labour contracts) from JSON / CSV / XLSX rows: name, tax code or ID number, taxable income, insurance, dependants, tax withheld, whether the person authorises the employer to finalise. It validates tax codes (check digit, 12-digit ID numbers), computes the family deduction, [21] taxable income and, for authorising employees, [24] tax payable on the yearly scale of the year (rules from /v1/vn-pit-annual), [25] overpaid, [26] still payable and the totals [28]–[43]. format=xlsx gives the columns in HTKK order ([06]–[27]) to paste into the template of your HTKK version. No submission XML is generated.

Parameters

Name	In	Type	Required	Default
`action`	body\|query	string	no	`parse`	`parse` (read a return XML) or `bk05_1` (build the 05-1/BK list).
`xml`	body	string	no		parse: the return XML (or `file`, or the raw body).
`file`	body	file	no		parse: XML file; bk05_1: XLSX / CSV of employees.
`employees`	body	array	no		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	no		bk05_1: tax year (2024–2027, default last year).
`format`	body\|query	string	no	`json`	bk05_1: `json` or `xlsx`.
`strict`	body\|query	boolean	no	`true`	bk05_1 xlsx: refuse rows with errors (false = export anyway).

Example

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));

Response

{
  "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"
}

Use cases

Summarise VAT returns of many clients from their XML files
Check a return before filing (indicator arithmetic)
Prepare the 05-1/BK list from payroll for the PIT finalisation
Validate employee tax codes before year-end

FAQ

Which form versions are supported?

Indicator names and checks: 01/GTGT (TT 80/2021 and TT 89/2026) and 05/QTT-TNCN (TT 80/2021). Any other HTKK form is parsed into codes and values. 05-1/BK uses the TT 80/2021 column layout [06]–[27].

Can I submit the result to the tax office?

No. The API reads filed returns and prepares the 05-1/BK rows; you import them into HTKK, check and sign the return yourself.

Are personal ID numbers accepted as tax codes?

Yes. Since 1 July 2025 the 12-digit personal identification number is used as the tax code; 10-digit codes are checked with the mod-11 check digit.

Related APIs

{✓}

HTKK tax return XML & 05-1/BK API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON