Tài liệu API MAXMIN

OpenAPI 3.1.0 · phiên bản 1.0.0 · sinh ngày 27/09/2026

MAXMIN trả về con số lương, thuế thu nhập cá nhân, bảo hiểm bắt buộc đúng luật Việt Nam tại đúng ngày áp dụng, kèm giai_trinh: từng bước tính và văn bản căn cứ (số hiệu, điều khoản, ngày hiệu lực).

- Mọi phép tính nhận ngay_ap_dung (YYYY-MM-DD, giờ Việt Nam). Bỏ trống = hôm nay theo giờ Việt Nam. - API không nhận dữ liệu định danh (tên, CCCD, MST): chỉ nhận con số. - Tiền là số nguyên đồng; mỗi khoản làm tròn tới đồng (nửa đồng làm tròn lên), tổng = cộng các khoản đã làm tròn. - Tham số chưa đối chiếu được nguyên văn văn bản gốc có trang_thai: can_ra_soat; kết quả dùng tham số đó liệt kê nó trong tham_so_can_ra_soat. - Bảng tham số luật và bộ ca kiểm: giấy phép CC BY 4.0. Mã nguồn: xem kho.

Khoá API: gửi Authorization: Bearer <khoa> hoặc X-API-Key: <khoa>. Không có khoá vẫn gọi được ở bậc ẩn danh (hạn mức theo IP). Đầu trả lời luôn có X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Địa chỉ gốc https://api.maxmin.vn (hoặc https://maxmin.vn/v1/...). Tài liệu máy đọc: OpenAPI 3.1; bản đọc tương tác: /docs.

GET `/healthz`

curl

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`trang_thai` bắt buộc	`string`
`phien_ban` bắt buộc	`string`
`commit`	`string`
`phien_ban_luat` bắt buộc	`string`

Mã trả về: 200 Sống

POST `/v1/luong/gross-net`

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

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`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` mặc định 0
`dong_bh`	`boolean` mặc định true	false = không đóng bảo hiểm bắt buộc
`dong_bhtn`	`boolean` mặc định true
`kpcd`	`boolean` mặc định 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"` mặc định "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"` mặc định "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` bắt buộc	`integer`
`luong_dong_bh`	`integer`	Tiền lương làm căn cứ đóng BH; mặc định = gross

curlMở trong sân thử

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}'

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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"` mặc định "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`

Mã trả về: 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`

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

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`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` mặc định 0
`dong_bh`	`boolean` mặc định true	false = không đóng bảo hiểm bắt buộc
`dong_bhtn`	`boolean` mặc định true
`kpcd`	`boolean` mặc định 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"` mặc định "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"` mặc định "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` bắt buộc	`integer`

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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"` mặc định "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`

Mã trả về: 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`

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

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`luong_dong_bh` bắt buộc	`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` mặc định true
`kpcd`	`boolean` mặc định true
`quoc_tich`	`"viet_nam" \| "nuoc_ngoai"` mặc định "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).

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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

Mã trả về: 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`

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

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`thu_nhap_chiu_thue` bắt buộc	`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` mặc định 0	BHXH
`so_nguoi_phu_thuoc`	`integer` mặc định 0
`giam_tru_khac`	`integer` mặc định 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"` mặc định "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.

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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"` mặc định "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`

Mã trả về: 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`

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)

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`nam` bắt buộc	`integer`	Năm tính thuế
`thang` bắt buộc	`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` mặc định true
`dang_lam_viec`	`boolean` mặc định true
`noi_khac_tnct`	`integer` mặc định 0
`noi_khac_bh`	`integer` mặc định 0
`noi_khac_thue`	`integer` mặc định 0
`vang_lai_tn`	`integer` mặc định 0
`vang_lai_thue`	`integer` mặc định 0
`huu_tri`	`integer` mặc định 0
`tu_thien`	`integer` mặc định 0
`y_te`	`integer` mặc định 0
`giao_duc`	`integer` mặc định 0
`so_thang_gt`	`integer` mặc định 12
`de_nghi_hoan`	`boolean` mặc định true

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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`

Mã trả về: 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)

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`ngay_tham_gia_dau` bắt buộc	`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` mặc định 0	Số tháng đóng BHXH trước 01/2014
`thang_tu_2014`	`integer` mặc định 0	Số tháng đóng BHXH từ 01/2014 trở đi
`muc_binh_quan` bắt buộc	`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` mặc định false
`ra_nuoc_ngoai_dinh_cu`	`boolean` mặc định false
`benh_hiem_ngheo`	`boolean` mặc định false
`suy_giam_tu_81_phan_tram`	`boolean` mặc định false
`nghi_12_thang_chua_du_20_nam`	`boolean` mặc định false	Chỉ áp dụng cho người tham gia BHXH TRƯỚC 01/07/2025 (điều khoản chuyển tiếp)

curlMở trong sân thử

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}'

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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`

Mã trả về: 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)

Thân yêu cầu (JSON)

Trường	Kiểu	Mô tả
`luong_dong_bhtn` bắt buộc	`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` bắt buộc	`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` mặc định 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.

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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ơ

Mã trả về: 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

Tham số truy vấn

