Mẫu BHXH D02-LT, TK1-TS API

Sinh mẫu D02-LT (danh sách tham gia) và TK1-TS (tờ khai) theo QĐ 366/QĐ-BHXH dạng Excel, kèm kiểm tra lỗi từng dòng.

POSThttps://apibox.io.vn/v1/vn-bhxh-forms

Gửi danh sách từ phần mềm nhân sự (JSON hoặc file CSV / XLSX), API trả file Excel trình bày như mẫu ban hành kèm QĐ 366/QĐ-BHXH (29/4/2026, hiệu lực 1/5/2026, thay QĐ 595): form=d02-lt tạo "Danh sách tham gia, điều chỉnh đóng BHXH, BHYT, BHTN" đủ 21 cột (tiền lương, phụ cấp, loại HĐLĐ, từ tháng / đến tháng, nơi KCB ban đầu, loại tăng giảm…) với dòng tiêu đề gộp ô; form=tk1-ts tạo mỗi người một sheet "Tờ khai đăng ký, điều chỉnh thông tin tham gia BHXH, BHYT" gồm các chỉ tiêu [01] đến [17].

Từng dòng được kiểm tra: mã số BHXH 10 chữ số, số định danh cá nhân 12 chữ số, ngày tháng hợp lệ (DD/MM/YYYY), khoảng tháng, mã loại tăng giảm (TM, ON, TC, TD, GH, KL, TS, OF, DC…), tiền lương cộng phụ cấp không thấp hơn lương tối thiểu vùng của đơn vị (unit.region hoặc mã phường xã, NĐ 293/2025/NĐ-CP) và cảnh báo khi vượt trần 20 lần lương cơ sở. format=json trả lỗi theo dòng và trường (kèm file base64); strict=true từ chối tạo file khi còn lỗi (422).

Mẫu D02-TS không còn trong QĐ 366 (danh sách hộ gia đình chuyển sang NĐ 188/2025/NĐ-CP). Bố cục cột theo mẫu kèm QĐ 366 do các đơn vị I-VAN công bố, vì bản scan chính thức chỉ liệt kê danh mục mẫu; hãy kiểm tra thêm yêu cầu của cơ quan BHXH địa phương.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`form`	body	string	không	`d02-lt`	d02-lt hoặc tk1-ts.
`rows`	body	array	có		D02-LT: [{ name, bhxh_code \| id_number, birth_date, position?, salary, allowance_position?, seniority_vk?, seniority_job?, other_allowances?, contract_type (indefinite\|fixed\|other), contract_date?, from_month, to_month?, health_facility?, result_delivery?, change_type, note? }]; TK1-TS: [{ name, sex, birth_date, id_number, ethnicity?, nationality?, phone?, email?, health_facility?, result_delivery?, address?, contribution?, payment_method?, change_request? }]. Hoặc tải `file`.
`unit`	body	object	không		{ name, code, number?, region (1–4) hoặc ward_code + province_code }.
`date`	body	string	không		Ngày lập (mặc định hôm nay).
`format`	body	string	không	`xlsx`	xlsx (file) hoặc json (báo cáo kiểm tra + xlsx_base64).
`include_file`	body	boolean	không	`true`	Định dạng JSON: kèm xlsx_base64.
`strict`	body	boolean	không	`false`	Trả lỗi 422 thay vì file khi còn lỗi.

Ví dụ

curl -X POST "https://apibox.io.vn/v1/vn-bhxh-forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form":"d02-lt","format":"json","include_file":false,"unit":{"name":"Công ty TNHH Ví Dụ","code":"TA1234A","region":1},"rows":[{"name":"Nguyễn Văn An","id_number":"001090012345","birth_date":"15/03/1990","position":"Kế toán viên","salary":8000000,"contract_type":"fixed","contract_date":"01/11/2026","from_month":"11/2026","change_type":"TM"},{"name":"Trần Thị Bình","bhxh_code":"7912345678","birth_date":"20/05/1995","salary":4000000,"from_month":"11/2026","change_type":"DC"}]}'

