# Bắt đầu với Tino Uptime

Tino Uptime kiểm website, máy chủ, cổng dịch vụ, bản ghi DNS, chứng chỉ SSL và hạn tên miền từ các điểm dò ở Việt Nam và quốc tế. Khi đích lỗi, Tino Uptime mở sự cố và báo qua email, Telegram, Discord, Slack, webhook hoặc Zalo. API của dịch vụ cho ứng dụng của bạn quản lý monitor, đọc uptime, kết quả kiểm, sự cố và kênh cảnh báo của gói Tino Uptime.

Cập nhật: 2026-10-24. Nguồn: module Tino Uptime của Tino và OpenAPI của Tino Uptime.

## Gọi API

| Mục | Giá trị |
| --- | --- |
| Địa chỉ | `https://api.tino.vn/service/<id dịch vụ>/uptime/…` |
| Xác thực | `Authorization: Bearer <token>`: token đăng nhập của chủ dịch vụ Tino Uptime |
| Body | JSON, `Content-Type: application/json` |
| Từng route | mục Tino Uptime ở [API Reference](/docs/reference#tino-uptime) |

- Body luôn là JSON. Với [Sửa monitor](/docs/api/uptime-put-monitors-monitor), chỉ gửi trường cần đổi.
- Chỉ các tham số ghi ở từng route được chuyển tiếp. Tino Uptime từ chối trường lạ trong body (422 `validation_failed`).
- ID monitor, sự cố, kênh trong đường dẫn là UUID; sai dạng trả 400 `invalid_request`.
- Phần chưa có trong API này (trang trạng thái, máy chủ, WordPress, cảnh báo CVE) mở ở bảng điều khiển Tino Uptime bằng `login_url` của [Tổng quan gói](/docs/api/uptime-get-overview).

Gateway `/v1` chưa mở các route Tino Uptime: token ứng dụng (`tinoat_`) và [token API cá nhân](/docs/personal-tokens) (`tinopat_`) chưa gọi được. Token đăng nhập là token khách dùng ở khu vực khách hàng tino.vn; [SDK](/docs/sdk) lấy được bằng đăng nhập mã OTP:

```python
from tino_userapi import TinoClient

client = TinoClient()
client.request_login_otp("you@example.com")
client.verify_login_otp("you@example.com", input("Mã OTP: "))
print(client.request("GET", "/service/100002/uptime/monitors", query={"state": "down"}))
```

`100002` là ID dịch vụ Tino Uptime: cách tìm ở mục dưới.

## Tìm dịch vụ Tino Uptime

Mỗi tài khoản Tino có một tài khoản Tino Uptime; gói đang dùng gắn với đúng một dịch vụ.

1. Nhận diện bằng module của dịch vụ: [Chi tiết dịch vụ](/docs/api/get-service-id) (`GET https://api.tino.vn/service/<id>`, cùng token đăng nhập) có `service.acc_module` là `"tino_uptime"`. Danh sách ứng viên lấy ở [Danh sách dịch vụ](/docs/api/get-service).
2. Gọi [Tổng quan gói](/docs/api/uptime-get-overview) (`GET /service/<id>/uptime`):

| Kết quả | Nghĩa |
| --- | --- |
| 200 | gói Tino Uptime đang dùng của khách: gọi các route khác với ID này |
| 404 `service_not_linked` | dịch vụ không còn là gói đang dùng (khách đã chuyển sang dịch vụ khác): thử dịch vụ Tino Uptime kế tiếp |
| 404 `invalid method` | dịch vụ không phải Tino Uptime hoặc không tồn tại |
| 404 `service_not_found` | dịch vụ của tài khoản khác |
| 404 `account_not_found` | chưa có tài khoản Tino Uptime cho dịch vụ: liên hệ hỗ trợ Tino |

## Hạn mức gói

Hạn mức nằm ở `subscription.limits` của [Tổng quan gói](/docs/api/uptime-get-overview), số đang dùng ở [Mức dùng](/docs/api/uptime-get-usage). Đọc hạn mức từ API, đừng ghi cứng: số của từng gói có thể đổi.

| Trường | Nghĩa |
| --- | --- |
| `max_monitors` | số monitor tối đa |
| `min_interval_s` | chu kỳ kiểm ngắn nhất (giây) |
| `raw_retention_days` | số ngày xem được kết quả kiểm từng lượt |
| `locations` | vị trí dò được dùng: `vn-cmc`, `vn-vt` (Việt Nam), `intl` (quốc tế) |
| `channels` | loại kênh cảnh báo được tạo |

Vượt hạn mức trả 403 `entitlement_exceeded`; `details.resource` chỉ hạn mức (`monitors`, `min_interval_s`, `locations`, `channels`). Khi dịch vụ bị tạm ngưng, tài khoản Tino Uptime chỉ đọc được: thao tác ghi trả 403 `account_suspended`. Sau khi hạ gói, monitor vượt hạn mức bị dừng (`disabled_reason: paused_by_plan`, đếm ở `monitors_paused_by_plan`).

## Loại monitor

[Tạo monitor](/docs/api/uptime-post-monitors) nhận `name`, `interval_s` (30–86400 giây, không dưới `limits.min_interval_s`), `locations` và `settings`. `settings.type` quyết định các trường còn lại:

| `type` | Bắt buộc | Tuỳ chọn |
| --- | --- | --- |
| `http` | `url` | `method` (`GET`, `HEAD`, `POST`), `expected_status` (mảng mã HTTP, tối đa 20), `follow_redirects` (mặc định `true`), `max_latency_ms` (1–60000), `headers` (object), `body` (tối đa 4096 ký tự), `basic_auth` (`username`, `password`) |
| `keyword` | `url`, `keyword` (1–100 ký tự) | `mode` (`present`, `absent`), `case_sensitive`, `method` (`GET`, `POST`) và các tuỳ chọn còn lại của `http` |
| `ssl` | `host` | `port` (443, 465, 993, 995), `warn_days` (1–90, mặc định 14) |
| `domain` | `domain` | `warn_days` (1–120, mặc định 30) |
| `ping` | `host` | — |
| `tcp` | `host`, `port` (1–65535) | — |
| `dns` | `name`, `record_type` (`A`, `AAAA`, `CNAME`, `MX`, `NS`, `TXT`) | `expected` (mảng giá trị, tối đa 20), `resolver` (IP hoặc IP kèm cổng 53; bỏ trống thì hỏi máy chủ tên miền có thẩm quyền) |
| `heartbeat` | — | `grace_s` (0–86400, mặc định 300) |

- `heartbeat` đảo chiều: hệ thống của bạn gọi `settings.ping_url` sau mỗi lần chạy. `ping_url` chỉ có trong câu trả lời của lệnh tạo: lưu lại ngay.
- Header, body, mật khẩu Basic auth không bao giờ được trả lại; `settings` chỉ cho biết `header_names`, `body_set`, `basic_auth_set`.
- `international_critical: true`: chỉ điểm dò quốc tế lỗi cũng tính là down (mặc định `false`).
- Đích nội bộ hoặc không an toàn bị từ chối: 422 `validation_failed` với `details.reason: blocked_destination`. Một đích bị kiểm quá dày (tính cả khách khác) trả 422 `target_rate_exceeded`: chọn chu kỳ dài hơn.

`state` của monitor: `pending` (chưa có kết quả), `up`, `suspect`, `down`, `partial`, `down_international`, `paused` (monitor đã tắt, bị hệ thống dừng theo `disabled_reason`, hoặc đang trong `paused_until`).

## Kênh cảnh báo

[Tạo kênh](/docs/api/uptime-post-channels) với `kind` trong `limits.channels` của gói; kênh mới chờ xác minh (trừ email tới đúng địa chỉ đã xác minh của chủ tài khoản). Kênh chưa có `opted_in_at` không nhận tin.

| `kind` | `config` | Xác minh (`verification.method`) |
| --- | --- | --- |
| `email` | `address` | `email_code`: gửi mã trong thư tới [Xác minh kênh](/docs/api/uptime-post-channels-channel-verify) (`code`); mã hiệu lực 24 giờ |
| `telegram` | — | `telegram_link`: mở `telegram_url` (hoặc `telegram_group_url` cho nhóm) trong 10 phút |
| `discord`, `slack`, `webhook` | `url` (https) | `test_message`: gọi Xác minh kênh để gửi tin thử; gửi được thì kênh được xác minh |
| `zalo` | `consent: true`; `phone` để xác minh bằng OTP, bỏ `phone` để liên kết qua OA | `zalo_otp` hoặc `zalo_link` (gửi `zalo_link_code` vào OA ở `zalo_oa_url`, hiệu lực 10 phút) |

- Kênh webhook trả `webhook_secret` (`whsec_…`) chỉ một lần, trong câu trả lời của lệnh tạo: lưu lại để kiểm chữ ký tin gửi tới.
- Thư mã xác minh: tối đa 5 thư mỗi giờ mỗi tài khoản, 3 thư mỗi ngày mỗi địa chỉ; vượt trả 429 `rate_limited`. Mã sai trả 422 `token_invalid`.
- [Gửi tin thử](/docs/api/uptime-post-channels-channel-test) chỉ cho kênh đã xác minh và đang bật; còn lại trả 409 `conflict`.

## Danh sách và gửi lại an toàn

Danh sách (monitor, sự cố, kênh, kết quả kiểm từng lượt) phân trang bằng con trỏ: gửi `next_cursor` của trang trước vào `cursor`; `next_cursor` là `null` khi hết. `limit` mặc định 50, tối đa 100 (kết quả kiểm từng lượt: mặc định 100, tối đa 1000).

```json
{ "data": { "data": [], "next_cursor": null } }
```

[Tạo monitor](/docs/api/uptime-post-monitors) và [Tạo kênh](/docs/api/uptime-post-channels) nhận `idempotency_key` (8–128 ký tự `A-Za-z0-9._:-`). Mất kết nối giữa chừng thì gửi lại đúng body với cùng khoá: lệnh không tạo thêm. Cùng khoá mà body khác, hoặc lần gửi trước còn đang chạy, trả 409 `idempotency_conflict`. Không gửi khoá thì mỗi lần gọi là một lệnh mới: đọc lại danh sách trước khi thử lại.

## Câu trả lời

Thành công: `{"data": …}`, `data` là câu trả lời của Tino Uptime. HTTP 200, 201 khi tạo, 202 khi đã xếp tin thử, 204 khi xoá (không có nội dung). Thời điểm theo RFC 3339; ID là UUID.

## Lỗi

```json
{ "error": ["entitlement_exceeded"], "message": "Đã vượt hạn mức của gói.", "details": { "resource": "monitors" }, "request_id": "…" }
```

Rẽ nhánh theo `error[0]`, không theo `message` (câu tiếng Việt, có thể đổi). Với `validation_failed`, `details.field` chỉ trường sai, `details.reason` chỉ lý do khi có. Lỗi Tino trả trước khi chuyển tiếp (`service_not_found`, `invalid method`) chỉ có `error`. Khi báo lỗi cho Tino, gửi kèm `request_id`.

| HTTP | Mã | Nghĩa, cách xử lý |
| --- | --- | --- |
| 400 | `invalid_request` | ID sai dạng (không phải UUID), `idempotency_key` sai dạng, hoặc yêu cầu sai: lỗi lập trình phía ứng dụng |
| 401 | `unauthorized`, `invalid_token`, `token_expired` | token đăng nhập sai hoặc hết hạn: làm mới token |
| 403 | `account_suspended` | tài khoản Tino Uptime đang tạm ngưng: chặn thao tác ghi, `GET` vẫn dùng được |
| 403 | `entitlement_exceeded` | vượt hạn mức gói, `details.resource` chỉ hạn mức: nâng gói hoặc bớt monitor, kênh |
| 404 | `service_not_found`, `invalid method` | không phải dịch vụ Tino Uptime của tài khoản đang đăng nhập: về danh sách dịch vụ |
| 404 | `service_not_linked` | dịch vụ không còn là gói đang dùng: tìm lại dịch vụ ([Tìm dịch vụ Tino Uptime](#tim-dich-vu-tino-uptime)) |
| 404 | `account_not_found` | chưa có tài khoản Tino Uptime: liên hệ hỗ trợ Tino |
| 404 | `not_found` | monitor, sự cố, kênh không có hoặc đã xoá: tải lại danh sách |
| 409 | `conflict` | không làm được ở trạng thái hiện tại (vd gửi tin thử tới kênh chưa xác minh): tải lại rồi thử lại |
| 409 | `idempotency_conflict` | cùng `idempotency_key` mà body khác, hoặc lần trước còn đang chạy |
| 422 | `validation_failed` | dữ liệu sai: hiện lỗi dưới đúng trường theo `details.field` |
| 422 | `target_rate_exceeded` | đích bị kiểm quá dày (tính cả khách khác): chọn chu kỳ dài hơn |
| 422 | `token_invalid` | mã xác minh kênh email sai hoặc hết hạn |
| 429 | `rate_limited` | thao tác quá nhanh: thử lại sau |
| 502, 503 | `network`, `invalid_response`, `not_configured`, `unavailable` | kết nối giữa Tino và Tino Uptime gián đoạn: lỗi phía Tino, không phải lỗi token. Đừng đăng xuất, thử lại sau |