Tra cứu mã số thuế — chi tiết & chi nhánh

Tra cứu danh sách người nộp thuế theo mã số thuế — gồm trụ sở chính và các chi nhánh/đơn vị trực thuộc, kèm cơ quan thuế quản lý và trạng thái từng đơn vị. Dữ liệu realtime từ Tổng cục Thuế.

GET /tax-code-2?tax={mst}

Khi nào dùng endpoint này

Dùng khi bạn cần liệt kê trụ sở + toàn bộ chi nhánh/đơn vị trực thuộc của một mã số thuế (rà soát tập đoàn/chuỗi chi nhánh). Nếu chỉ cần thông tin chi tiết của một pháp nhân (người đại diện, ngày thành lập), dùng Tra cứu mã số thuế.

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ố). Chỉ nhận MST chính (không có dấu -).
attempts	number		Số lần thử tối đa (mặc định 5, trần 10). Tùy chọn.

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 người nộp thuế
danh_sach	array	Danh sách đơn vị khớp — trụ sở chính + các chi nhánh

Mỗi phần tử trong danh_sach là một đơn vị (trụ sở hoặc chi nhánh):

Trường	Kiểu	Mô tả
stt	string	Số thứ tự
ma_so_thue	string	MST đơn vị (chi nhánh có dạng 0316520735-001)
la_chi_nhanh	boolean	true nếu là chi nhánh/đơn vị trực thuộc
ten_cty	string | null	Tên người nộp thuế
dia_chi	string | null	Địa chỉ trụ sở/kinh doanh
cqthue_ql	string | null	Cơ quan thuế quản lý
ten_tthai	string | null	Trạng thái MST (vd NNT đang hoạt động)
dang_hoat_dong	boolean | null	Suy từ trạng thái (true nếu đang hoạt động)

Trường luôn null ở endpoint này

Endpoint này tập trung vào danh sách đơn vị, nên các trường cqthuecap_tinh, nguoi_dai_dien, ngay_thanh_lap luôn trả null. Cần các thông tin chi tiết pháp nhân này thì dùng Tra cứu mã số thuế.

cURL

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

Ví dụ response

{
  "ma_so_thue": "0316520735",
  "success": true,
  "danh_sach": [
    {
      "stt": "1",
      "ma_so_thue": "0316520735",
      "la_chi_nhanh": false,
      "ten_cty": "CÔNG TY TNHH TƯ VẤN - ĐẠI LÝ THUẾ TFA",
      "dia_chi": "1329/1G Đường APĐ 09, Phường An Phú Đông, TP Hồ Chí Minh",
      "cqthue_ql": "Thuế cơ sở 12 Thành phố Hồ Chí Minh",
      "cqthuecap_tinh": null,
      "nguoi_dai_dien": null,
      "ngay_thanh_lap": null,
      "ten_tthai": "NNT đang hoạt động",
      "dang_hoat_dong": true
    },
    {
      "stt": "2",
      "ma_so_thue": "0316520735-001",
      "la_chi_nhanh": true,
      "ten_cty": "CHI NHÁNH CÔNG TY TNHH TƯ VẤN - ĐẠI LÝ THUẾ TFA",
      "dia_chi": "125/6 Đường APĐ 09, Phường An Phú Đông, TP Hồ Chí Minh",
      "cqthue_ql": "Thuế cơ sở 12 Thành phố Hồ Chí Minh",
      "cqthuecap_tinh": null,
      "nguoi_dai_dien": null,
      "ngay_thanh_lap": null,
      "ten_tthai": "NNT đang hoạt động",
      "dang_hoat_dong": true
    }
  ]
}

Không tìm thấy

Nếu MST hợp lệ nhưng không có dữ liệu, API trả success: false và danh_sach: [] (vẫn tính phí 1 request).

Không cần mã hóa

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