# Gọi API Tino

Ứng dụng và phần mềm của khách gọi API Tino thay khách qua gateway `https://api.tino.vn/v1/<route>`: mỗi route chạy route UserAPI cùng tên bằng tài khoản của khách, trong phạm vi quyền của token. Body và câu trả lời giữ nguyên dạng của UserAPI (xem [Dữ liệu cá nhân](#du-lieu-ca-nhan)). Trợ lý AI gọi cùng các route này dưới dạng tool qua [máy chủ MCP](/docs/mcp).

Cập nhật: 2026-10-21. Danh sách route, quyền, tên và tham số đúng như gateway đang chạy; mẫu response là câu trả lời thật, đã che dữ liệu cá nhân.

## Xác thực

Mọi route cần header `Authorization: Bearer <token>`, một trong hai loại token:

| Token | Tiền tố | Có từ đâu | Gọi được |
| --- | --- | --- | --- |
| Token ứng dụng (access token) | `tinoat_` | [Đăng nhập bằng Tino](/docs/oauth): khách đồng ý cấp quyền cho ứng dụng | route thuộc các quyền khách đã đồng ý; không bao giờ có `domains:owner` |
| Token API cá nhân | `tinopat_` | [khách tự tạo](/docs/personal-tokens) ở `https://auth.tino.vn/me/security`, mục Token API | route thuộc các quyền khách chọn, kể cả `domains:owner` (bắt buộc giới hạn IP); chỉ từ IP trong danh sách nếu có |

```bash
curl https://api.tino.vn/v1/details -H "Authorization: Bearer $TINO_TOKEN"
```

Mỗi trang route ghi quyền (scope) cần có và loại token gọi được.

Ngoại lệ: route công khai không cần token và gọi thẳng `https://api.tino.vn` (không có `/v1`), hiện có [Tra whois tên miền](/docs/api/get-whois-domain) (`GET /whois/<tên miền>`).

## Gửi tham số

- Tham số đường dẫn: tài liệu viết `@id`, `@vmid`…; thay bằng giá trị thật, ví dụ `GET /v1/service/12345`.
- `GET`, `DELETE`: tham số ở query string.
- `POST`, `PUT`: body JSON với `Content-Type: application/json`. Gateway cũng đọc query string, và body form (`application/x-www-form-urlencoded`).
- Phân trang (các route danh sách có): `page` bắt đầu từ 0, `perpage` số dòng mỗi trang; câu trả lời có `page.current`, `page.total`.
- Lọc và sắp xếp: `filter[<khoá>]=<giá trị>`, `orderby=<trường>|DESC` hoặc `|ASC`.

## Dữ liệu cá nhân

Gateway `/v1` trả nguyên câu trả lời của route, gồm cả thông tin định danh của tài khoản, liên hệ và chủ thể tên miền (số giấy tờ, ngày sinh, số điện thoại, địa chỉ, mã số thuế): token gọi được là của chủ tài khoản hoặc được chủ tài khoản cho phép. Giữ token như mật khẩu; không ghi log, không lưu các trường này khi ứng dụng không cần.

[Máy chủ MCP](/docs/mcp) thì lọc các trường định danh trước khi gửi kết quả cho trợ lý AI.

## Lỗi

Gateway từ chối bằng body `{"error": ["<mã>"]}`; lỗi 401 và `insufficient_scope` kèm header `WWW-Authenticate: Bearer error="<mã>"` (có `scope` và `resource_metadata` cho client MCP).

| HTTP | `error` | Nguyên nhân | Xử lý |
| --- | --- | --- | --- |
| 401 | `invalid_token` | token sai, hết hạn hoặc đã bị thu hồi | ứng dụng làm mới token; token cá nhân thì tạo token mới |
| 403 | `insufficient_scope` | token không có quyền của route, hoặc route không có trong gateway | xin thêm quyền (ứng dụng) hoặc tạo token có thêm quyền (token cá nhân) |
| 403 | `ip_not_allowed` | token API cá nhân gọi từ IP ngoài danh sách giới hạn | gọi từ IP đã khai, hoặc tạo token với danh sách IP mới |
| 403 | `ipnotallowed` | IP gọi API đang bị Tino chặn | liên hệ Tino |

Lỗi nghiệp vụ của từng route (ví dụ dịch vụ không tồn tại) giữ nguyên câu trả lời của UserAPI, thường là HTTP 200 kèm `{"error": ["<mã>"]}`; thao tác thành công thường kèm `{"info": ["<mã>"]}`.

## Danh sách route

Mỗi route một trang: tham số, ví dụ cURL, JavaScript, PHP, mẫu response; mục lục theo sản phẩm ở [API Reference](/docs/reference), bản máy đọc ở [/openapi.json](/openapi.json). Bản Markdown cho LLM: thêm `.md` vào đường dẫn trang (ví dụ `/docs/api/get-details.md`); toàn bộ ở [/llms-full.txt](/llms-full.txt).