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). Trợ lý AI gọi cùng các route này dưới dạng tool qua máy chủ 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: 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 ở 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ó |
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 (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ớiContent-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ó):
pagebắt đầu từ 0,perpagesố 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>|DESChoặ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 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, bản máy đọc ở /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.