📘 API đọc dữ liệu nhiệt độ

API cho phép phần mềm khác (Excel, Google Sheets, hệ thống quản lý kho, phần mềm của công ty…) đọc số đo, trạng thái và sự kiện của các tủ / kho mà tài khoản của bạn được xem trên web theo dõi. API chỉ đọc: không đổi được cài đặt, không gửi lệnh xuống máy, không có số điện thoại hay thông tin SIM.

Địa chỉ gốc: https://theodoi.canhbaosms.com

1. Tạo khóa API

Đăng nhập web theo dõi → Tài khoản → thẻ 🔑 Khóa API.
Đặt tên khóa (vd "Excel phòng kế toán"), chọn thời hạn rồi bấm ＋ Tạo khóa.
Chép khóa (dạng cbs_…) và cất ở nơi an toàn — khóa chỉ hiện một lần.
Lộ khóa hoặc không dùng nữa: bấm Thu hồi, phần mềm dùng khóa đó bị chặn ngay.

Gửi khóa trong tiêu đề Authorization: Bearer cbs_… (hoặc X-API-Key: cbs_…). Không gửi khóa trên đường dẫn (?key=) — bị từ chối.

2. Các địa chỉ đọc dữ liệu

Địa chỉ	Trả về
`GET /api/v1/devices`	Danh sách máy: `device` (idx máy), `name`, `sensors` [idx, name, kind, unit], `status`, `last_seen`
`GET /api/v1/sensors`	Mọi cảm biến: số đo mới nhất (`temp` °C, `hum` %), trạng thái, ngưỡng `thr_min`/`thr_max`, nguồn điện
`GET /api/v1/latest`	Số đo mới nhất của mọi cảm biến trong 1 lần gọi: `temp`, `hum`, `ts` (lúc đo), `age_s` (đã bao nhiêu giây), `fresh` (máy còn kết nối), `status`. Mỗi cảm biến ghi rõ thuộc máy nào: `device` (idx máy), `device_name`, `hub` (idx trạm chính nếu máy gửi qua trạm chính, không thì null), `kind_text`. Thêm `?by=device` → gom theo máy: `devices` [`device`, `device_name`, `status` (xấu nhất của máy), `sensors` […]]. Thêm `?at=2026-10-12T08:00` → số đo tại thời điểm đó (kết hợp được: `?by=device&at=…`)
`GET /api/v1/sensors/{idx}/latest`	Số đo mới nhất của 1 cảm biến. Thêm `?at=…` (ISO 8601 hoặc epoch) → lần đo gần nhất trước hoặc đúng thời điểm đó (tìm lùi tối đa 24 giờ), kèm `gap_s` = lần đo đó sớm hơn thời điểm hỏi bao nhiêu giây; không có số đo → `temp: null` + `note`
`GET /api/v1/sensors/{idx}/readings`	Số đo theo thời gian. Tham số: `from`, `to` (ISO 8601, vd `2026-10-01T00:00:00+07:00`, hoặc số giây epoch; không ghi múi giờ = giờ Việt Nam), `interval` = `raw` \| `5m` \| `1h` (mặc định, trung bình mỗi giờ) \| `1d`, `limit` (≤ 10 000), `offset`, `format=csv`. Khoảng tối đa 31 ngày với `raw`, 366 ngày với trung bình. Bỏ qua lần đọc lỗi đầu dò.
`GET /api/v1/events`	Sự kiện cảnh báo, mất / có điện, lỗi đầu dò, mất kết nối. Tham số: `from`, `to`, `idx`, `limit`, `offset`

Kết quả là JSON viết liền 1 dòng (cho phần mềm đọc). Muốn đọc bằng mắt: thêm ?pretty=1 (hoặc &pretty=1 nếu đã có tham số khác), vd /api/v1/latest?pretty=1. Trên Windows PowerShell, lệnh curl thực chất là Invoke-WebRequest và chỉ hiện chuỗi chữ — dùng curl.exe hoặc Invoke-RestMethod -Headers @{Authorization="Bearer cbs_…"} https://theodoi.canhbaosms.com/api/v1/latest (tự ra bảng).

