Tham chiếu · TV

Liệt kê TV

GET /v1/tvs

Liệt kê các TV đã kích hoạt của những tổ chức mà người dùng được xem TV, theo thứ tự bảng chữ cái.

Phản hồi được phân trang: các mục nằm trong data và thông tin trang nằm trong meta. Phân trang và bộ lọc

Tham số

Tên	Loại	Mô tả
`organization`	`string`	uid của một tổ chức, để chỉ lấy các mục của tổ chức đó (xem `/organizations`).
`q`	`string`	Một phần của tên, tối đa 100 ký tự.
`page`	`integer`	Trang, bắt đầu từ 1. Mặc định: 1.
`per_page`	`integer`	Số mục mỗi trang, từ 1 đến 100. Mặc định: 50.

Các trường của mỗi mục

uid string: Mã định danh của TV, giống mã dùng trong bảng điều khiển.
name string: Tên TV.
description string: Mô tả TV (có thể trống).
organization object: Tổ chức của TV: uid và name.
playlist object | null: Danh sách phát của TV (uid và name), hoặc null nếu không có.
status string: online, alert hoặc offline, như giải thích bên dưới.
last_seen_at string | null: Lần liên lạc gần nhất giữa TV và nền tảng, hoặc null nếu TV chưa từng kết nối.
activated_at string | null: Thời điểm TV được kích hoạt.
app_version string: Phiên bản ứng dụng cài trên TV.
os string: Hệ điều hành của TV, ví dụ android.
device object: Hãng (brand) và mẫu (model) của thiết bị, nếu TV cung cấp.
timezone string | null: Múi giờ của TV, ví dụ America/Sao_Paulo, hoặc null.

Cách tính trạng thái

online liên lạc cách đây chưa đến 3 phút, đang phát
alert liên lạc cách đây từ 3 đến 9 phút, hoặc TV vẫn đang khởi động
offline không liên lạc từ 10 phút trở lên, hoặc chưa từng kết nối

Đây cũng là quy tắc dùng cho màu trạng thái trong bảng điều khiển.

Các lỗi có thể gặp

400 invalid_parameter Một tham số có giá trị không hợp lệ, ví dụ per_page vượt quá mức tối đa.
404 organization_not_found Giá trị organization được truyền không phải là tổ chức mà người dùng được xem loại mục này.
Lỗi về khóa và giới hạn yêu cầu áp dụng cho mọi endpoint. Xem tất cả lỗi

Yêu cầucURLPHPJavaScript

curl "https://api.on-cloud.live/v1/tvs?per_page=2" \
  -H "X-API-Key: $API_KEY"

<?php
$ch = curl_init('https://api.on-cloud.live/v1/tvs?per_page=2');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('API_KEY')],
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.on-cloud.live/v1/tvs?per_page=2', {
  headers: { 'X-API-Key': process.env.API_KEY }
});
const { data, meta } = await res.json();

Phản hồi200

{
  "data": [
    {
      "uid": "d3d9446802a44259755d38e6d163e820",
      "name": "Caixa 2",
      "description": "",
      "organization": {
        "uid": "1679091c5a880faf6fb5e6087eb1b2dc",
        "name": "Loja Shopping Norte"
      },
      "playlist": null,
      "status": "offline",
      "last_seen_at": "2026-11-01T18:04:51-03:00",
      "activated_at": "2025-03-12T09:41:05-03:00",
      "app_version": "3.12.83",
      "os": "android",
      "device": {
        "brand": "Philco",
        "model": "PTV32G70"
      },
      "timezone": "America/Sao_Paulo"
    },
    {
      "uid": "c98cb8f9cc62887d1f6cf5693df9219c",
      "name": "Recepção",
      "description": "TV da entrada",
      "organization": {
        "uid": "8f14e45fceea167a5a36dedd4bea2543",
        "name": "Loja Centro"
      },
      "playlist": {
        "uid": "e4da3b7fbbce2345d7772b0674a318d5",
        "name": "Lista principal"
      },
      "status": "online",
      "last_seen_at": "2026-11-03T14:32:10-03:00",
      "activated_at": "2025-03-12T09:41:05-03:00",
      "app_version": "3.12.84",
      "os": "android",
      "device": {
        "brand": "TCL",
        "model": "43P635"
      },
      "timezone": "America/Sao_Paulo"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total": 3,
    "total_pages": 2
  }
}