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

Phiên bản nâng cao của tra cứu MST: trả về danh sách người nộp thuế khớp 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}

Tính phí

Mỗi lần gọi = 1 request tính phí (bậc thang, cao hơn tra cứu cơ bản vì trả chi tiết & chi nhánh). 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ả về schema hợp nhất dùng chung với /tax-code. Với /tax-code-2, danh_sach gồm trụ sở chính + các chi nhánh.

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 + chi nhánh)

Mỗi phần tử trong danh_sach:

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ý
cqthuecap_tinh	string | null	Cơ quan thuế cấp tỉnh — null ở endpoint này
nguoi_dai_dien	string | null	Người đại diện — null ở endpoint này
ngay_thanh_lap	string | null	Ngày thành lập — null ở endpoint này
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)

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).

So với tra cứu cơ bản

Hai endpoint dùng chung schema (danh_sach[]). GET /tax-code (cơ bản) trả 1 pháp nhân kèm trường chi tiết (nguoi_dai_dien, ngay_thanh_lap, cqthuecap_tinh). GET /tax-code-2 trả nhiều đơn vị (trụ sở + chi nhánh) và để null các trường chi tiết đó — phù hợp rà soát tập đoàn/chuỗi chi nhánh. Chỉ nhận tax qua query, vẫn cần Bearer + Partner-Code.