Trường	Kiểu	Mô tả
`tim` bắt buộc	`string`	Tên xã/phường, cũ hoặc mới (không dấu cũng được)
`ngay_ap_dung`	`string (date)`

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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`

Mã trả về: 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`

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

Tham số truy vấn

Trường	Kiểu	Mô tả
`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.

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay_ap_dung` bắt buộc	`string (date)`
`phien_ban_luat` bắt buộc	`string`
`giai_trinh` bắt buộc	`mảng object`
`giai_trinh[].buoc` bắt buộc	`string`
`giai_trinh[].cong_thuc` bắt buộc	`string`
`giai_trinh[].ket_qua` bắt buộc	`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`

Mã trả về: 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`

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

Tham số truy vấn

Trường	Kiểu	Mô tả
`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

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`ngay`	`string (date)`
`phien_ban_luat`	`string`
`giay_phep`	`string`
`tham_so`	`mảng object`

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

GET `/v1/thay-doi-luat`

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

Tham số truy vấn

Trường	Kiểu	Mô tả
`tu`	`string (date)`
`den`	`string (date)`

curlMở trong sân thử

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

Các trường trả về (200)

Trường	Kiểu	Mô tả
`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`

Mã trả về: 200 Kết quả

GET `/v1/ca-kiem`

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

curlMở trong sân thử

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

Mã trả về: 200 Bộ ca kiểm

POST `/mcp`

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.

Mã trả về: 200 Trả lời JSON-RPC · 202 Đã nhận notification

Webhook báo luật đổi đặc tả, chưa triển khai

Thay vì tự gọi lại GET /v1/thay-doi-luat hay theo dõi feed.xml định kỳ, đăng ký một URL để MAXMIN tự POST tới đó ngay khi có một mục mới xuất hiện trong nhật ký thay đổi luật (tệp nguồn luat/thay-doi-luat.json, sinh bởi maxmin xuat-nhat-ky).

Chưa triển khai: cần một tiến trình chạy nền để theo dõi thay đổi và một nơi lưu danh sách URL đã đăng ký (khác với phần còn lại của MAXMIN, vốn không cần DB, không giữ trạng thái quá một lần chạy). Đây là việc hạ tầng mới, nên phần này CHỈ LÀ ĐẶC TẢ, chờ CEO quyết định trước khi dựng.

Đăng ký

POST /v1/webhooks
{
  "url": "https://vi-du.cong-ty.vn/hook/maxmin",
  "bi_mat": "chuoi-bi-mat-de-ky-HMAC (tuy chon nhung nen co)",
  "nhom": ["luong", "bao-hiem", "thue-tncn"],   // rong = tat ca nhom
  "email_lien_he": "[email protected]"              // de bao khi webhook loi lien tuc
}
-> 201 {"id": "wh_...", "url": "...", "trang_thai": "cho_xac_nhan"}

Xác nhận sở hữu URL trước khi kích hoạt (chống SSRF/spam): MAXMIN gọi thử POST url với {"loai":"xac_nhan","ma":"..."}, endpoint phải trả lại đúng ma trong 10 giây thì mới chuyển trang_thai sang hoat_dong.

Gửi khi có thay đổi

POST <url đã đăng ký>
Headers: Content-Type: application/json
         X-Maxmin-Signature: sha256=<HMAC-SHA256(body, bi_mat) dạng hex>
         X-Maxmin-Delivery: <id lần gửi, để chống xử lý trùng>
Body:    { "phien_ban_luat": "...", "thay_doi": [ { ...một mục của /v1/thay-doi-luat... } ] }

Thử lại theo hàm mũ (1 phút, 5 phút, 30 phút, 2 giờ, 12 giờ) tối đa 5 lần nếu endpoint không trả 2xx trong 10 giây; sau 5 lần liên tiếp thất bại thì tạm khoá webhook và báo email_lien_he. Có GET /v1/webhooks/{id} (xem lịch sử gửi) và DELETE /v1/webhooks/{id} (huỷ đăng ký).

Không cần backend mới cho phần chỉ đọc: RSS và changelog.json đã chạy được ngay (build tĩnh lại mỗi khi luật đổi), dùng được với mọi trình đọc RSS hoặc job định kỳ tự tải JSON, không cần chờ webhook.

Tài liệu API MAXMIN

GET /healthz

POST /v1/luong/gross-net

Thân yêu cầu (JSON)

POST /v1/luong/net-gross

Thân yêu cầu (JSON)

POST /v1/bhxh

Thân yêu cầu (JSON)

POST /v1/thue-tncn

Thân yêu cầu (JSON)

POST /v1/quyet-toan

Thân yêu cầu (JSON)

POST /v1/bhxh-mot-lan

Thân yêu cầu (JSON)

POST /v1/tro-cap-that-nghiep

Thân yêu cầu (JSON)

GET /v1/vung-theo-xa

Tham số truy vấn

GET /v1/luong-toi-thieu

Tham số truy vấn

GET /v1/tham-so

Tham số truy vấn

GET /v1/thay-doi-luat

Tham số truy vấn

GET /v1/ca-kiem

POST /mcp

Webhook báo luật đổi đặc tả, chưa triển khai

Đăng ký

Gửi khi có thay đổi

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`