⚡ Flow Power — ربط أنظمة الفنادق

نظام الفندق يفعّل الكهرباء على جهاز الغرفة لمدة الحجز، ويمددها أو يوقفها. الجهاز نفسه يفصل الكهرباء عند انتهاء المدة حتى لو انقطع الإنترنت.

الدخول

الرابط والمفتاح من صفحة الإعدادات والربط في لوحة التحكم. أرسل المفتاح في كل طلب:

Authorization: Bearer fpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
Content-Type: application/json

الرابط الأساسي: https://power.roydigi.com/api/v1

المدة

إما duration: رقم + وحدة — min دقيقة، h ساعة، d يوم، w أسبوع، mo شهر (مثل 1h، 1d، 2d، 1w، 1mo)، أو ends_at: وقت الانتهاء بصيغة ISO 8601 (مثل 2026-11-02T12:00:00+03:00). الحد الأقصى 400 يوم.

تفعيل الكهرباء (حجز جديد)

POST https://power.roydigi.com/api/v1/activations
{
  "location": "204",            // رقم الغرفة كما في لوحة التحكم — أو "device": "FP-XXXXXXXX"
  "duration": "2d",             // أو "ends_at": "2026-11-02T12:00:00+03:00"
  "reference": "BK-10045",      // رقم الحجز في نظامك (اختياري، يمنع التكرار)
  "guest_name": "محمد"          // اختياري
}

الاستجابة 201 (أو 200 إن كان هناك تفعيل نشط بنفس reference على نفس الجهاز — إعادة الإرسال آمنة):

{
  "ok": true,
  "activation": {
    "id": 17, "device": "FP-7KQ2M9XA", "location": "204", "status": "active",
    "starts_at": "2026-10-29T21:00:00+00:00", "ends_at": "2026-10-31T21:00:00+00:00",
    "remaining_seconds": 172800, "reference": "BK-10045", "guest_name": "محمد",
    "guest_url": "https://power.roydigi.com/g/AbC…",   // صفحة للضيف تعرض الوقت المتبقي
    "source": "api", "ended_at": null
  },
  "device": { "serial": "FP-7KQ2M9XA", "online": true, "power": "on", "in_sync": false, ... },
  "ble_token": "v1.FP-7KQ2M9XA.5.1793480400.1793307600.9f2c…"   // للتطبيق عبر البلوتوث إن كان الجهاز بلا إنترنت
}

أي تفعيل نشط سابق على نفس الجهاز يُستبدل (replaced).

تمديد

POST https://power.roydigi.com/api/v1/activations/{id}/extend
{ "duration": "1d" }        // تُضاف إلى وقت الانتهاء الحالي — أو "ends_at" لوقت محدد

إيقاف مبكر (خروج الضيف)

POST https://power.roydigi.com/api/v1/activations/{id}/stop

تشغيل/إطفاء داخل المدة

لا يغيّر المدة نفسها — مثل مفتاح الغرفة. الضيف يستطيع ذلك أيضًا من رابطه أو من التطبيق (عبر الإنترنت أو البلوتوث).

POST https://power.roydigi.com/api/v1/devices/{serial}/switch
{ "on": false }

تفعيل جديد على الجهاز يعيد المفتاح «مشغّلًا». التشغيل بلا مدة سارية يُرفض بـ 409.

الضيف

guest_url في كل تفعيل: صفحة للضيف بلا تطبيق (الوقت المتبقي + تشغيل/إطفاء)، وفيها زر يفتح تطبيق Flow Power (flowpower://guest/{code}) للتحكم عبر البلوتوث حين لا يوجد إنترنت. التفعيلات بنفس reference تظهر للضيف معًا (مثلًا كهرباء الغرفة والمكيّف). الرابط يتوقف تلقائيًا عند انتهاء المدة أو بدء تفعيل لضيف آخر على الجهاز.

الاستعلام

GET https://power.roydigi.com/api/v1/activations/{id}
GET https://power.roydigi.com/api/v1/activations?reference=BK-10045
GET https://power.roydigi.com/api/v1/activations?status=active
GET https://power.roydigi.com/api/v1/devices
GET https://power.roydigi.com/api/v1/devices/{serial}

حالات التفعيل

active نشط · ended انتهت المدة · stopped أوقف مبكرًا · replaced استُبدل بتفعيل أحدث.

Webhooks

عند ضبط رابط الـ Webhook في الإعدادات نرسل POST بصيغة JSON لكل حدث، ونعيد المحاولة حتى 5 مرات إن لم يرد نظامك بـ 2xx.

X-FlowPower-Event: activation.ended
X-FlowPower-Signature: sha256=<HMAC-SHA256(body, webhook_secret)>

{
  "id": "6f1c…", "event": "activation.ended", "created_at": "2026-10-31T21:00:30+00:00",
  "data": { "activation": { ... } }       // أو "device": { ... } لأحداث الجهاز
}

الأحداث: activation.started، activation.extended، activation.stopped، activation.ended، device.online، device.offline.

التحقق من التوقيع (PHP):

$expected = 'sha256=' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_FLOWPOWER_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

الأخطاء

مثال cURL

curl -X POST https://power.roydigi.com/api/v1/activations \
  -H "Authorization: Bearer fpk_..." -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"location":"204","duration":"1d","reference":"BK-10045"}'