ربط نظامك بالويب هوك

إن كانت الحجوزات موجودة أصلاً في نظام تتحكم به — نظام إدارة وحدات، أو مدير قنوات، أو خلفية داخلية — فهذا أسرع المسارات، والوحيد اللحظي في الاتجاهين. أنت ترسل حدثاً موقّعاً؛ فيحتسبه سويتي على باقة المضيف أو محفظته، وينشئ التنظيف، ويرسل منظّفاً.

ما تحتاجه

• حساب مشغّل (/partner).
• شخص يستطيع إضافة ويب هوك صادر في نظامك.
• معرّفات وحداتك أنت، وربط كل واحد بمضيف ووحدة في سويتي.

الخطوة ١ — أنشئ نقطة الربط

التكاملات ← نقاط الربط ← إنشاء. تُعرض عليك قيمتان، مرة واحدة:

• رابط الاستقبال — https://suitiee.com/webhooks/receive/{partnerSlug}/{webhookId}
• مفتاح التوقيع

الخطوة ٢ — اربط وحداتك

سجّل سطراً لكل مضيف تحت العملاء ← عملاء الشريك، بمعرّفك أنت له، واربط معرّفات وحداتك بوحدات سويتي. يجب أن يؤدي unit_id الوارد إلى مضيف ووحدة، وإلا قُبل الحدث ثم فشل بذلك السبب على سطره.

الخطوة ٣ — وقّع الطلب

كل طلب يحمل HMAC-SHA256 على الجسم الخام، بمفتاح التوقيع:

X-Suitiee-Signature: sha256=<hex hmac_sha256(rawBody, secret)>

$body = json_encode($payload, JSON_UNESCAPED_UNICODE);
$signature = 'sha256=' . hash_hmac('sha256', $body, $webhookSecret);

const body = JSON.stringify(payload);
const signature = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');

وقّع البايتات نفسها التي ترسلها. إعادة التسلسل بعد التوقيع — ترتيب مفاتيح مختلف، أو مسافات مختلفة، أو ترميز يونيكود مختلف — تنتج توقيعاً لن يطابق.

يجب أن يحمل الجسم أيضاً timestamp بصيغة ISO 8601 في المستوى الأعلى، وأن يكون ضمن خمس دقائق من ساعتنا في أي من الاتجاهين. هذا ما يمنع إعادة تشغيل طلب مُلتقَط.

إن كنت ترسل من عناوين ثابتة، أضفها إلى قائمة السماح على نقطة الربط؛ ويُرفض عندها ما عداها.

الخطوة ٤ — أرسل الحدث

POST https://suitiee.com/webhooks/receive/{partnerSlug}/{webhookId}

{
  "event_id": "res_9f8c12",
  "event_type": "checkout",
  "timestamp": "2026-09-04T14:00:00Z",
  "unit_id": "APT-204",
  "checkout_datetime": "2026-09-04T11:00:00Z",
  "next_checkin_datetime": "2026-09-04T16:00:00Z",
  "guest_name": "سارة علي",
  "notes": "مغادرة متأخرة معتمدة؛ مناشف إضافية."
}

أرسل دائماً event_id ثابتاً. تُطوى التكرارات عليه، فإعادة الإرسال بعد انقطاع تنشئ تنظيفاً واحداً لا اثنين. وبدونه يُشتقّ معرّف من نوع الحدث ورقم الحجز، وإلا فمن بصمة الجسم.

الخطوة ٥ — اقرأ الجواب

200 {"status":"received"} تعني أن الحدث خُزّن ووُضع في الطابور. لا تعني أن التنظيف أُنشئ بعد — فذلك يحدث لاحقاً، وتظهر النتيجة على سطر الحدث تحت التكاملات ← أحداث الربط، وعبر GET /partner/webhooks/events.

كل ما يُكتشف بعد القبول لا يُفشل نداء HTTP. المحفظة الفارغة أو الوحدة غير المرتبطة نتائج تشغيلية لا أخطاء نقل. يُجاب النداء بـ received، ويقول سطر الحدث failed مع السبب. ولا يعود 4xx إلا لمشكلات التوقيع والطابع الزمني ونقطة الربط.

بيانات الضيف اختيارية وتبقى اختيارية

أرسلها على حدث الحجز، أو على حدث المغادرة، أو لا ترسلها أبداً. الحدث الذي يحذفها يترك ما لدينا كما هو بدل أن يمسحه؛ والحدث الذي يتضمّنها يحدّثه، وهكذا يصلنا بريد مصحّح.

بريد الضيف وجواله بيانات شخصية بموجب نظام حماية البيانات الشخصية. تُخزَّن على الحجز، وتُعرض للمشغّل والمضيف اللذين يملكانه، وتُبعَد عن كل عمود قائمة، ولا تُكتب في أي سطر سجل. أرسلها فقط إن كان أساسك النظامي لمشاركتها يسمح — وكل شيء آخر يعمل تماماً بدونها.

نداءات الرجوع إليك

اضبط رابط الرجوع ومفتاح الرجوع تحت الإعدادات، فيرسل سويتي إليك تحديثاً موقّعاً حين يُنشأ تنظيف أو تتغير حالته أو يكتمل، وكذلك لزيارات الصيانة.

X-Suitiee-Callback-Signature: sha256=<hmac_sha256(body, callbackSecret)>

أجب بـ 2xx. وما ليس 2xx أو ما ينقطع يُعاد ثلاث مرات — بعد ٣٠ ثانية ودقيقتين وعشر دقائق — ثم يُسجَّل فشلاً نهائياً.

حين يحدث خطأ