📖 Tài Liệu Hướng Dẫn RESTful API

Hướng dẫn kết nối và truy vấn trạng thái thiết bị mạng LAN từ các client bên ngoài.

🔐 Xác Thực Bằng Mã Token Bí Mật (Authentication)

Mọi truy vấn API đến server WCM đều phải đính kèm **Mã Token Bí Mật (API Secret Token)**. Bạn có thể gửi mã Token bằng 1 trong 3 cách sau:

Phương thức gửi Cú pháp mẫu Ghi chú
Header (Khuyên dùng) X-API-Key: <B33_API_TOKEN> Đặt vào HTTP Request Header X-API-Key
Bearer Token Authorization: Bearer <B33_API_TOKEN> Đặt vào HTTP Request Header Authorization
Query Parameter ?token=<B33_API_TOKEN> Đính kèm trực tiếp vào đường dẫn URL truy vấn
Tham số Mã Token truyền vào: <B33_API_TOKEN>
GET

/api/device/status

Yêu cầu Token

Truy vấn thông tin trạng thái Online/Offline, thời gian duy trì liên tục (sau khi lọc nhiễu 6 phút), IP, MAC và Nhà sản xuất cho 1 thiết bị cụ thể.

Tham số truy vấn:

Ví dụ cURL:

cURL Example
curl -s -H "X-API-Key: <B33_API_TOKEN>" "https://wcm.lotus1104.synology.me/api/device/status?query=172.16.20.1"

Response JSON mẫu:

{ "query": "172.16.20.1", "found": true, "device": { "name": "TP-Link ER605 Router", "mac": "5C:A6:E6:12:34:56", "ip": "172.16.20.1", "manufacturer": "TP-Link Corporation", "status": "online", "status_since": "2026-07-28T01:05:05Z", "duration_seconds": 49053, "duration_formatted": "13 giờ 37 phút 33 giây", "last_seen": "2026-07-28T14:08:53Z", "noise_filter_minutes": 6, "tracked": true, "is_visible": true, "detect": { "level": 2, "level_source": "type", "level_name": "Mức 2 — ICMP + Cổng dịch vụ", "device_type": "pc_windows", "device_label": "Máy tính Windows", "detect_ports": "3389,445,135", "last_detect_method": "tcp:3389", "last_detect_label": "Cổng TCP 3389" } } }

Khối detect cho biết mức nhận diện đang áp dụng cho thiết bị (1–5), mức đó đến từ đâu (manual = chọn tay · type = mặc định theo loại thiết bị · global = mặc định hệ thống) và bằng chứng nào đã kết luận Online ở lần kiểm tra gần nhất. Nếu last_detect_method = "arp" nghĩa là thiết bị chỉ còn dấu vết trong bảng ARP router (card mạng ngủ vẫn trả lời) chứ không thực sự phản hồi — hãy hạ mức của thiết bị xuống Mức 2 ở trang Cấu hình.

POST

/api/device/status/bulk

Yêu cầu Token

Truy vấn trạng thái và thời gian duy trì hàng loạt cho danh sách nhiều thiết bị cùng lúc.

Request Body JSON mẫu:

{ "queries": ["172.16.20.28", "172.16.20.21", "WP2_SocketPlug", "38:18:68:FB:9F:0A"] }

Ví dụ Python:

import requests url = "https://wcm.lotus1104.synology.me/api/device/status/bulk" headers = {"X-API-Key": "<B33_API_TOKEN>"} payload = {"queries": ["172.16.20.28", "WP2_SocketPlug"]} response = requests.post(url, json=payload, headers=headers) print(response.json())
GET

/api/devices/online

Yêu cầu Token

Lấy danh sách tất cả các thiết bị đang Online trong toàn mạng LAN kèm thời gian hoạt động liên tục của từng thiết bị.

Ví dụ cURL:

cURL Example
curl -s "https://wcm.lotus1104.synology.me/api/devices/online?token=<B33_API_TOKEN>"
GET

/api/tuya/meter

