Kiểm tra CCCD & mã số thuế API
Kiểm tra số căn cước công dân (CCCD), CMND cũ và mã số thuế (MST): cấu trúc, tỉnh, giới tính, năm sinh và chữ số kiểm tra của MST.
API kiểm tra số định danh Việt Nam giúp phát hiện số sai cấu trúc trước khi lưu. Số CCCD 12 chữ số được giải mã theo Thông tư 07/2016 và 59/2021 của Bộ Công an: 3 số đầu là tỉnh nơi đăng ký khai sinh (trả về tên tỉnh và tỉnh tương ứng sau sáp nhập 2025), số thứ 4 là giới tính và thế kỷ sinh, 2 số tiếp theo là năm sinh, 6 số cuối là số ngẫu nhiên.
Mã số thuế 10 số được kiểm tra bằng chữ số kiểm tra chính thức (trọng số 31, 29, 23, 19, 17, 13, 7, 5, 3); mã 13 số (0101248141-001) được nhận diện là chi nhánh / đơn vị phụ thuộc. Từ 07/2025 mã số thuế cá nhân là số CCCD, nên MST 12 số được kiểm tra như CCCD. CMND 9 số không có checksum nên chỉ kiểm tra định dạng. type=auto (mặc định) tự đoán loại theo độ dài.
Đây là kiểm tra cấu trúc: API không tra cứu cơ sở dữ liệu nào của nhà nước và không chứng minh được thẻ hay doanh nghiệp có tồn tại. Số được xử lý trong bộ nhớ, không lưu và không ghi log; nên dùng POST để số không xuất hiện trong URL.
Tham số
| Tên | Vị trí | Kiểu | Bắt buộc | Mặc định | |
|---|---|---|---|---|---|
number | body|query | string | có | Số CCCD, CMND hoặc mã số thuế; dấu cách, dấu chấm, gạch ngang được bỏ qua. | |
type | body|query | string | không | auto | auto, cccd, cmnd hoặc tax_code (tên khác mst). |
Ví dụ
curl -X POST "https://apibox.io.vn/v1/vn-id" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"number":"001099012345"}'const res = await fetch('https://apibox.io.vn/v1/vn-id', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"number": "001099012345"
}),
});
const data = await res.json();
console.log(data);import requests
res = requests.post(
"https://apibox.io.vn/v1/vn-id",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"number": "001099012345"},
timeout=30,
)
print(res.json())<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-id');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => '{"number":"001099012345"}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));Kết quả trả về
{
"input": "001099012345",
"normalized": "001099012345",
"type": "cccd",
"valid": true,
"errors": [],
"details": {
"province_code": "001",
"province": "Hà Nội",
"province_since_2025": "Hà Nội",
"gender": "male",
"gender_code": 0,
"birth_year": 1999,
"age_this_year": 27,
"serial": "012345"
},
"note": "Since 07/2025 the CCCD number is also the personal tax code. Structure check only: this does not prove the card exists."
}
Ứng dụng
- Bắt lỗi gõ sai CCCD, mã số thuế trong form đăng ký, hoá đơn điện tử
- Điền sẵn giới tính, năm sinh từ số CCCD trong quy trình eKYC
- Làm sạch dữ liệu khách hàng, nhà cung cấp trước khi nhập vào hệ thống
- Phân biệt MST doanh nghiệp, MST chi nhánh và MST cá nhân
Hỏi đáp
Kết quả hợp lệ có nghĩa CCCD là thật không?
Không. Kết quả chỉ cho biết số đúng cấu trúc (mã tỉnh có thật, năm sinh hợp lý). Chỉ Cơ sở dữ liệu quốc gia về dân cư mới xác nhận được thẻ, và cơ sở dữ liệu này không mở công khai.
Số có bị lưu lại không?
Không. Số được kiểm tra trong bộ nhớ, không ghi vào log hay cơ sở dữ liệu. Hãy dùng POST với body JSON để số không nằm trong log truy cập của proxy.
Vì sao tỉnh khác với nơi người đó đang sống?
3 số đầu là tỉnh nơi đăng ký khai sinh, không phải địa chỉ thường trú. Mã theo 63 tỉnh trước 07/2025; province_since_2025 cho biết tỉnh sau sáp nhập.
API liên quan
Định vị IP
Tra cứu quốc gia, tỉnh/thành, toạ độ, ASN và nhà mạng của bất kỳ địa chỉ IPv4, IPv6 nào – hoặc IP của chính bạn – chỉ với một request JSON.
DNSTra cứu DNS
Tra bản ghi A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, SRV… của mọi tên miền hoặc tra ngược IP (PTR) qua DNS over HTTPS, kết quả JSON gọn gàng.
@Kiểm tra e-mail
Kiểm tra địa chỉ e-mail: cú pháp RFC, bản ghi MX/A, ~120k tên miền e-mail tạm, tài khoản chức năng, nhà cung cấp miễn phí và gợi ý gõ sai như gmial.com.