Thời gian trả về theo 2 dạng: ts (UTC, ISO 8601, vd 2026-10-12T01:00:00Z) và local (giờ Việt Nam, 12/10/2026 08:00:00). status: normal bình thường, alert đang cảnh báo, out_of_range vượt ngưỡng, power_lost mất điện, sensor_error lỗi cảm biến, offline mất kết nối, inactive ngừng hoạt động. Trang dài: dùng next_offset làm offset lần sau.

3. Ví dụ

curl (dòng lệnh):

curl -H "Authorization: Bearer cbs_KHOA_CUA_BAN" "https://theodoi.canhbaosms.com/api/v1/latest?by=device&pretty=1"
curl -H "Authorization: Bearer cbs_KHOA_CUA_BAN" https://theodoi.canhbaosms.com/api/v1/latest
curl -H "Authorization: Bearer cbs_KHOA_CUA_BAN" "https://theodoi.canhbaosms.com/api/v1/latest?at=2026-10-12T08:00"
curl -H "Authorization: Bearer cbs_KHOA_CUA_BAN" https://theodoi.canhbaosms.com/api/v1/sensors
curl -H "Authorization: Bearer cbs_KHOA_CUA_BAN" "https://theodoi.canhbaosms.com/api/v1/sensors/360/readings?from=2026-10-01&to=2026-10-08&interval=1h"
curl -H "Authorization: Bearer cbs_KHOA_CUA_BAN" -o so_do.csv "https://theodoi.canhbaosms.com/api/v1/sensors/360/readings?interval=5m&format=csv"

Python:

import requests
H = {"Authorization": "Bearer cbs_KHOA_CUA_BAN"}
r = requests.get("https://theodoi.canhbaosms.com/api/v1/sensors", headers=H, timeout=20)
r.raise_for_status()
for s in r.json()["sensors"]:
    print(s["name"], s["temp"], "°C", s["status"])

Excel (Power Query): Dữ liệu → Lấy dữ liệu → Từ nguồn khác → Truy vấn trống → Trình soạn thảo nâng cao, dán:

let
    Nguon = Csv.Document(Web.Contents("https://theodoi.canhbaosms.com/api/v1/sensors/360/readings",
        [Query = [interval = "1h", format = "csv"],
         Headers = [Authorization = "Bearer cbs_KHOA_CUA_BAN"]]),
        [Delimiter = ",", Encoding = 65001]),
    TieuDe = Table.PromoteHeaders(Nguon)
in
    TieuDe

Khi Excel hỏi cách đăng nhập, chọn Ẩn danh (Anonymous) — khóa đã nằm trong tiêu đề. Bấm Làm mới để lấy số mới.

4. Giới hạn và lỗi

Mỗi khóa tối đa 60 yêu cầu / phút và 10.000 yêu cầu / ngày. Vượt: mã 429 kèm tiêu đề Retry-After (số giây chờ).
Khóa chỉ đọc được các tủ tài khoản đó được xem. Quản trị đổi quyền xem thì khóa đổi theo.
Lỗi trả JSON {"error": "…"}: 401 thiếu / sai / đã thu hồi / hết hạn khóa · 403 không có quyền xem cảm biến này · 404 không có cảm biến · 400 tham số sai · 429 quá nhiều yêu cầu.
Số đo được lưu 1 phút / lần (tùy cài đặt máy chủ); muốn số mới nhất thì đọc /latest, không cần gọi dày hơn 1 lần / phút. Máy gửi số đo về liên tục nên /latest chính là số tức thời (thường cũ dưới 1–2 phút — xem age_s); fresh: false = máy đang mất kết nối, số đó là số cuối cùng nhận được.