واجهة ربطٍ موثّقةٌ ومنشورة.

١. المصادقة

الدخول يُعيد توكن دخولٍ مؤقتاً (JWT من نوع Bearer). رقم منشأتك محمولٌ داخل هذا التوكن نفسه، ويُقرأ منه فقط — لا من جسم الطلب ولا من الرابط ولا من أي ترويسة.

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "owner@example.com",
  "password": "••••••••"
}

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOi...",
    "refresh_token": "eyJhbGciOi..."
  }
}

٢. قراءة صفحة من المركبات

التوكن يُرسَل في ترويسة Authorization على كل طلبٍ لاحق. القيم أدناه مُستبدَلةٌ بالكامل؛ البنية فقط هي المطابقة لما يعيده الحساب الحقيقي.

GET /api/v1/vehicles?page=1&limit=2
Authorization: Bearer <access_token>

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "tenant_id": 9001,
      "imei": "000000000000001",
      "name": "DEMO-001",
      "name_ar": "مثال-001",
      "saudi_plate": "0000  AAA",
      "vehicle_class": "van",
      "make": "Example",
      "model": "Model",
      "year": 2024,
      "fuel_type": "diesel"
    }
  ],
  "meta": { "total": 2, "page": 1, "limit": 2 }
}

٣. قراءة ترويسات حدود الاستخدام

نفسُ الردِّ أعلاه يحمل حالة عدّادك في اللحظة نفسها — بلا نداءٍ إضافي، وبلا رقمٍ نُعلنه هنا (السقف يُضبط على مستوى منشأتك، كما في القسم التالي).

— (على أي ردٍّ ناجح من القسم السابق)

X-RateLimit-Limit: <سقف منشأتك>
X-RateLimit-Remaining: <المتبقّي الآن>
X-RateLimit-Reset: <ختم زمني Unix>

# وعند التجاوز:
HTTP/1.1 429 Too Many Requests
Retry-After: <عدد الثواني>

٤. ما الذي يتحدّث معه العتاد

قدرات كل عائلة أجهزةٍ مُعلَنةٌ بالاسم — والحقيقة الكاملة معها: كل فعلٍ اليوم قيمته sendable: false، لأن البوابة ترفض ترميز أي أمرٍ لم يُختبَر فعلياً على عتادٍ حقيقي بعد. هذا موقفُ أمانٍ متعمَّد، لا نقاشه.

GET /api/v1/devices/capabilities
Authorization: Bearer <access_token>

{
  "success": true,
  "data": {
    "allow_unverified_commands": false,
    "families": [
      {
        "name": "family_1",
        "verbs": [
          { "verb": "get_info", "status": "documented", "sendable": false },
          { "verb": "immobilize", "status": "documented", "sendable": false }
        ]
      }
    ]
  }
}