API tra cứu mã số thuế: Tự động lấy thông tin doanh nghiệp khi onboarding và xuất hóa đơn

Tra cứu mã số thuế để làm gì?

Khi một doanh nghiệp mới đăng ký, thanh toán, hay xuất hóa đơn cho bạn, thứ duy nhất bạn thường có là mã số thuế. Từ mã số thuế đó, bạn cần biết: tên công ty đầy đủ, địa chỉ đăng ký, cơ quan thuế quản lý, người đại diện, trạng thái còn hoạt động hay không.

Nhập tay những thông tin này vừa chậm vừa dễ sai — sai tên hay địa chỉ trên hóa đơn có thể khiến hóa đơn không hợp lệ. API tra cứu mã số thuế của TConnect trả về toàn bộ thông tin đó chỉ từ một mã số thuế, trong một lời gọi.

Endpoint & tham số

GET /tax-code?tax={mst}

• Không cần mã hóa — chỉ truyền tax qua query parameter (khác với các API cần AES).
• Vẫn dùng chung xác thực Open API: Authorization: Bearer <access_token> + Partner-Code.

Ví dụ gọi API

Tra cứu chính mã số thuế của TConnect (0319074775):

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

Kết quả trả về:

{
  "success": true,
  "ma_so_thue": "0319074775",
  "masothue_id": "0319074775",
  "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",
  "cqthuecap_tinh": "Chi cục thuế Hồ Chí Minh",
  "cqthue_ql": "Thuế cơ sở 7 Thành phố Hồ Chí Minh",
  "nguoi_dai_dien": null,
  "ngay_thanh_lap": null,
  "tthai": null,
  "ten_tthai": null
}

Các trường trả về

Một số trường có thể là null khi cơ quan thuế không công bố dữ liệu tương ứng cho mã số thuế đó — hãy xử lý null an toàn ở phía client.

Ứng dụng thực tế

API tra cứu mã số thuế xuất hiện ở rất nhiều điểm chạm trong nghiệp vụ B2B. Dưới đây là các tình huống phổ biến nhất.

1. Tự động điền form onboarding từ mã số thuế

Người dùng chỉ nhập mã số thuế, phần còn lại điền tự động:

function autofill_company_form(mst):
    info = GET /tax-code?tax={mst}
 
    if not info.success:
        show_error("Không tìm thấy mã số thuế này")
        return
 
    form.company_name.value = info.ten_cty
    form.address.value      = info.dia_chi
    form.tax_office.value   = info.cqthue_ql
    form.representative.value = info.nguoi_dai_dien or ""   // có thể null

Trải nghiệm: gõ mã số thuế → thấy ngay tên công ty → giảm sai sót và bỏ được nhiều ô nhập tay.

2. Điền thông tin người mua khi xuất hóa đơn điện tử

Đây là tình huống quan trọng nhất. Hóa đơn điện tử ghi sai tên hoặc địa chỉ người mua có thể bị coi là không hợp lệ, phải điều chỉnh/thay thế — mất thời gian và rủi ro về thuế. Thay vì để nhân viên gõ tay, lấy trực tiếp thông tin đăng ký từ cơ quan thuế:

function build_invoice_buyer(mst):
    info = GET /tax-code?tax={mst}
 
    if not info.success:
        raise Error("mã số thuế người mua không hợp lệ — không thể xuất hóa đơn")
 
    return {
        buyer_tax_code: info.ma_so_thue,
        buyer_name:     info.ten_cty,      // ĐÚNG tên đăng ký thuế
        buyer_address:  info.dia_chi       // ĐÚNG địa chỉ đăng ký
    }

Kết hợp với hệ thống hóa đơn điện tử, quy trình "nhập mã số thuế → tự điền người mua → phát hành hóa đơn" gần như tức thì và không còn hóa đơn sai thông tin.

3. Kiểm tra doanh nghiệp khi KYB (Know Your Business)

Trước khi mở tài khoản, ký hợp đồng hay cấp hạn mức công nợ, đối chiếu tên khai báo với tên đăng ký chính thức:

function verify_business(mst, declared_name):
    info = lookup_tax_code(mst)
 
    // mã số thuế không tồn tại
    if not info.success:
        return { ok: false, reason: "mst_not_found" }
 
    // Tên khai báo lệch quá nhiều với tên đăng ký
    if similarity(declared_name, info.ten_cty) < 0.7:
        flag_for_manual_review(mst, declared_name, info.ten_cty)
 
    return { ok: true, official_name: info.ten_cty }

4. Kiểm tra trạng thái hoạt động của mã số thuế

Trường tthai / ten_tthai cho biết doanh nghiệp còn hoạt động hay đã ngừng, tạm ngừng, bỏ địa chỉ… Rất hữu ích để chặn giao dịch với đối tác rủi ro:

function is_safe_to_transact(mst):
    info = lookup_tax_code(mst)
 
    if not info.success:
        return false   // mã số thuế không tồn tại
 
    // Trạng thái bất thường → cảnh báo trước khi giao dịch/xuất hóa đơn
    if info.ten_tthai is not null and "ngừng" in lower(info.ten_tthai):
        warn("Đối tác đang ở trạng thái: " + info.ten_tthai)
        return false
 
    return true

5. Đối chiếu nhà cung cấp trên hóa đơn đầu vào

Khi nhận hóa đơn mua vào, đối chiếu sellerTaxCode với thông tin tra cứu để phát hiện nhà cung cấp ngừng hoạt động hoặc dữ liệu lệch — kết hợp rất tự nhiên với API tra cứu hóa đơn đầu vào:

function reconcile_supplier(invoice):
    info = lookup_tax_code(invoice.sellerTaxCode)
 
    if not info.success:
        flag("mã số thuế người bán không tra được", invoice.id)
    else if similarity(invoice.sellerName, info.ten_cty) < 0.8:
        flag("Tên người bán lệch với đăng ký thuế", invoice.id)

6. Làm giàu dữ liệu CRM / danh bạ khách hàng hàng loạt

Có sẵn danh sách mã số thuế nhưng thiếu tên/địa chỉ chuẩn? Chạy batch để chuẩn hóa toàn bộ (nhớ cache và giới hạn tốc độ):

function enrich_customers(mst_list):
    for mst in mst_list:
        info = lookup_tax_code_cached(mst)   // xem phần Cache bên dưới
        if info.success:
            update_customer(mst, name=info.ten_cty, address=info.dia_chi,
                            tax_office=info.cqthue_ql)

7. Xác thực mã số thuế tại form thanh toán và hợp đồng

Ngay khi khách nhập mã số thuế vào form thanh toán B2B hoặc hợp đồng, gọi tra cứu để xác nhận mã số thuế có thật và hiển thị tên công ty để khách kiểm tra lại — giảm nhầm lẫn và tranh chấp về sau.

Cache để tối ưu chi phí và tốc độ

Thông tin doanh nghiệp thay đổi rất ít. Với mã số thuế tra đi tra lại nhiều lần, hãy cache:

function lookup_tax_code_cached(mst):
    cache_key = "taxcode:{mst}"
 
    cached = cache.get(cache_key)
    if cached exists:
        return parse_json(cached)
 
    result = GET /tax-code?tax={mst}
 
    // Chỉ cache khi tra cứu thành công; TTL vài ngày là hợp lý
    if result.success:
        cache.set(cache_key, result, ttl = 7 days)
 
    return result

Cache vừa giảm độ trễ, vừa tiết kiệm số request tính phí.

Kết luận

Tra cứu mã số thuế là một API nhỏ nhưng xuất hiện ở khắp nơi trong nghiệp vụ B2B: onboarding, KYB, xuất hóa đơn, đối chiếu nhà cung cấp. Chỉ cần một mã số thuế, bạn có ngay thông tin doanh nghiệp chuẩn từ cơ quan thuế — không mã hóa phức tạp, tích hợp trong vài phút.

Xem đặc tả đầy đủ tại tài liệu API tra cứu mã số thuế. Cần khóa sandbox để thử? Liên hệ TConnect.