الخطوات الأولى

ترقيم الصفحات والتصفية

القوائم (/tvs و/files و/playlists) مقسّمة إلى صفحات. تأتي العناصر في data ومعلومات الصفحة في meta.

الاسم	النوع	الوصف
`page`	`integer`	رقم الصفحة، بدءًا من 1. القيمة الافتراضية: 1.
`per_page`	`integer`	عدد العناصر في كل صفحة، من 1 إلى 100. القيمة الافتراضية: 50.

حقول `meta`

page integer: الصفحة الحالية.
per_page integer: عدد العناصر في كل صفحة.
total integer: إجمالي العناصر التي عُثر عليها في جميع الصفحات.
total_pages integer: إجمالي عدد الصفحات.

لجلب كل شيء، ابدأ من page=1 وتقدّم حتى تصل إلى total_pages. الصفحة التي تلي الأخيرة تعود بقيمة data فارغة.

التصفية

يمكن الجمع بين عوامل التصفية بعضها مع بعض ومع ترقيم الصفحات. ويأخذ الحقل total في meta عوامل التصفية في الحسبان.

الاسم	النوع	الوصف
`organization`	`string`	uid مؤسسة ما، لجلب عناصرها فقط (راجع `/organizations`).
`q`	`string`	جزء من الاسم، حتى 100 حرف.
`type`	`string`	نوع الملف، مثل `image` أو `video`. في `/files` فقط.
`archived`	`integer`	`1` للملفات المؤرشفة فقط أو `0` للملفات غير المؤرشفة فقط. في `/files` فقط.

الترتيب

تأتي أجهزة التلفزيون وقوائم التشغيل بالترتيب الأبجدي، والملفات من الأحدث إلى الأقدم.

الطلبcURLPHPJavaScript

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();

الاستجابة200

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

معامل غير صالح400

GET /v1/tvs?per_page=500

{
  "error": {
    "code": "invalid_parameter",
    "message": "per_page must be a number between 1 and 100."
  }
}

ترقيم الصفحات والتصفية

حقول meta

التصفية

الترتيب

حقول `meta`