واجهة الشركاء البرمجية

الواجهة REST لنظام يريد أكثر من الإعلان عن المغادرات: تسجيل المضيفين الذين يديرهم، وإنشاء تنظيف عند الطلب، واشتراك مضيف في باقة، وقراءة ما حدث.

هي إلى جانب الويب هوك لا بديلاً عنه. للتنظيف التلقائي بعد المغادرة الويب هوك هو الأداة الصحيحة؛ والواجهة هي ما تستدعيه حين يكون برنامجك أنت هو من يقرّر.

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

المرجع الكامل، بكل حقل وبمُنشئ طلبات، في التكاملات ← توثيق API داخل لوحة المشغّل.

ما تحتاجه

• حساب مشغّل (/partner).
• مفتاح API: الإعدادات ← مفاتيح API ← إنشاء. يُعرض مرة واحدة. سمِّه باسم النظام الذي سيستخدمه، حتى تستطيع إبطال واحد دون كسر الباقي.

الخطوة ١ — المصادقة

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

٦٠ طلباً في الدقيقة لكل مفتاح. فوق ذلك تحصل على 429؛ تراجع وأعد المحاولة.

الخطوة ٢ — اعرف الغلاف

شكل واحد لكل شيء، حتى يُكتب العميل مرة واحدة.

{ "data": { }, "message": "اختياري" }

والقائمة تضيف الترقيم:

{ "data": [ ], "meta": { "current_page": 1, "last_page": 5, "per_page": 15, "total": 73 } }

والخطأ ليس نصاً مجرداً أبداً:

{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "…", "details": { } } }

الرموز التي يجب أن تعالجها بالاسم لا بالنص: UNAUTHENTICATED وFORBIDDEN وNOT_FOUND وVALIDATION_ERROR وINSUFFICIENT_BALANCE وPACKAGE_EXHAUSTED وPACKAGE_EXPIRED وSLOT_UNAVAILABLE.

المبالغ بالريال بمنزلتين عشريتين؛ والتواريخ ISO 8601 بتوقيت UTC؛ والموارد العامة تُعرَّف بـ UUID، ومضيفوك بـ external_id الخاص بك.

الخطوة ٣ — سجّل المضيفين

POST /partner/clients
{ "external_id": "OWNER-118", "client_phone": "+9665…", "client_name_en": "…" }

external_id ملكك. كل نداء لاحق يسمّي المضيف به، فاستخدم ما يسمّيه به نظامك أصلاً ولا تغيّره أبداً.

وGET /partner/clients وGET /partner/clients/{external_id} و PUT /partner/clients/{external_id} تفعل البقية.

الخطوة ٤ — مسار نظام إدارة الوحدات: أعلن ثم غادِر

هذان الاستدعاءان يجعلان التنظيف تلقائياً بلا ويب هوك.

POST /partner/reservations
{
  "external_reservation_id": "BK-99120",
  "client_external_id": "OWNER-118",
  "external_unit_id": "APT-204",
  "checkin_datetime": "2026-09-06T15:00:00Z",
  "expected_checkout_datetime": "2026-09-09T11:00:00Z",
  "next_checkin_datetime": "2026-09-09T16:00:00Z"
}

يصبح الحجز متوقّعاً: لا احتساب ولا إرسال. أرسل next_checkin_datetime فور معرفتك به لتنتهي نافذة التنظيف قبل ذلك الوصول بدل الافتراضي وهو خمس ساعات.

POST /partner/reservations/{external_reservation_id}/checkout

تلك هي اللحظة التي يُحتسب فيها المبلغ ويُنشأ التنظيف ويُرسل منظّف.

وGET /partner/reservations وGET /partner/reservations/{id} لقراءتها.

الخطوة ٥ — مسار المجمّعات: أنشئ العمل بنفسك

المبنى أو المجمّع الذي لا يبيع ليالي ليس لديه مغادرات يتفاعل معها. فهو يحجز العمل مباشرة:

POST /partner/requests
Idempotency-Key: 3f1c-…
{
  "client_external_id": "OWNER-118",
  "service_id": "…",
  "requested_window_start": "2026-09-06T08:00:00Z",
  "requested_window_end": "2026-09-06T12:00:00Z"
}

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

وGET /partner/requests تسردها، وGET /partner/requests/{uuid} تقرأ واحداً، و POST /partner/requests/{uuid}/cancel يلغي واحداً وفق قواعد الإلغاء الخاصة بك.

الخطوة ٦ — أرسل Idempotency-Key دائماً

يقبل POST /partner/requests ترويسة Idempotency-Key. أرسل واحدة جديدة لكل نيّة، وكرّرها في كل إعادة محاولة للنيّة نفسها.

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

بقية السطح

ما لا تفعله الواجهة بعد

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

حين يحدث خطأ