# Tra cứu mã số thuế > Chỉ dùng endpoint, field, mã lỗi và ví dụ trong trang này. Không thêm API chưa được mô tả ở đây. `GET /v1/tax-codes/{mst}` 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. Vị trí: header. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `api_key` | string | có | API key của ứng dụng. Phải thuộc đúng app_id. | | `app_id` | string | 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. Vị trí: đường dẫn. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `mst` | string | 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: ```bash 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. | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `object` | string | có | Luôn là tax_code. | | `id` | string | có | Trùng tax_code. | | `tax_code` | string | có | MST đã chuẩn hoá. 10 số, hoặc chi nhánh dạng 0312345678-001. | | `name` | string | có | Tên đơn vị trên hồ sơ thuế. | | `name_international` | string \| null | có | Tên giao dịch quốc tế. null khi không có. | | `address` | string | có | Địa chỉ trên hồ sơ thuế. | | `status` | string | có | Mã trạng thái. Xem mục Trạng thái. Chỉ active là đang hoạt động. | | `status_label` | string | có | Câu tiếng Việt cùng nghĩa với status, dùng để hiện trên form. | | `tax_office` | string \| null | có | Cơ quan thuế quản lý. null khi không có. | | `representative` | string \| null | có | Người đại diện. null khi không có. | | `updated_at` | string | có | Thời điểm cập nhật thông tin, ISO 8601, múi giờ +07:00. | 200 OK: ```json { "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:** 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: | Trường | Kiểu | Bắt buộc | Mô tả | | --- | --- | --- | --- | | `401 unauthorized` | — | không | 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` | — | không | Không có đơn vị nào khớp MST đã nhập. | | `422 validation_error` | — | không | MST sai định dạng (độ dài, ký tự không hợp lệ). | | `429 rate_limited` | — | không | Vượt giới hạn số request tra cứu trong khoảng thời gian cho phép. | | `503 provider_unavailable` | — | không | Không tra cứu được mã số thuế lúc này. Thử lại sau. | Trang HTML: /docs/tax-codes Cập nhật: 10/11/2026