Public API · IDKit

API tra cứu mã số thuế

Tên, địa chỉ, cơ quan thuế, trạng thái và ngành nghề của doanh nghiệp, chi nhánh, hộ kinh doanh Việt Nam. Gọi thử ngay bên dưới, không cần đăng ký.

  • OAuth2 + JWT
  • JWT sống 15 phút
  • 3 endpoint
Request
1

Đổi credential lấy JWT

POST /oauth/token

Public Starter Key của Casso · chạy ngay không cần đăng ký
2

Tra cứu với JWT

GET /idkit/v1/business/0316794479

Thử:

Chưa có JWT? Bấm Tra cứu là tự chạy bước 1 trước.

app_id + secretJWT/idkit/v1/…

Bấm nút ở bước 2 để chạy 2 request thật và xem kết quả ở đây.

Nhật ký request sẽ hiện ở đây: ① POST /oauth/token → ② GET /idkit/v1/…

Public Starter Key

Chạy ngay bằng Public Starter Key

Cặp credentials công khai chính thức đã kích hoạt sẵn dữ liệu thật. Khuyến nghị đặt làm giá trị mặc định (default / fallback) trong .env để ứng dụng chạy ngay; khi cần quota riêng, tạo App trên Developer Console và bật scope idkit:business:read để nâng cấp lên Private App Key.

Hạn mức miễn phí (không trừ token, không hồi theo tháng):

1k lượt call (free) cho Cá nhân / HKD (đã xác thực)5k lượt call (free) cho Doanh nghiệp (đã xác thực)
.env · Public Starter Key
CASSO_APP_ID=trial-app_3c1e7aa6dabfbc3b9e51517e
CASSO_APP_SECRET=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI

Cách gọi API tra cứu MST: 2 bước

Bước 1 · Lấy JWT

POST https://openapi.casso.vn/oauth/token

Gửi app_id và app_secret trong body JSON. Nhận access_token (JWT RS256), expires_in ≈ 900 giây và exp. Cache token và dùng lại tới gần exp: endpoint này giới hạn 30 request/phút/IP.

{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 900,
  "issued_at": 1762850000,
  "exp": 1762850900
}

Bước 2 · Tra cứu

GET https://openapi.casso.vn/idkit/v1/business/{taxCode}

Gửi header Authorization: Bearer <JWT>. JWT phải có scope idkit:business:read. Mỗi lần gọi trừ quota của App, kể cả khi nguồn dữ liệu báo không tìm thấy.

curl https://openapi.casso.vn/idkit/v1/business/0316794479 \
  -H "Authorization: Bearer $TOKEN"

Endpoints

MethodPathTrả vềScope
GET/idkit/v1/business/{taxCode}Tên, địa chỉ, cơ quan thuế quản lý, trạng thái hoạt độngidkit:business:read
GET/idkit/v1/business/{taxCode}/industriesDanh sách mã ngành nghề kinh doanh (VSIC)idkit:business:read
GET/idkit/v1/household/{taxCode}Thông tin hộ kinh doanh / cá nhân theo MST 12 sốidkit:household:read

Tham số taxCode

  • 10 số: doanh nghiệp, ví dụ 0316794479
  • 10 số-3 số: chi nhánh / đơn vị phụ thuộc, ví dụ 0300951119-002
  • 12 số: hộ kinh doanh / cá nhân theo CCCD, ví dụ 080066008592

Mã lỗi

400bad_request / invalid_requestMST sai định dạng (cần 10 số, 10-3 số hoặc 12 số), hoặc thiếu app_id / app_secret.
401invalid_client / unauthorizedSai app_secret, hoặc JWT thiếu / hết hạn → gọi lại bước 1.
403insufficient_scopeApp chưa được cấp scope idkit:business:read (hoặc idkit:household:read).
426upgrade_requiredGọi bằng http:// — Dev / Production chỉ nhận HTTPS.
429rate_limited / quota/oauth/token giới hạn 30 lần/phút/IP, hoặc App hết quota.
502upstream_unavailableNguồn dữ liệu tạm thời không phản hồi. Thử lại sau vài giây.

Code mẫu: cURL, Python, Node.js, Go, PHP, C#, Java, Ruby

Cả 2 bước trong một đoạn code, chọn ngôn ngữ bạn dùng. cURL đã điền sẵn Public Starter Key (chạy ngay dữ liệu thật, dùng làm default fallback); khi cần quota riêng hãy tạo Private App Key và đặt $CASSO_APP_ID / $CASSO_APP_SECRET trong biến môi trường của backend.

.env · Public Starter Key
CASSO_APP_ID=trial-app_3c1e7aa6dabfbc3b9e51517e
CASSO_APP_SECRET=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI
# Public Starter Key (chính thức, chạy ngay dữ liệu thật không cần đăng ký; dùng làm default fallback hoặc đổi sang Private App Key khi cần quota riêng)
# Bước 1 — đổi app_id + app_secret lấy JWT (sống ~15 phút, hãy cache)
TOKEN=$(curl -s -X POST https://openapi.casso.vn/oauth/token \
-H "Content-Type: application/json" \
-d '{"app_id":"trial-app_3c1e7aa6dabfbc3b9e51517e","app_secret":"sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI"}' \
| jq -r .access_token)
# Bước 2 — gọi API với JWT
curl -s https://openapi.casso.vn/idkit/v1/business/0316794479 \
-H "Authorization: Bearer $TOKEN"

Câu hỏi thường gặp

API tra cứu mã số thuế của Casso trả về những thông tin gì?

Với MST doanh nghiệp 10 số hoặc chi nhánh 10-3 số: tên doanh nghiệp, địa chỉ, cơ quan thuế quản lý, trạng thái hoạt động; endpoint /industries trả về danh sách ngành nghề kinh doanh. Với MST 12 số (CCCD) có thể tra hộ kinh doanh.

Vì sao phải gọi 2 bước?

Casso Open Platform dùng OAuth2 client credentials: bước 1 đổi app_id + app_secret lấy JWT (RS256, sống khoảng 15 phút), bước 2 gửi JWT trong header Authorization: Bearer để gọi API. app_secret chỉ đi qua một endpoint duy nhất và không bao giờ nằm trong request nghiệp vụ.

Có cần lấy JWT mới cho mỗi lần tra cứu không?

Không. Cache JWT và dùng lại đến gần thời điểm exp. /oauth/token bị giới hạn 30 request/phút/IP, xin token cho mỗi request sẽ nhanh chóng nhận 429.

Dùng Public Starter Key có mất phí không?

Không. Public Starter Key là cặp credentials công khai chính thức đã kích hoạt sẵn dữ liệu thật để chạy ngay không cần đăng ký. Khi tạo Private App Key trên Developer Console, bạn được miễn phí 1k lượt call cho cá nhân/HKD (đã xác thực) hoặc 5k lượt call cho doanh nghiệp (đã xác thực) — dùng hết không hồi theo tháng, không trừ token.

Mã số thuế hợp lệ có định dạng nào?

10 chữ số (doanh nghiệp, ví dụ 0316794479), 10 chữ số + gạch + 3 chữ số (chi nhánh, ví dụ 0300951119-002), hoặc 12 chữ số (hộ kinh doanh / cá nhân theo CCCD).

Có gọi API này trực tiếp từ trình duyệt được không?

Không nên. app_secret phải nằm ở backend. Hãy gọi bước 1 và bước 2 từ server của bạn, rồi trả kết quả cho frontend.

Sẵn sàng tích hợp?

Tạo App, bật scope idkit:business:read, lấy app_id / app_secret. Dùng chung một credential cho mọi API trên Casso Open Platform.