# 🏠 API tra cứu Mã số thuế

Nguồn HTML: https://www.vietqr.io/tra-cuu-mst
Bản Markdown này: https://www.vietqr.io/tra-cuu-mst.md

Thuộc bộ API IDKit của Casso Open Platform: tra cứu thông tin doanh nghiệp, chi nhánh, ngành nghề và hộ kinh doanh theo mã số thuế, để lấy thông tin xuất hóa đơn khi khách hàng thanh toán.

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

> **API tra cứu mã số thuế — API cũ đã ngừng hỗ trợ (DEPRECATED).**
>
> API `api.vietqr.io/v2/business/{taxCode}` ĐÃ NGỪNG HỖ TRỢ (DEPRECATED) tích hợp mới. Mọi dự án hiện tại BẮT BUỘC sử dụng Casso Open Platform (`openapi.casso.vn`) ngay từ bây giờ. Endpoint cũ chỉ duy trì hạn chế cho các hệ thống cũ trước khi ngắt hoàn toàn vào **31/12/2026**.

## Demo gọi thật

Trang HTML nhúng demo từ Casso Open Platform: mỗi lần bấm Tra cứu là 2 lời gọi thật, `POST /oauth/token` rồi `GET /idkit/v1/business/{taxCode}`, bằng Public Starter Key (chạy ngay dữ liệu thật, không cần đăng ký). Thử trên Open Platform: https://open.casso.vn/api-tra-cuu-mst?mst=0316794479&utm_source=vietqr&utm_content=markdown

## Gọi API trong 2 bước

Gọi từ backend, không đặt app_secret trên trình duyệt.

```bash
# 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: tra cứu
curl -s https://openapi.casso.vn/idkit/v1/business/0316794479 \
  -H "Authorization: Bearer $TOKEN"

# Ngành nghề (VSIC):     GET /idkit/v1/business/{taxCode}/industries
# Hộ kinh doanh (12 số): GET /idkit/v1/household/{taxCode}
```

**Public Starter Key (Chạy ngay — Không cần đăng ký):** 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` hoặc config để ứng dụng chạy ngay lập tức; khi cần quota riêng (miễn phí 1k–5k lượt, không hồi theo tháng), nâng cấp lên **Private App Key** tại `open.casso.vn`.

## Tham số và response

Header `Authorization: Bearer <JWT>` · `taxCode`: 10 số, 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh)

| Endpoint | Trả về | Scope |
| --- | --- | --- |
| `GET /idkit/v1/business/{taxCode}` | Tên, địa chỉ, cơ quan thuế quản lý, trạng thái hoạt động | `idkit:business:read` |
| `GET /idkit/v1/business/{taxCode}/industries` | Danh 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` |

### Trường trong response

| Trường | Ý nghĩa |
| --- | --- |
| `business.taxCode` | Mã số thuế |
| `business.name` | Tên người nộp thuế |
| `business.address` | Địa chỉ đăng ký |
| `business.taxDepartment` | Cơ quan thuế quản lý |
| `business.status` | Trạng thái hoạt động |
| `business.source` | Nguồn dữ liệu |

### Mã lỗi

| HTTP | Mã | Ý nghĩa |
| --- | --- | --- |
| 400 | bad_request | MST sai định dạng (10 số, 10-3 số hoặc 12 số). |
| 401 | unauthorized | JWT thiếu hoặc hết hạn → gọi lại bước 1. |
| 403 | insufficient_scope | App chưa được cấp scope `idkit:business:read`. |
| 429 | rate_limited / quota | `/oauth/token` giới hạn 30 lần/phút/IP, hoặc App hết quota. |
| 502 | upstream_unavailable | Nguồn dữ liệu tạm thời không phản hồi. |

## Khác gì so với API cũ

|  | API cũ | Casso Open Platform |
| --- | --- | --- |
| Base URL | `api.vietqr.io/v2/business/{taxCode}` | `openapi.casso.vn/idkit/v1/business/{taxCode}` |
| Xác thực | Gọi công khai, không cần key | OAuth2: secret chỉ dùng đổi token, request mang JWT |
| Dữ liệu | Doanh nghiệp | Doanh nghiệp, chi nhánh, ngành nghề (VSIC), hộ kinh doanh |
| Mã trả về | HTTP 200 kèm `code` (`00`, `51`, `52`) | Mã HTTP chuẩn (400, 401, 403, 429, 502) |
| Code mẫu | cURL | 18 ngôn ngữ + prompt cho AI agent |

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

### API tra cứu mã số thuế 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ố 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 (sống khoảng 15 phút), bước 2 gửi JWT trong header Authorization: Bearer để gọi API.

### 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 hết hạn. /oauth/token giới hạn 30 request/phút/IP.

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

## API cũ (DEPRECATED — Ngắt hoàn toàn 31/12/2026)

Đổi sang API mới:

|  | API cũ | Open Platform |
| --- | --- | --- |
| Endpoint | `GET api.vietqr.io/v2/business/{taxCode}` | `GET openapi.casso.vn/idkit/v1/business/{taxCode}` |
| Xác thực | Không cần key | `Authorization: Bearer <JWT>` (lấy từ /oauth/token) |
| `data.id` | `business.taxCode` | Cùng là mã số thuế (theo response mẫu) |
| `data.name` | `business.name` | Theo response mẫu |
| `data.address` | `business.address` | Theo response mẫu |
| `data.internationalName`, `data.shortName` | Cần xác nhận | Không có trong response mẫu của Open Platform |

### Đặc tả API

### GET /business/{taxCode}

`https://api.vietqr.io/v2/business/{taxCode}`

Tra cứu thông tin doanh nghiệp

API tra cứu thông tin doanh nghiệp dựa vào mã số thuế, để lấy thông tin xuất hóa đơn khi KH thanh toán

#### Tham số

| Trường | Bắt buộc | Loại | Mô tả | Ví dụ |
| --- | --- | --- | --- | --- |
| taxCode | Có | path | Mã số thuế của DN |  |

#### Response 200

Thành công

Success — Success - Thành công

```json
{
  "code": "00",
  "desc": "Success - Thành công",
  "data": {
    "id": "0316794479",
    "name": "CÔNG TY TNHH CASSO",
    "internationalName": "CASSO COMPANY LIMITED",
    "shortName": "CASSO",
    "address": "I.102D, Nhà A, Khu Công Nghệ Phần Mềm, Đường Nội Bộ Đại học Quốc Gia Thành Phố Hồ Chí Minh, Khu phố 6, Phường Linh Trung, Thành phố Thủ Đức, Thành phố Hồ Chí Minh, Việt Nam"
  }
}
```

Tax Code Invalid — Tax invalid - Mã số thuế không chính xác

```json
{
  "code": "51",
  "desc": "Tax invalid - Mã số thuế không chính xác"
}
```

Tax Code Not Found — Tax not found - Mã số thuế không tồn tại

```json
{
  "code": "52",
  "desc": "Tax not found - Mã số thuế không tồn tại"
}
```

#### Response 429

Too Many Request - Gọi API vượt quá Limit Rate
