Bảng lương hàng loạt và phiếu lương API

Tính lương cả công ty: gross hoặc net, phụ cấp, người phụ thuộc, trần đóng bảo hiểm, thuế TNCN, chi phí doanh nghiệp, file Excel và phiếu lương PDF.

POSThttps://apibox.io.vn/v1/vn-payroll-batch

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

Gửi danh sách nhân viên dạng JSON (employees) hoặc tải file CSV / XLSX có dòng tiêu đề (nhận các cột tiếng Việt như "Họ tên", "Lương", "Số NPT", "Vùng", "Lương đóng BH"). Mỗi dòng được tính theo cùng quy tắc với vn-salary: BHXH, BHYT, BHTN của người lao động (8 / 1,5 / 1 %) trên lương đóng bảo hiểm, có trần 20 lần lương cơ sở (2.530.000 đ từ 1/7/2026) và 20 lần lương tối thiểu vùng; giảm trừ gia cảnh 15,5 triệu và 6,2 triệu mỗi người phụ thuộc, biểu thuế 5 bậc từ 2026; phần doanh nghiệp đóng (17 % + 0,5 % + 3 % + 1 %, tuỳ chọn 2 % kinh phí công đoàn).

Mỗi dòng có thể là lương gross (salary / gross) hoặc net (net: API tự tính ngược ra gross), tính theo ngày công (work_days / standard_days), kèm thưởng, làm thêm giờ (phần miễn thuế), tạm ứng và khấu trừ khác. Phụ cấp gửi qua allowances (mảng { name, amount, taxable, insurance }) hoặc các cột có tiền tố pc_ (chịu thuế), pckct_ (miễn thuế), pcbh_ (tính vào lương đóng bảo hiểm); allowance_rules phân loại lại theo tên. API không tự áp định mức miễn thuế: bạn quyết định khoản nào được miễn.

format=json trả từng dòng và tổng từng cột; format=xlsx trả "Bảng thanh toán tiền lương" sẵn để in (font Times New Roman, dòng tổng, chỗ ký); format=payslips trả file ZIP gồm phiếu lương PDF khổ A5 cho từng người, tiếng Việt hoặc tiếng Anh (font Be Vietnam Pro). Giới hạn: 2.000 dòng, 200 phiếu lương mỗi lần gọi. File chỉ xử lý trong bộ nhớ, không lưu lại.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`employees`	body	array	có		Danh sách nhân viên: [{ name, employee_id?, department?, position?, salary \| gross \| net, dependents?, region?, insurance_salary?, allowances?, work_days?, bonus?, overtime?, advance?, … }]. Hoặc tải `file` (CSV / XLSX).
`file`	body	file	không		File CSV hoặc XLSX có dòng tiêu đề (multipart).
`period`	body	string	không		Tháng tính lương YYYY-MM (mặc định tháng hiện tại). Áp dụng quy định của tháng đó.
`mode`	body	string	không	`gross`	Mặc định cho cột `salary`: gross hoặc net.
`region`	body	number	không	`1`	Vùng lương tối thiểu mặc định 1–4.
`standard_days`	body	number	không	`26`	Số ngày công chuẩn để tính theo ngày công.
`allowance_rules`	body	object	không		{ "Ăn trưa": { "taxable": false, "insurance": false } } để phân loại phụ cấp theo tên.
`union_fund`	body	boolean	không	`false`	Tính thêm 2 % kinh phí công đoàn vào chi phí doanh nghiệp.
`format`	body	string	không	`json`	json, xlsx (bảng lương) hoặc payslips (ZIP phiếu lương PDF).
`company`	body	string	không		Tên công ty in trên bảng lương và phiếu lương.
`lang`	body	string	không	`vi`	Ngôn ngữ phiếu lương: vi hoặc en.

Ví dụ

curl -X POST "https://apibox.io.vn/v1/vn-payroll-batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"2026-11","employees":[{"employee_id":"NV01","name":"Nguyễn Văn An","department":"Kế toán","salary":30000000},{"employee_id":"NV02","name":"Trần Thị Bình","salary":20000000,"dependents":1,"insurance_salary":15000000,"allowances":[{"name":"Ăn trưa","amount":730000,"taxable":false},{"name":"Điện thoại","amount":500000}]}]}'

