MAXMIN API reference

OpenAPI 3.1.0 · version 1.0.0 · generated 27/09/2026

Base URL https://api.maxmin.vn (also https://maxmin.vn/v1/...). JSON in, JSON out. Machine-readable spec: OpenAPI 3.1. Field names are Vietnamese identifiers and stay stable; descriptions below come from the spec (Vietnamese).

Every calculation takes ngay_ap_dung (YYYY-MM-DD, Vietnam time); empty means today.
Money is whole VND. Each result carries giai_trinh: the steps and the legal basis.
Key (optional): Authorization: Bearer <key> or X-API-Key. Without a key: 30 requests/minute and 1,000/day per IP. Every response has X-RateLimit-* headers.

GET `/healthz`

Health check

curl

curl -s 'https://api.maxmin.vn/healthz'

Response fields (200)

Field	Type	Description (VI)
`trang_thai` required	`string`
`phien_ban` required	`string`
`commit`	`string`
`phien_ban_luat` required	`string`

Status codes: 200 Sống

POST `/v1/luong/gross-net`

Gross to net salary, with insurance, PIT and employer cost

Từ lương gross ra lương net (thực nhận), kèm bảo hiểm, thuế, chi phí doanh nghiệp

Request body (JSON)

Field	Type	Description (VI)
`ngay_ap_dung`	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`ma_xa`	`string`	Thay cho vung (từ 01/07/2025: Phụ lục I Nghị định 128/2025, từ 01/01/2026: Nghị định 293/2025)
`so_nguoi_phu_thuoc`	`integer` default 0
`dong_bh`	`boolean` default true	false = không đóng bảo hiểm bắt buộc
`dong_bhtn`	`boolean` default true
`kpcd`	`boolean` default true	Tính kinh phí công đoàn 2% (phần doanh nghiệp)
`thu_nhap_mien_thue`	`integer`	Phần miễn thuế nằm trong gross (ăn giữa ca trong mức
`doi_tuong`	`"cu_tru" \| "khong_cu_tru" \| "vang_lai"` default "cu_tru"	cu_tru: cá nhân cư trú có hợp đồng lao động từ 3 tháng, khấu trừ theo biểu luỹ tiến sau giảm trừ. khong_cu_tru: cá nhân không cư trú, 20% trên thu nhập chịu thuế, không giảm trừ. vang_lai: không ký hợp đồng lao động hoặc hợp đồng dưới 3 tháng; khấu trừ 10% nếu mỗi lần trả từ ngưỡng trở lên.
`quoc_tich`	`"viet_nam" \| "nuoc_ngoai"` default "viet_nam"	nuoc_ngoai = người nước ngoài làm việc tại Việt Nam (không thuộc đối tượng BHTN).
`gross` required	`integer`
`luong_dong_bh`	`integer`	Tiền lương làm căn cứ đóng BH; mặc định = gross

curlOpen in playground

curl -s https://api.maxmin.vn/v1/luong/gross-net \
  -H 'content-type: application/json' \
  -d '{"gross":30000000,"ngay_ap_dung":"2026-09-27","vung":"I","so_nguoi_phu_thuoc":1}'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`gross`	`integer`
`net`	`integer`
`net_muc_tieu`	`integer`	Chỉ có ở net-gross
`lech`	`integer`	net - net_muc_tieu (net-gross)
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`doi_tuong`	`"cu_tru" \| "khong_cu_tru" \| "vang_lai"` default "cu_tru"	cu_tru: cá nhân cư trú có hợp đồng lao động từ 3 tháng, khấu trừ theo biểu luỹ tiến sau giảm trừ. khong_cu_tru: cá nhân không cư trú, 20% trên thu nhập chịu thuế, không giảm trừ. vang_lai: không ký hợp đồng lao động hoặc hợp đồng dưới 3 tháng; khấu trừ 10% nếu mỗi lần trả từ ngưỡng trở lên.
`bao_hiem`	`object \| null`
`bh_nld`	`integer`
`thu_nhap_chiu_thue`	`integer`
`giam_tru_ban_than`	`integer`
`giam_tru_nguoi_phu_thuoc`	`integer`
`tong_giam_tru`	`integer`
`thu_nhap_tinh_thue`	`integer`
`thue_tncn`	`integer`
`bac`	`integer`
`chi_tiet_bac`	`mảng object`
`chi_tiet_bac[].bac`	`integer`
`chi_tiet_bac[].tu`	`integer`
`chi_tiet_bac[].den`	`integer \| null`
`chi_tiet_bac[].phan`	`number`
`chi_tiet_bac[].thue_suat`	`number`
`chi_tiet_bac[].thue`	`number`
`chi_phi_dn`	`integer`	gross + BH doanh nghiệp + KPCĐ
`thue_suat_hieu_dung`	`number`

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 413 Thân yêu cầu quá 64 KB · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

POST `/v1/luong/net-gross`

Net target to the smallest gross (whole VND) that reaches it

Từ lương net mong muốn ra gross nhỏ nhất (đồng nguyên) cho net >= mục tiêu

Request body (JSON)

Field	Type	Description (VI)
`ngay_ap_dung`	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`ma_xa`	`string`	Thay cho vung (từ 01/07/2025: Phụ lục I Nghị định 128/2025, từ 01/01/2026: Nghị định 293/2025)
`so_nguoi_phu_thuoc`	`integer` default 0
`dong_bh`	`boolean` default true	false = không đóng bảo hiểm bắt buộc
`dong_bhtn`	`boolean` default true
`kpcd`	`boolean` default true	Tính kinh phí công đoàn 2% (phần doanh nghiệp)
`thu_nhap_mien_thue`	`integer`	Phần miễn thuế nằm trong gross (ăn giữa ca trong mức
`doi_tuong`	`"cu_tru" \| "khong_cu_tru" \| "vang_lai"` default "cu_tru"	cu_tru: cá nhân cư trú có hợp đồng lao động từ 3 tháng, khấu trừ theo biểu luỹ tiến sau giảm trừ. khong_cu_tru: cá nhân không cư trú, 20% trên thu nhập chịu thuế, không giảm trừ. vang_lai: không ký hợp đồng lao động hoặc hợp đồng dưới 3 tháng; khấu trừ 10% nếu mỗi lần trả từ ngưỡng trở lên.
`quoc_tich`	`"viet_nam" \| "nuoc_ngoai"` default "viet_nam"	nuoc_ngoai = người nước ngoài làm việc tại Việt Nam (không thuộc đối tượng BHTN).
`net` required	`integer`

curlOpen in playground

curl -s https://api.maxmin.vn/v1/luong/net-gross \
  -H 'content-type: application/json' \
  -d '{"net":25000000,"ngay_ap_dung":"2026-09-27","vung":"I"}'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`gross`	`integer`
`net`	`integer`
`net_muc_tieu`	`integer`	Chỉ có ở net-gross
`lech`	`integer`	net - net_muc_tieu (net-gross)
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`doi_tuong`	`"cu_tru" \| "khong_cu_tru" \| "vang_lai"` default "cu_tru"	cu_tru: cá nhân cư trú có hợp đồng lao động từ 3 tháng, khấu trừ theo biểu luỹ tiến sau giảm trừ. khong_cu_tru: cá nhân không cư trú, 20% trên thu nhập chịu thuế, không giảm trừ. vang_lai: không ký hợp đồng lao động hoặc hợp đồng dưới 3 tháng; khấu trừ 10% nếu mỗi lần trả từ ngưỡng trở lên.
`bao_hiem`	`object \| null`
`bh_nld`	`integer`
`thu_nhap_chiu_thue`	`integer`
`giam_tru_ban_than`	`integer`
`giam_tru_nguoi_phu_thuoc`	`integer`
`tong_giam_tru`	`integer`
`thu_nhap_tinh_thue`	`integer`
`thue_tncn`	`integer`
`bac`	`integer`
`chi_tiet_bac`	`mảng object`
`chi_tiet_bac[].bac`	`integer`
`chi_tiet_bac[].tu`	`integer`
`chi_tiet_bac[].den`	`integer \| null`
`chi_tiet_bac[].phan`	`number`
`chi_tiet_bac[].thue_suat`	`number`
`chi_tiet_bac[].thue`	`number`
`chi_phi_dn`	`integer`	gross + BH doanh nghiệp + KPCĐ
`thue_suat_hieu_dung`	`number`

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

POST `/v1/bhxh`

Compulsory social, health and unemployment insurance, employee and employer shares, union fee

BHXH, BHYT, BHTN phần người lao động và doanh nghiệp, kinh phí công đoàn

Request body (JSON)

Field	Type	Description (VI)
`luong_dong_bh` required	`integer`
`ngay_ap_dung`	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`ma_xa`	`string`
`dong_bhtn`	`boolean` default true
`kpcd`	`boolean` default true
`quoc_tich`	`"viet_nam" \| "nuoc_ngoai"` default "viet_nam"	nuoc_ngoai = người nước ngoài làm việc tại Việt Nam (không thuộc đối tượng BHTN).

curlOpen in playground

curl -s https://api.maxmin.vn/v1/bhxh \
  -H 'content-type: application/json' \
  -d '{"luong_dong_bh":60000000,"ngay_ap_dung":"2026-09-27","vung":"II"}'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`luong_co_so`	`integer`
`luong_toi_thieu_vung`	`integer`
`tran_bhxh_bhyt`	`integer`
`tran_bhtn`	`integer`
`can_cu_bhxh_bhyt`	`integer`
`can_cu_bhtn`	`integer`
`nld`	`object`
`nld.bhxh`	`integer`
`nld.bhyt`	`integer`
`nld.bhtn`	`integer`
`nld.tong`	`integer`
`dn`	`object`
`dn.huu_tri_tu_tuat`	`integer`
`dn.om_dau_thai_san`	`integer`
`dn.tnld_bnn`	`integer`
`dn.bhxh`	`integer`
`dn.bhyt`	`integer`
`dn.bhtn`	`integer`
`dn.tong`	`integer`
`kpcd`	`integer`
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

POST `/v1/thue-tncn`

Monthly personal income tax on employment income (resident progressive, non-resident 20%, casual 10%)

Thuế TNCN một tháng từ tiền lương, tiền công (cư trú luỹ tiến, không cư trú 20%, vãng lai 10%)

Request body (JSON)

Field	Type	Description (VI)
`thu_nhap_chiu_thue` required	`integer`	Thu nhập chịu thuế tháng (đã trừ khoản miễn thuế); với vang_lai là số tiền trả một lần
`bao_hiem_bat_buoc`	`integer` default 0	BHXH
`so_nguoi_phu_thuoc`	`integer` default 0
`giam_tru_khac`	`integer` default 0	Hưu trí tự nguyện (trong trần), từ thiện... trong tháng
`doi_tuong`	`"cu_tru" \| "khong_cu_tru" \| "vang_lai"` default "cu_tru"	cu_tru: cá nhân cư trú có hợp đồng lao động từ 3 tháng, khấu trừ theo biểu luỹ tiến sau giảm trừ. khong_cu_tru: cá nhân không cư trú, 20% trên thu nhập chịu thuế, không giảm trừ. vang_lai: không ký hợp đồng lao động hoặc hợp đồng dưới 3 tháng; khấu trừ 10% nếu mỗi lần trả từ ngưỡng trở lên.
`ngay_ap_dung`	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.

curlOpen in playground

curl -s https://api.maxmin.vn/v1/thue-tncn \
  -H 'content-type: application/json' \
  -d '{"thu_nhap_chiu_thue":40000000,"bao_hiem_bat_buoc":4200000,"so_nguoi_phu_thuoc":2,"ngay_ap_dung":"2026-09-27"}'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`doi_tuong`	`"cu_tru" \| "khong_cu_tru" \| "vang_lai"` default "cu_tru"	cu_tru: cá nhân cư trú có hợp đồng lao động từ 3 tháng, khấu trừ theo biểu luỹ tiến sau giảm trừ. khong_cu_tru: cá nhân không cư trú, 20% trên thu nhập chịu thuế, không giảm trừ. vang_lai: không ký hợp đồng lao động hoặc hợp đồng dưới 3 tháng; khấu trừ 10% nếu mỗi lần trả từ ngưỡng trở lên.
`thu_nhap_chiu_thue`	`integer`
`tong_giam_tru`	`integer`
`thu_nhap_tinh_thue`	`integer`
`thue_tncn`	`integer`
`bac`	`integer`
`thue_suat`	`number`	Thuế suất toàn phần (không cư trú 20%
`chi_tiet_bac`	`mảng object`
`chi_tiet_bac[].bac`	`integer`
`chi_tiet_bac[].tu`	`integer`
`chi_tiet_bac[].den`	`integer \| null`
`chi_tiet_bac[].phan`	`number`
`chi_tiet_bac[].thue_suat`	`number`
`chi_tiet_bac[].thue`	`number`

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

POST `/v1/quyet-toan`

Annual PIT finalisation for a resident: authorise employer or self-file, tax payable or refundable

Quyết toán thuế TNCN năm từ tiền lương, tiền công của cá nhân cư trú (uỷ quyền hay tự quyết toán, nộp thêm/hoàn)

Request body (JSON)

Field	Type	Description (VI)
`nam` required	`integer`	Năm tính thuế
`thang` required	`mảng object`	Tháng 1..12 theo thứ tự; thiếu = 0
`thang[].tnct`	`integer`	Thu nhập chịu thuế tại nơi trả lương (đã trừ miễn thuế)
`thang[].bh`	`integer`	BH bắt buộc người lao động đã đóng
`thang[].thue`	`integer`	Thuế đã khấu trừ
`thang[].npt`	`integer`	Số người phụ thuộc tính giảm trừ trong tháng
`hd_3_thang`	`boolean` default true
`dang_lam_viec`	`boolean` default true
`noi_khac_tnct`	`integer` default 0
`noi_khac_bh`	`integer` default 0
`noi_khac_thue`	`integer` default 0
`vang_lai_tn`	`integer` default 0
`vang_lai_thue`	`integer` default 0
`huu_tri`	`integer` default 0
`tu_thien`	`integer` default 0
`y_te`	`integer` default 0
`giao_duc`	`integer` default 0
`so_thang_gt`	`integer` default 12
`de_nghi_hoan`	`boolean` default true

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`nam`	`integer`
`cach`	`"uy_quyen" \| "tu_quyet_toan" \| "khong_phai"`
`duoc_uy_quyen`	`boolean`
`ly_do_khong_uy_quyen`	`mảng string`
`bo_vang_lai`	`boolean`
`ket_qua`	`object`
`ket_qua.tnct`	`integer`
`ket_qua.bh`	`integer`
`ket_qua.gt_ban_than`	`integer`
`ket_qua.gt_npt`	`integer`
`ket_qua.huu_tri`	`integer`
`ket_qua.tu_thien`	`integer`
`ket_qua.y_te_giao_duc`	`integer`
`ket_qua.tong_giam_tru`	`integer`
`ket_qua.tntt`	`integer`
`ket_qua.thue`	`integer`
`ket_qua.da_khau_tru`	`integer`
`ket_qua.chenh`	`integer`	> 0 nộp thêm, < 0 nộp thừa
`toan_bo`	`object`
`toan_bo.tnct`	`integer`
`toan_bo.bh`	`integer`
`toan_bo.gt_ban_than`	`integer`
`toan_bo.gt_npt`	`integer`
`toan_bo.huu_tri`	`integer`
`toan_bo.tu_thien`	`integer`
`toan_bo.y_te_giao_duc`	`integer`
`toan_bo.tong_giam_tru`	`integer`
`toan_bo.tntt`	`integer`
`toan_bo.thue`	`integer`
`toan_bo.da_khau_tru`	`integer`
`toan_bo.chenh`	`integer`	> 0 nộp thêm, < 0 nộp thừa
`tai_don_vi`	`object`
`tai_don_vi.tnct`	`integer`
`tai_don_vi.bh`	`integer`
`tai_don_vi.gt_ban_than`	`integer`
`tai_don_vi.gt_npt`	`integer`
`tai_don_vi.huu_tri`	`integer`
`tai_don_vi.tu_thien`	`integer`
`tai_don_vi.y_te_giao_duc`	`integer`
`tai_don_vi.tong_giam_tru`	`integer`
`tai_don_vi.tntt`	`integer`
`tai_don_vi.thue`	`integer`
`tai_don_vi.da_khau_tru`	`integer`
`tai_don_vi.chenh`	`integer`	> 0 nộp thêm, < 0 nộp thừa
`han_nop`	`object`
`han_nop.ngay`	`string (date)`
`han_nop.ghi`	`string`
`ghi_chu`	`mảng string`

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

POST `/v1/bhxh-mot-lan`

Điều kiện và mức hưởng bảo hiểm xã hội một lần (Điều 70, Điều 74 Luật BHXH 41/2024/QH15)

Request body (JSON)

Field	Type	Description (VI)
`ngay_tham_gia_dau` required	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.
`ngay_tinh`	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.
`thang_truoc_2014`	`integer` default 0	Số tháng đóng BHXH trước 01/2014
`thang_tu_2014`	`integer` default 0	Số tháng đóng BHXH từ 01/2014 trở đi
`muc_binh_quan` required	`integer`	Mức bình quân tiền lương tháng đóng BHXH (đã áp hệ số trượt giá
`du_tuoi_chua_du_15_nam`	`boolean` default false
`ra_nuoc_ngoai_dinh_cu`	`boolean` default false
`benh_hiem_ngheo`	`boolean` default false
`suy_giam_tu_81_phan_tram`	`boolean` default false
`nghi_12_thang_chua_du_20_nam`	`boolean` default false	Chỉ áp dụng cho người tham gia BHXH TRƯỚC 01/07/2025 (điều khoản chuyển tiếp)

curlOpen in playground

curl -s https://api.maxmin.vn/v1/bhxh-mot-lan \
  -H 'content-type: application/json' \
  -d '{"ngay_tham_gia_dau":"2018-01-01","thang_truoc_2014":0,"thang_tu_2014":60,"muc_binh_quan":8000000,"du_tuoi_chua_du_15_nam":true}'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`nhom`	`"truoc-2025-07-01" \| "tu-2025-07-01"`
`du_dieu_kien`	`boolean`
`ly_do_dieu_kien`	`string`
`du_mot_nam`	`boolean`	false: chưa đủ 1 năm đóng, cần số tiền thực đóng để tính, công cụ không tự tính
`nam_truoc_2014`	`number`
`nam_tu_2014`	`number`
`muc_huong`	`integer`

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

POST `/v1/tro-cap-that-nghiep`

Điều kiện, mức hưởng và số tháng hưởng trợ cấp thất nghiệp (Điều 38, 39 Luật Việc làm 74/2025/QH15)

Request body (JSON)

Field	Type	Description (VI)
`luong_dong_bhtn` required	`mảng number`	Lương tháng đóng BHTN tối đa 6 tháng liền kề gần nhất trước khi nghỉ việc, mới nhất trước
`thang_dong` required	`number`	Tổng số tháng đã đóng BHTN liên tục chưa hưởng
`thang_dong_trong_ky`	`number`	Số tháng đã đóng trong 24 tháng trước khi chấm dứt hợp đồng, nếu khác thang_dong
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`nha_nuoc`	`boolean` default false	Hưởng lương do Nhà nước quy định (chỉ còn hiệu lực trước 01/01/2026)
`ngay_nghi`	`string (date)`	YYYY-MM-DD, giờ Việt Nam. Bỏ trống = hôm nay.

curlOpen in playground

curl -s https://api.maxmin.vn/v1/tro-cap-that-nghiep \
  -H 'content-type: application/json' \
  -d '{"luong_dong_bhtn":[10000000,10000000,10000000,10000000,10000000,10000000],"thang_dong":48,"vung":"I","ngay_nghi":"2026-09-27"}'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`du_dieu_kien`	`boolean`
`ly_do`	`string`
`binh_quan`	`integer`
`muc_chua_tran`	`integer`
`tran`	`integer`
`bi_tran`	`boolean`
`muc_thang`	`integer`
`so_thang`	`number`
`thang_bao_luu`	`number`
`tong`	`integer`
`han_nop`	`string (date)`
`ngay_bat_dau`	`integer`	Ngày làm việc thứ mấy kể từ ngày nộp đủ hồ sơ

Status codes: 200 Kết quả · 400 Đầu vào sai · 401 Khoá API sai hoặc hết hạn · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

GET `/v1/vung-theo-xa`

Vùng lương tối thiểu theo tên xã/phường, chấp nhận cả tên TRƯỚC sáp nhập 01/07/2025 lẫn tên MỚI

Query parameters

Field	Type	Description (VI)
`tim` required	`string`	Tên xã/phường, cũ hoặc mới (không dấu cũng được)
`ngay_ap_dung`	`string (date)`

curlOpen in playground

curl -s 'https://api.maxmin.vn/v1/vung-theo-xa?tim=...&ngay_ap_dung=2026-09-27'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`tim`	`string`
`so_ket_qua`	`integer`
`ket_qua`	`mảng object`
`ket_qua[].ma_xa`	`string`
`ket_qua[].ten_xa`	`string`
`ket_qua[].tinh`	`string`
`ket_qua[].vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`ket_qua[].luong_toi_thieu_thang`	`integer`
`ket_qua[].luong_toi_thieu_gio`	`integer`
`ket_qua[].tran_dong_bhxh_bhyt`	`integer`
`ket_qua[].tu_ten_cu`	`string`	Có mặt nếu tìm thấy qua tên xã CŨ (trước 01/07/2025)
`ket_qua[].huyen_cu`	`string`
`ket_qua[].tinh_cu`	`string`
`ket_qua[].cach_sap_xep`	`"toan-bo" \| "mot-phan" \| "giu-nguyen" \| "doi-ten"`
`ket_qua[].can_cu_vung`	`string`	Danh mục địa bàn áp dụng tại ngày: Phụ lục Nghị định 74/2024 (quận/huyện cũ), Phụ lục I Nghị định 128/2025, Phụ lục Nghị định 293/2025, hoặc bảo lưu khoản 7 Điều 15 Nghị định 128/2025. Rỗng khi không xác định được một vùng (vung rỗng, mức 0, xem ghi_chu)
`ket_qua[].ghi_chu`	`string`

Status codes: 200 Kết quả · 400 Đầu vào sai · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

GET `/v1/luong-toi-thieu`

Regional minimum wage (monthly, hourly) on a date; look up the region by commune code or name

Lương tối thiểu vùng (tháng, giờ) tại ngày; tra vùng theo mã hoặc tên xã/phường, cả tên xã cũ trước sáp nhập (xa=), kèm vùng trước/sau

Query parameters

Field	Type	Description (VI)
`ngay_ap_dung`	`string (date)`
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`ma_xa`	`string`	Mã xã MỚI 5 chữ số (Cục Thống kê): vùng theo Phụ lục I Nghị định 128/2025 (01/07/2025-31/12/2025) hoặc Phụ lục Nghị định 293/2025 (từ 01/01/2026); trước 01/07/2025 báo lỗi, dùng xa=
`tim`	`string`	Tìm xã/phường theo tên (không dấu cũng được)
`xa`	`string`	Tên xã CŨ (trước 01/07/2025) hoặc MỚI (không dấu cũng được, có thể kèm huyện/tỉnh), hoặc mã 5 chữ số (mới hoặc cũ). Trả `tra_xa`: xã mới kèm `vung_nd128` (Phụ lục I Nghị định 128/2025, 01/07/2025-31/12/2025) và `vung_sau` (Nghị định 293/2025, từ 01/01/2026); xã cũ kèm `vung_truoc` (Nghị định 74/2024, 01/07/2024-30/06/2025, theo quận/huyện cũ, có `giai_doan` khi quận/huyện sắp xếp từ 01/01/2025). Khi khớp đúng một xã (hoặc một kết quả chính xác), `vung` lấy theo ngày: 01/07/2024-30/06/2025 vùng trước; 01/07/2025-31/12/2025 vùng theo Phụ lục I Nghị định 128/2025, biết xã cũ thì áp bảo lưu khoản 7 Điều 15 (vùng trước cao hơn thì giữ); từ 01/01/2026 vùng sau, kèm khoản 5 Điều 5 Nghị định 293/2025 tính cụ thể (mức tại 31/12/2025 cao hơn thì cảnh báo số tiền). Nguồn: bảng chuyển đổi của Cục Thống kê, 34 Nghị quyết 1654-1687/NQ-UBTVQH15, luat/xa-cu-2025.json, luat/vung-nd74-2024.json, luat/vung-nd128-2025.json.

curlOpen in playground

curl -s 'https://api.maxmin.vn/v1/luong-toi-thieu?ngay_ap_dung=2026-09-27&vung=I'

Response fields (200)

Field	Type	Description (VI)
`ngay_ap_dung` required	`string (date)`
`phien_ban_luat` required	`string`
`giai_trinh` required	`mảng object`
`giai_trinh[].buoc` required	`string`
`giai_trinh[].cong_thuc` required	`string`
`giai_trinh[].ket_qua` required	`number`
`giai_trinh[].can_cu`	`mảng object`	Luôn là mảng (có thể rỗng)
`canh_bao`	`mảng string`
`tham_so_can_ra_soat`	`mảng string`
`thang`	`object`
`gio`	`object`
`vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`xa`	`object`
`xa.ma`	`string`
`xa.ten`	`string`
`xa.loai`	`"xa" \| "phuong" \| "dac-khu"`
`xa.ma_tinh`	`string`
`xa.ten_tinh`	`string`
`xa.vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`xa.can_cu`	`"liet-ke" \| "con-lai"`	liet-ke = có tên trong Phụ lục; con-lai = thuộc mệnh đề 'các xã, phường còn lại'
`xa.trang_phu_luc`	`integer`
`xa.trang_thai`	`"da_kiem" \| "can_ra_soat"`	Chỉ có khi cần rà soát (vd Phụ lục I Nghị định 128 ghi tên khác danh mục)
`xa.ly_do`	`string`
`xa.ten_phu_luc`	`string`	Tên đúng như Phụ lục ghi khi khác tên chính thức
`ket_qua_tim`	`mảng object`
`ket_qua_tim[].ma`	`string`
`ket_qua_tim[].ten`	`string`
`ket_qua_tim[].loai`	`"xa" \| "phuong" \| "dac-khu"`
`ket_qua_tim[].ma_tinh`	`string`
`ket_qua_tim[].ten_tinh`	`string`
`ket_qua_tim[].vung`	`"I" \| "II" \| "III" \| "IV"`	Vùng lương tối thiểu nơi người sử dụng lao động hoạt động
`ket_qua_tim[].can_cu`	`"liet-ke" \| "con-lai"`	liet-ke = có tên trong Phụ lục; con-lai = thuộc mệnh đề 'các xã, phường còn lại'
`ket_qua_tim[].trang_phu_luc`	`integer`
`ket_qua_tim[].trang_thai`	`"da_kiem" \| "can_ra_soat"`	Chỉ có khi cần rà soát (vd Phụ lục I Nghị định 128 ghi tên khác danh mục)
`ket_qua_tim[].ly_do`	`string`
`ket_qua_tim[].ten_phu_luc`	`string`	Tên đúng như Phụ lục ghi khi khác tên chính thức
`tra_xa`	`object`
`tra_xa.dau_vao`	`string`
`tra_xa.so_khop`	`integer`
`tra_xa.khop`	`mảng object`

Status codes: 200 Kết quả · 400 Đầu vào sai · 404 Không tìm thấy · 429 Vượt tốc độ hoặc hạn mức; xem đầu Retry-After

GET `/v1/tham-so`

Every legal parameter in force on a date, with its legal basis

Toàn bộ tham số luật có hiệu lực tại một ngày, kèm căn cứ

Query parameters

Field	Type	Description (VI)
`ngay`	`string (date)`
`ten`	`string`	Chỉ lấy một tham số
`lich_su`	`boolean`	true = trả cả lịch sử mọi mức

curlOpen in playground

curl -s 'https://api.maxmin.vn/v1/tham-so?ngay=2026-09-27&ten=...'

Response fields (200)

Field	Type	Description (VI)
`ngay`	`string (date)`
`phien_ban_luat`	`string`
`giay_phep`	`string`
`tham_so`	`mảng object`

Status codes: 200 Kết quả · 400 Đầu vào sai · 404 Không tìm thấy

GET `/v1/thay-doi-luat`

Machine-readable change log of the rules by effective date

Nhật ký thay đổi luật theo ngày hiệu lực (máy đọc được)

Query parameters

Field	Type	Description (VI)
`tu`	`string (date)`
`den`	`string (date)`

curlOpen in playground

curl -s 'https://api.maxmin.vn/v1/thay-doi-luat?tu=2026-09-27&den=2026-09-27'

Response fields (200)

Field	Type	Description (VI)
`phien_ban_luat`	`string`
`thay_doi`	`mảng object`
`thay_doi[].ngay_hieu_luc`	`string (date)`
`thay_doi[].tham_so`	`string`
`thay_doi[].nhan`	`string`
`thay_doi[].cu`
`thay_doi[].moi`
`thay_doi[].van_ban`	`mảng string`
`thay_doi[].trang_thai`	`string`

Status codes: 200 Kết quả

GET `/v1/ca-kiem`

The public test suite (CC BY 4.0) to measure your payroll software

Bộ ca kiểm công khai (CC BY 4.0) để đo phần mềm lương của bạn

curlOpen in playground

curl -s 'https://api.maxmin.vn/v1/ca-kiem'

Status codes: 200 Bộ ca kiểm

POST `/mcp`

MCP server (Model Context Protocol), Streamable HTTP, JSON-RPC 2.0

Máy chủ MCP (Model Context Protocol), Streamable HTTP, JSON-RPC 2.0

Công cụ: tinh_luong_gross_net, tinh_luong_net_gross, tinh_bhxh, tinh_thue_tncn, tra_luong_toi_thieu, quyet_toan_tncn, tinh_bhxh_mot_lan, tinh_tro_cap_that_nghiep, tra_vung_theo_xa, tra_xa_cu_moi, tra_tham_so, tra_thay_doi_luat. Không giữ phiên; GET trả 405 (không mở luồng SSE). Hướng dẫn cấu hình Claude, ChatGPT, Cursor: mcp/HUONG-DAN.md trong kho.

Status codes: 200 Trả lời JSON-RPC · 202 Đã nhận notification

Webhook for rule changes specification only, not built

Instead of polling GET /v1/thay-doi-luat or feed.xml, register a URL and MAXMIN will POST to it as soon as a new entry appears in the change log.

Not built yet: needs a background worker plus a place to store registered URLs, unlike the rest of MAXMIN (stateless, in-RAM only). This is new infrastructure, so this section is a specification only, pending a decision from ALODEV before building it.

No new infrastructure is needed for the read-only path: RSS and changelog.json already work today (rebuilt as static files whenever the rules change) and work with any RSS reader or a periodic job that fetches JSON, no webhook required.

MAXMIN API reference

GET /healthz

POST /v1/luong/gross-net

Request body (JSON)

POST /v1/luong/net-gross

Request body (JSON)

POST /v1/bhxh

Request body (JSON)

POST /v1/thue-tncn

Request body (JSON)

POST /v1/quyet-toan

Request body (JSON)

POST /v1/bhxh-mot-lan

Request body (JSON)

POST /v1/tro-cap-that-nghiep

Request body (JSON)

GET /v1/vung-theo-xa

Query parameters

GET /v1/luong-toi-thieu

Query parameters

GET /v1/tham-so

Query parameters

GET /v1/thay-doi-luat

Query parameters

GET /v1/ca-kiem

POST /mcp

Webhook for rule changes specification only, not built

GET `/healthz`

POST `/v1/luong/gross-net`

POST `/v1/luong/net-gross`

POST `/v1/bhxh`

POST `/v1/thue-tncn`

POST `/v1/quyet-toan`

POST `/v1/bhxh-mot-lan`

POST `/v1/tro-cap-that-nghiep`

GET `/v1/vung-theo-xa`

GET `/v1/luong-toi-thieu`

GET `/v1/tham-so`

GET `/v1/thay-doi-luat`

GET `/v1/ca-kiem`

POST `/mcp`