const res = await fetch('https://apibox.io.vn/v1/vn-bhxh-forms', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "form": "d02-lt",
    "format": "json",
    "include_file": false,
    "unit": {
      "name": "Công ty TNHH Ví Dụ",
      "code": "TA1234A",
      "region": 1
    },
    "rows": [
      {
        "name": "Nguyễn Văn An",
        "id_number": "001090012345",
        "birth_date": "15/03/1990",
        "position": "Kế toán viên",
        "salary": 8000000,
        "contract_type": "fixed",
        "contract_date": "01/11/2026",
        "from_month": "11/2026",
        "change_type": "TM"
      },
      {
        "name": "Trần Thị Bình",
        "bhxh_code": "7912345678",
        "birth_date": "20/05/1995",
        "salary": 4000000,
        "from_month": "11/2026",
        "change_type": "DC"
      }
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/vn-bhxh-forms",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"form": "d02-lt", "format": "json", "include_file": False, "unit": {"name": "Công ty TNHH Ví Dụ", "code": "TA1234A", "region": 1}, "rows": [{"name": "Nguyễn Văn An", "id_number": "001090012345", "birth_date": "15/03/1990", "position": "Kế toán viên", "salary": 8000000, "contract_type": "fixed", "contract_date": "01/11/2026", "from_month": "11/2026", "change_type": "TM"}, {"name": "Trần Thị Bình", "bhxh_code": "7912345678", "birth_date": "20/05/1995", "salary": 4000000, "from_month": "11/2026", "change_type": "DC"}]},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-bhxh-forms');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"form":"d02-lt","format":"json","include_file":false,"unit":{"name":"Công ty TNHH Ví Dụ","code":"TA1234A","region":1},"rows":[{"name":"Nguyễn Văn An","id_number":"001090012345","birth_date":"15/03/1990","position":"Kế toán viên","salary":8000000,"contract_type":"fixed","contract_date":"01/11/2026","from_month":"11/2026","change_type":"TM"},{"name":"Trần Thị Bình","bhxh_code":"7912345678","birth_date":"20/05/1995","salary":4000000,"from_month":"11/2026","change_type":"DC"}]}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "form": "D02-LT",
  "rows": 2,
  "valid": false,
  "error_count": 1,
  "warning_count": 0,
  "errors": [
    {
      "row": 2,
      "field": "salary",
      "code": "below_minimum_wage",
      "message": "Salary + allowances 4,000,000 is below the region I minimum wage 5,310,000 (NĐ 293/2025/NĐ-CP)"
    }
  ],
  "warnings": [],
  "minimum_wage": {
    "region": "I",
    "amount": 5310000,
    "decree": "293/2025/NĐ-CP"
  },
  "legal": {
    "decision": "366/QĐ-BHXH",
    "signed": "2026-04-29",
    "effective_from": "2026-05-01",
    "replaces": "595/QĐ-BHXH (2017) and amendments",
    "template_source": "Templates attached to QĐ 366 as published by I-VAN providers (the official scan lists the forms only)",
    "reviewed": "2026-11-11"
  },
  "filename": "D02-LT-2026-11-11.xlsx",
  "disclaimer": "Reference template, not legal advice; check the official text and your BHXH office requirements."
}

Ứng dụng

Xuất danh sách tăng giảm lao động hằng tháng từ phần mềm nhân sự
Phát hiện sai mã BHXH, lương dưới tối thiểu vùng trước khi nộp
In tờ khai TK1-TS cho nhân viên mới trong một lần gọi
Chuẩn bị dữ liệu để nhập tay vào phần mềm BHXH điện tử

Hỏi đáp

API dùng mẫu theo văn bản nào?

QĐ 366/QĐ-BHXH ngày 29/4/2026, hiệu lực từ 1/5/2026, thay thế QĐ 595/QĐ-BHXH và các quyết định sửa đổi.

File có nhập thẳng vào phần mềm BHXH được không?

File theo mẫu giấy. Phần mềm I-VAN có định dạng nhập riêng, nên hãy dùng để in hoặc làm nguồn nhập liệu.

Lương tối thiểu vùng được kiểm tra thế nào?

Tiền lương cộng phụ cấp chức vụ và phụ cấp khác phải từ mức lương tối thiểu vùng của đơn vị tại ngày lập; truyền unit.region (1–4) hoặc unit.ward_code.

API liên quan

{✓}

Mẫu BHXH D02-LT, TK1-TS 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