Tra cứu mã số thuế

Tra cứu thông tin một doanh nghiệp theo mã số thuế: tên, địa chỉ, cơ quan thuế quản lý, người đại diện, ngày thành lập và trạng thái hoạt động.

GET /tax-code?tax={mst}

Khi nào dùng endpoint này

Dùng khi bạn cần thông tin chi tiết của một pháp nhân (kèm người đại diện, ngày thành lập, cơ quan thuế cấp tỉnh). Nếu cần liệt kê cả chi nhánh/đơn vị trực thuộc, dùng Tra cứu MST — chi tiết & chi nhánh.

Tính phí

Mỗi lần gọi = 1 request tính phí (bậc thang). Xem Tính giá theo request.

Query Parameters

Name	Type	Bắt buộc	Mô tả
tax	string	✅	Mã số thuế cần tra cứu (10 hoặc 13 số)

Response

Trường	Kiểu	Mô tả
ma_so_thue	string	Mã số thuế đã tra cứu
success	boolean	true nếu tìm thấy doanh nghiệp
danh_sach	array	Thông tin doanh nghiệp — endpoint này trả đúng 1 phần tử

Phần tử trong danh_sach:

Trường	Kiểu	Mô tả
stt	string	Số thứ tự (luôn "1")
ma_so_thue	string	Mã số thuế của doanh nghiệp
la_chi_nhanh	boolean	true nếu MST tra là chi nhánh
ten_cty	string | null	Tên đầy đủ công ty/doanh nghiệp
dia_chi	string | null	Địa chỉ đăng ký kinh doanh
cqthue_ql	string | null	Cơ quan thuế quản lý trực tiếp
cqthuecap_tinh	string | null	Cơ quan thuế cấp tỉnh
nguoi_dai_dien	string | null	Người đại diện pháp luật
ngay_thanh_lap	string (YYYY-MM-DD) | null	Ngày thành lập
ten_tthai	string | null	Tên trạng thái hoạt động
dang_hoat_dong	boolean | null	Suy từ trạng thái (true nếu đang hoạt động)

cURL

curl "$BASE/tax-code?tax=0319074775" \
  -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC"

Ví dụ response

{
  "ma_so_thue": "0319074775",
  "success": true,
  "danh_sach": [
    {
      "stt": "1",
      "ma_so_thue": "0319074775",
      "la_chi_nhanh": false,
      "ten_cty": "CÔNG TY CỔ PHẦN GIẢI PHÁP T CONNECT",
      "dia_chi": "232 Nguyễn Lương Bằng, Phường Tân Mỹ, Thành phố Hồ Chí Minh, Việt Nam",
      "cqthue_ql": "Thuế cơ sở 7 Thành phố Hồ Chí Minh",
      "cqthuecap_tinh": "Chi cục thuế Hồ Chí Minh",
      "nguoi_dai_dien": null,
      "ngay_thanh_lap": null,
      "ten_tthai": null,
      "dang_hoat_dong": null
    }
  ]
}

Xử lý null an toàn

Nhiều trường có thể null khi cơ quan thuế không công bố — client cần xử lý null an toàn.

Không tìm thấy

Nếu MST không tồn tại: success: false và danh_sach: [] (vẫn tính phí 1 request).

Không cần mã hóa

API chỉ nhận tax qua query parameter, không cần AES. Vẫn cần header xác thực Bearer + Partner-Code.