# TConnect Open API — Tra cứu mã số thuế (single-file cho AI Agent)

FILE NÀY LÀ ĐẶC TẢ ĐẦY ĐỦ — AI Agent có thể TÍCH HỢP TRỰC TIẾP từ đây, không cần đọc tài liệu web.
Cần: (1) Base URL, (2) token Bearer (login Keycloak) + Partner-Code, rồi gọi endpoint ở "ENDPOINT" bên dưới.

## Mô tả
API tra cứu thông tin doanh nghiệp theo MÃ SỐ THUẾ (MST): tên công ty, địa chỉ đăng ký,
cơ quan thuế quản lý, người đại diện, ngày thành lập, trạng thái hoạt động.
Chỉ cần 1 MST → 1 lời gọi GET, không mã hóa tham số. Dùng cho auto-fill onboarding, KYB,
chuẩn hóa thông tin trước khi xuất hóa đơn, đối chiếu nhà cung cấp.

## Base URL
- Staging:    https://sme-open-api-sandbox.tconnect.vn
- Production: Được cung cấp sau khi hoàn tất kiểm thử
(Chỉ test trên Staging.)

## Xác thực (JWT Bearer — Keycloak, dùng chung với các Open API khác)
1) Lấy token: POST {BASE}/openapi/v1/auth/login
   - Header: Partner-Code: <mã Merchant>
   - Body: {"data": AES-256-CBC_hex({username,password,client_id,client_secret}, aes_key)}
     (AES-256-CBC, IV 16B nối đầu ciphertext, PKCS7, hex. TConnect cấp: partner_code, client_id, client_secret, aes_key.)
   - Response: { access_token, refresh_token, expires_in, token_type:"Bearer", ... }  (Keycloak realm 'tconnect')
2) Mọi request thêm header:
   Authorization: Bearer <access_token>
   Partner-Code: <mã Merchant>
3) Hết hạn: POST {BASE}/openapi/v1/auth/refresh-token để lấy access_token mới.
Keycloak: issuer https://account-sandbox.tconnect.vn/realms/tconnect (sandbox) · JWKS .../protocol/openid-connect/certs (RS256).

LƯU Ý: Bản thân endpoint /tax-code KHÔNG mã hóa body/tham số (chỉ query param `tax`).
Việc mã hóa AES chỉ áp dụng cho bước login ở trên để lấy token.

===========================================================================
ENDPOINT
===========================================================================

GET /tax-code?tax={mst}
Query:
  tax (string, bắt buộc) = mã số thuế cần tra cứu.
Response 200: {
  success (bool),
  ma_so_thue, masothue_id,            // mã số thuế
  ten_cty,                            // tên đầy đủ công ty/doanh nghiệp
  dia_chi,                            // địa chỉ đăng ký kinh doanh
  cqthuecap_tinh (string|null),       // cơ quan thuế cấp tỉnh
  cqthue_ql,                          // cơ quan thuế quản lý trực tiếp
  nguoi_dai_dien (string|null),       // người đại diện pháp luật
  ngay_thanh_lap (YYYY-MM-DD|null),   // ngày thành lập
  tthai (string|null), ten_tthai (string|null)   // mã / tên trạng thái hoạt động
}
Ghi chú: 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.
Nếu MST không tồn tại: success=false (không có dữ liệu doanh nghiệp).

Ví dụ (tax=0319074775):
{"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}

## CURL MẪU
# Tra cứu MST
curl "$BASE/tax-code?tax=0319074775" -H "Authorization: Bearer $TOKEN" -H "Partner-Code: $PC"

## GHI CHÚ
- Mỗi request được đo đếm (đối soát qua requests.byEndpoint), dùng CHUNG bộ đếm với API tra cứu hóa đơn đầu vào.
- Thông tin doanh nghiệp thay đổi rất ít → nên cache theo MST để giảm số request.