Yêu cầu Token

Truy vấn chỉ số điện tức thì từ Ổ cắm thông minh Tuya (Điện áp Volt, Công suất tiêu thụ Watt, Dòng điện mA, Tổng kWh tiêu thụ).

Cách sử dụng theo trường hợp:

📍 Trường hợp 1: Thiết bị NỘI MẠNG LAN (Dùng ip)

Dành cho các thiết bị nằm cùng mạng LAN nội bộ (vd: 172.16.20.25).

Nội mạng LAN
curl -s "https://wcm.lotus1104.synology.me/api/tuya/meter?ip=172.16.20.25" -H "X-API-Key: <B33_API_TOKEN>"
🌐 Trường hợp 2: Thiết bị KHÁC MẠNG / Remote (Dùng device_id)

Dành cho thiết bị ở dải LAN khác (IPSec VPN, 4G, địa điểm khác). Chỉ cần truyền device_id định danh Tuya toàn cầu.

Khác mạng / Remote
curl -s "https://wcm.lotus1104.synology.me/api/tuya/meter?device_id=a3c2be1e64b42e53e5i3zh" -H "X-API-Key: <B33_API_TOKEN>"
POST

/api/tuya/power

Yêu cầu Token

Điều khiển Bật / Tắt nguồn nguồn điện trực tiếp cho Ổ cắm thông minh Tuya (Hỗ trợ cả Nội Mạng LAN & Khác Mạng).

* Ghi chú: state: true là Bật nguồn (ON), state: false là Tắt nguồn (OFF).

Cách sử dụng theo trường hợp:

📍 Trường hợp 1: Điều khiển NỘI MẠNG LAN (Dùng ip)

Truyền IP của thiết bị trong mạng LAN (vd: 172.16.20.25).

Nội mạng LAN
curl -X POST "https://wcm.lotus1104.synology.me/api/tuya/power" \ -H "X-API-Key: <B33_API_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"ip": "172.16.20.25", "state": true}'
🌐 Trường hợp 2: Điều khiển KHÁC MẠNG / Remote toàn cầu (Dùng device_id)

Truyền device_id định danh của thiết bị. Bật/tắt tức thì ở bất kỳ nơi đâu trên thế giới.

Khác mạng / Remote
curl -X POST "https://wcm.lotus1104.synology.me/api/tuya/power" \ -H "X-API-Key: <B33_API_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"device_id": "a3c2be1e64b42e53e5i3zh", "state": true}'
⚡ Trường hợp 3: Điều khiển Ổ CẮM NỐI DÀI NHIỀU CỔNG (4 Ổ AC + 1 Cổng USB)

Truyền thêm tham số switch (từ 1 đến 4 cho ổ điện AC, hoặc 5 / "USB" cho cổng sạc USB).

  • Bật/tắt Ổ điện số 1, 2, 3, 4: "switch": 1 đến "switch": 4
  • Bật/tắt Cổng sạc USB: "switch_code": "USB" (hoặc "switch": 5)
• Ví dụ BẬT riêng Ổ điện số 2:
Ổ điện AC số 2
curl -X POST "https://wcm.lotus1104.synology.me/api/tuya/power" \ -H "X-API-Key: <B33_API_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"device_id": "a323811bcef7982aa7jmza", "switch": 2, "state": true}'
• Ví dụ BẬT riêng Cổng sạc USB:
Cổng sạc USB
curl -X POST "https://wcm.lotus1104.synology.me/api/tuya/power" \ -H "X-API-Key: <B33_API_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"device_id": "a323811bcef7982aa7jmza", "switch_code": "USB", "state": true}'
GET

/api/tuya/devices

Yêu cầu Token

Liệt kê danh sách tất cả các thiết bị Tuya thông minh có trong tài khoản Cloud Tuya (để tra cứu mã device_id).

Ví dụ cURL:

Danh sách thiết bị
curl -s "https://wcm.lotus1104.synology.me/api/tuya/devices" -H "X-API-Key: <B33_API_TOKEN>"