const res = await fetch('https://apibox.io.vn/v1/vn-payroll-batch', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "period": "2026-11",
    "employees": [
      {
        "employee_id": "NV01",
        "name": "Nguyễn Văn An",
        "department": "Kế toán",
        "salary": 30000000
      },
      {
        "employee_id": "NV02",
        "name": "Trần Thị Bình",
        "salary": 20000000,
        "dependents": 1,
        "insurance_salary": 15000000,
        "allowances": [
          {
            "name": "Ăn trưa",
            "amount": 730000,
            "taxable": false
          },
          {
            "name": "Điện thoại",
            "amount": 500000
          }
        ]
      }
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/vn-payroll-batch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"period": "2026-11", "employees": [{"employee_id": "NV01", "name": "Nguyễn Văn An", "department": "Kế toán", "salary": 30000000}, {"employee_id": "NV02", "name": "Trần Thị Bình", "salary": 20000000, "dependents": 1, "insurance_salary": 15000000, "allowances": [{"name": "Ăn trưa", "amount": 730000, "taxable": False}, {"name": "Điện thoại", "amount": 500000}]}]},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-payroll-batch');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"period":"2026-11","employees":[{"employee_id":"NV01","name":"Nguyễn Văn An","department":"Kế toán","salary":30000000},{"employee_id":"NV02","name":"Trần Thị Bình","salary":20000000,"dependents":1,"insurance_salary":15000000,"allowances":[{"name":"Ăn trưa","amount":730000,"taxable":false},{"name":"Điện thoại","amount":500000}]}]}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "period": "2026-11",
  "source": "json",
  "mode": "gross",
  "employees": 2,
  "totals": {
    "base_salary": 50000000,
    "allowances_total": 1230000,
    "bonus": 0,
    "overtime": 0,
    "gross": 51230000,
    "insurance_salary": 45000000,
    "bhxh": 3600000,
    "bhyt": 675000,
    "bhtn": 450000,
    "non_taxable_income": 730000,
    "family_deduction": 37200000,
    "taxable_income": 11350000,
    "pit": 635000,
    "net": 45870000,
    "advance": 0,
    "other_deductions": 0,
    "take_home": 45870000,
    "er_bhxh": 7650000,
    "er_tnld": 225000,
    "er_bhyt": 1350000,
    "er_bhtn": 450000,
    "er_union": 0,
    "employer_cost": 60905000,
    "employee_insurance": 4725000,
    "employer_insurance": 9675000
  },
  "rows": [
    {
      "no": 1,
      "employee_id": "NV01",
      "name": "Nguyễn Văn An",
      "department": "Kế toán",
      "position": null,
      "email": null,
      "bank_account": null,
      "mode": "gross",
      "region": 1,
      "dependents": 0,
      "resident": true,
      "work_days": null,
      "standard_days": null,
      "base_salary": 30000000,
      "allowances": [],
      "allowances_total": 0,
      "bonus": 0,
      "overtime": 0,
      "gross": 30000000,
      "insurance_salary": 30000000,
      "employee_insurance": {
        "bhxh": 2400000,
        "bhyt": 450000,
        "bhtn": 300000,
        "total": 3150000
      },
      "non_taxable_income": 0,
      "personal_deduction": 15500000,
      "dependent_deduction": 0,
      "taxable_income": 11350000,
      "pit": 635000,
      "net": 26215000,
      "advance": 0,
      "other_deductions": 0,
      "take_home": 26215000,
      "employer": {
        "bhxh": 5100000,
        "tnld_bnn": 150000,
        "bhyt": 900000,
        "bhtn": 300000,
        "union_fund": 0,
        "total": 6450000
      },
      "employer_cost": 36450000,
      "warnings": []
    }
  ],
  "rules": {
    "personal_deduction": 15500000,
    "dependent_deduction": 6200000,
    "deduction_ref": "Nghị quyết 110/2025/UBTVQH15",
    "tax_table": "Luật Thuế TNCN 109/2025/QH15 (5 bậc)",
    "base_salary": 2530000,
    "base_salary_ref": "Nghị định 161/2026/NĐ-CP",
    "insurance_cap_bhxh_bhyt": 50600000,
    "region_min_wage": [
      5310000,
      4730000,
      4140000,
      3700000
    ],
    "region_min_wage_ref": "Nghị định 293/2025/NĐ-CP",
    "employee_rates": {
      "bhxh": 0.08,
      "bhyt": 0.015,
      "bhtn": 0.01
    },
    "employer_rates": {
      "bhxh": 0.17,
      "tnld_bnn": 0.005,
      "bhyt": 0.03,
      "bhtn": 0.01,
      "union_fund": 0
    },
    "allowances": "Allowances are taxable and outside the insurance salary unless classified (non_t…"
  },
  "legal": "Luật Thuế TNCN 109/2025/QH15 and NQ 110/2025/UBTVQH15 (from tax year 2026); Luật BHXH 41/2024/QH15, Luật BHYT, Luật Việc làm (rates and 20× caps); NĐ 161/2026/NĐ-CP (base salary 2,530,000 from 1/7/2026); NĐ 293/2025/NĐ-CP (regional minimum wages 2026).",
  "reviewed": "2026-11-11",
  "disclaimer": "Reference calculation, not legal advice; check the official text."
}

Ứng dụng

Chạy lương tháng cho doanh nghiệp nhỏ từ file Excel
Gửi phiếu lương PDF cho từng nhân viên
Ước tính tổng chi phí doanh nghiệp khi tuyển thêm người
Đối chiếu kết quả của phần mềm nhân sự với một phép tính độc lập

Hỏi đáp

API dùng quy định nào?

Quy định có hiệu lực ở tháng tính lương: thuế TNCN theo Luật 109/2025/QH15 và NQ 110/2025/UBTVQH15 từ 2026, bảo hiểm theo Luật BHXH 2024, lương cơ sở 2.530.000 đ từ 1/7/2026, lương tối thiểu vùng theo NĐ 293/2025/NĐ-CP.

Tiền ăn trưa, điện thoại có được miễn thuế không?

Chỉ khi bạn đánh dấu (taxable: false hoặc cột pckct_). Định mức miễn thuế phụ thuộc quy chế và chứng từ của doanh nghiệp nên API không tự đoán.

Có đặt mật khẩu cho phiếu lương được không?

Chưa: môi trường Workers chưa hỗ trợ mã hoá PDF. Hãy gửi file ZIP qua kênh riêng tư.

API liên quan

{✓}

Bảng lương hàng loạt và phiếu lương 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