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

• Body luôn là JSON. Với Sửa 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.

Gateway /v1 chưa mở các route Tino Uptime: token ứng dụng (tinoat_) và token API cá nhân (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 lấy được bằng đăng nhập mã OTP:

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ụ (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ụ.
2. Gọi Tổng quan gói (GET /service/<id>/uptime):

Hạn mức gói

Hạn mức nằm ở subscription.limits của Tổng quan gói, số đang dùng ở Mức dùng. Đọc hạn mức từ API, đừng ghi cứng: số của từng gói có thể đổi.

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 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:

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

• 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ử 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).

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

Tạo monitor và Tạo kênh 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

{ "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.