/v1/tax-codes/{mst}Tra cứu mã số thuế
Lấy tên đơn vị, địa chỉ và trạng thái hoạt động từ mã số thuế (MST) để tự điền thông tin người mua khi lập hoá đơn.
Giới thiệu
Gọi API này khi người dùng nhập mã số thuế trên form bán hàng. Kết quả có tên, địa chỉ và trạng thái để điền người mua trước khi tạo hoá đơn.
Trên sandbox, 0312345678 và 0109876543 luôn trả dữ liệu mẫu để thử.
Endpoint
Gửi GET với MST trên đường dẫn. MST 10 số chỉ khớp đúng đơn vị đó, không kèm chi nhánh. Muốn tra chi nhánh thì gửi đủ 13 số.
Mọi request cần API key trong header api_key và App ID trong header app_id. API key phải thuộc đúng ứng dụng đó. Không dùng Authorization. Endpoint không trừ hạn mức phát hành hoá đơn, nhưng vẫn tính vào giới hạn số request.
Header
API key và App ID phải cùng một ứng dụng.
api_keystringBắt buộcAPI key của ứng dụng. Phải thuộc đúng app_id.
app_idstringBắt buộcĐịnh danh ứng dụng (UUID). Sao chép App ID trên trang chi tiết ứng dụng (tab Kết nối & bảo mật).
Param
Nằm trên đường dẫn.
mststringBắt buộcMã số thuế cần tra cứu. Chấp nhận 10 chữ số hoặc 13 chữ số (MST chi nhánh, dạng XXXXXXXXXX-XXX hoặc 13 số liền không dấu gạch). Chỉ gồm chữ số và dấu gạch ngang nếu có.
Ví dụ
Request mẫu trên sandbox:
curl https://sandbox.api.hddt.dev/v1/tax-codes/0312345678 \
-H "api_key: $HDDT_API_KEY" \
-H "app_id: $HDDT_APP_ID"Phản hồi
Khi tìm thấy MST, API trả 200 OK. Điền buyer bằng name, tax_code và address. Kiểm tra status trước khi phát hành.
objectstringBắt buộcLuôn là tax_code.
idstringBắt buộcTrùng tax_code.
tax_codestringBắt buộcMST đã chuẩn hoá. 10 số, hoặc chi nhánh dạng 0312345678-001.
namestringBắt buộcTên đơn vị trên hồ sơ thuế.
name_internationalstring | nullBắt buộcTên giao dịch quốc tế. null khi không có.
addressstringBắt buộcĐịa chỉ trên hồ sơ thuế.
statusstringBắt buộcMã trạng thái. Xem mục Trạng thái. Chỉ active là đang hoạt động.
status_labelstringBắt buộcCâu tiếng Việt cùng nghĩa với status, dùng để hiện trên form.
tax_officestring | nullBắt buộcCơ quan thuế quản lý. null khi không có.
representativestring | nullBắt buộcNgười đại diện. null khi không có.
updated_atstringBắt buộcThời điểm cập nhật thông tin, ISO 8601, múi giờ +07:00.
{
"object": "tax_code",
"id": "0312345678",
"tax_code": "0312345678",
"name": "Công ty TNHH ABC",
"name_international": null,
"address": "123 Nguyễn Huệ, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh",
"status": "active",
"status_label": "Đang hoạt động",
"tax_office": "Cục Thuế TP. Hồ Chí Minh",
"representative": "Nguyễn Văn A",
"updated_at": "2026-10-20T08:00:00+07:00"
}Trạng thái
status là mã để kiểm tra. status_label là câu tiếng Việt để hiện trên form.
| Mã | Mô tả |
|---|---|
| active | Đang hoạt động. |
| suspended | Tạm ngừng hoạt động, hoặc đã ngừng nhưng chưa hoàn thành thủ tục chấm dứt MST. |
| inactive | Không hoạt động tại địa chỉ đã đăng ký. |
| closed | Đã ngừng hoạt động và đã chấm dứt hiệu lực MST. |
| unknown | Không xác định được trạng thái. |
Chỉ phát hành khi active
Mã lỗi
Các trường hợp thường gặp:
401 unauthorized—Tuỳ chọnThiếu header api_key hoặc app_id, API key sai hoặc đã thu hồi, hoặc API key không thuộc App ID.
404 not_found—Tuỳ chọnKhông có đơn vị nào khớp MST đã nhập.
422 validation_error—Tuỳ chọnMST sai định dạng (độ dài, ký tự không hợp lệ).
429 rate_limited—Tuỳ chọnVượt giới hạn số request tra cứu trong khoảng thời gian cho phép.
503 provider_unavailable—Tuỳ chọnKhông tra cứu được mã số thuế lúc này. Thử lại sau.