hddt.dev
Tài liệuBảng giáTra cứu

Bắt đầu

  • Tổng quan
  • Bắt đầu nhanh
  • Xác thực
  • Môi trường sandbox
  • Mã lỗi

Ứng dụng

  • GETThông tin ứng dụng
  • PATCHCập nhật ứng dụng

Hoá đơn

  • POSTLấy token
  • GETLấy mẫu hoá đơn
  • GETDanh sách mẫu đã đăng ký
  • GETHạn mức hoá đơn
  • POSTTạo mẫu hoá đơn
  • POSTDuyệt số lượng hoá đơn
  • DELETEXoá mẫu chưa duyệt
  • POSTTạo hoá đơn
  • GETDanh sách hoá đơn
  • POSTKý hoá đơn nháp
  • GETTải hoá đơn PDF/XML
  • DELETEXoá hoá đơn nháp

Tra cứu

  • GETTra cứu mã số thuế

Webhook

  • GETDanh sách webhook
  • POSTThêm webhook
  • POSTNhận và kiểm tra
Trang chủTài liệuTra cứu mã số thuế
GET/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.

MarkdownOpenAPI

#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ộc

API 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ộc

Mã 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
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ộc

Luôn là tax_code.

idstringBắt buộc

Trùng tax_code.

tax_codestringBắt buộc

MST đã chuẩn hoá. 10 số, hoặc chi nhánh dạng 0312345678-001.

namestringBắt buộc

Tên đơn vị trên hồ sơ thuế.

name_internationalstring | nullBắt buộc

Tê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ộc

Mã trạng thái. Xem mục Trạng thái. Chỉ active là đang hoạt động.

status_labelstringBắt buộc

Câu tiếng Việt cùng nghĩa với status, dùng để hiện trên form.

tax_officestring | nullBắt buộc

Cơ quan thuế quản lý. null khi không có.

representativestring | nullBắt buộc

Người đại diện. null khi không có.

updated_atstringBắt buộc

Thời điểm cập nhật thông tin, ISO 8601, múi giờ +07:00.

200 OK
{
  "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.
suspendedTạ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.
inactiveKhô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.
unknownKhông xác định được trạng thái.

Chỉ phát hành khi active

Dùng name và address để điền người mua khi status là active. Các mã còn lại nghĩa là đơn vị không còn hoạt động bình thường. Nên báo cho người dùng trước khi tạo hoá đơn.

#Mã lỗi

Các trường hợp thường gặp:

401 unauthorized—Tuỳ chọn

Thiế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ọn

Không có đơn vị nào khớp MST đã nhập.

422 validation_error—Tuỳ chọn

MST sai định dạng (độ dài, ký tự không hợp lệ).

429 rate_limited—Tuỳ chọn

Vượt giới hạn số request tra cứu trong khoảng thời gian cho phép.

503 provider_unavailable—Tuỳ chọn

Không tra cứu được mã số thuế lúc này. Thử lại sau.

Trước đóXoá hoá đơn nhápTiếp theoDanh sách webhook
Trang này có hữu ích không?
Cập nhật lần cuối: 10/11/2026

Trên trang này

  • Giới thiệu
  • Endpoint
  • Header
  • Param
  • Ví dụ
  • Phản hồi
  • Trạng thái
  • Mã lỗi
Đăng nhậpBắt đầu ngay