التوثيق
واجهة برمجية لنفس المنصة اللي تستخدمها
لوحة التشغيل وبوابة النزيل والاستقبال الذاتي كلها تستخدم نفس الواجهة. هذي الصفحة تشرح المفاهيم الاساسية للمطورين.
تبي تربط نظامك بهوستليفو؟ تواصل معنا ونرتب الوصول لحسابك.
نظرة عامةقريبا
واجهة REST ترجع JSON. كل المسارات تبدا بـ /api/v1.
- النسخة في المسار. اي تغيير يكسر التوافق ياخذ /api/v2 ويعيش جنب النسخة الاولى
- التواريخ بصيغة ISO 8601 وتخزن بالتوقيت العالمي
- كل منشاة لها منطقة زمنية والاقامات تحسب بها
- لغة الرسائل حسب ترويسة Accept-Language بالعربي او الانجليزي
- وصف الواجهة بصيغة OpenAPI نرسله لشركاء التكامل
GET https://{your-domain}/api/v1/orgs/{orgId}/properties
Accept: application/json
Accept-Language: arنموذج المصادقةقريبا
كل نوع مستخدم له طريقة دخول منفصلة وصلاحيات منفصلة.
- جلسة الفريقمصمم
- لوحة التشغيل تستخدم جلسة على الخادم بكوكي محمي. الجلسة تنتهي وتلغى ومع حماية من الطلبات المزورة.
- رابط النزيلمصمم
- رمز خاص بحجز واحد بصلاحيات محدودة. منفصل تماما عن حسابات الفريق.
- مفاتيح الواجهة للمنشاتقريبا
- مفاتيح لكل حساب بصلاحيات محددة للربط مع انظمتك.
عزل الحساباتمصمم
كل حساب منشاة معزول عن غيره في كل طلب.
- معرف الحساب في المسار مثل /orgs/{orgId}
- الخادم يتحقق ان المستخدم عضو في الحساب قبل اي شي
- الحساب ما ياخذ من جسم الطلب ابدا
- قاعدة البيانات نفسها ترفض اي سجل من حساب ثاني
- طلب مورد من حساب ثاني يرجع غير موجود
المواردقريبا
هذي الموارد الاساسية في الواجهة البرمجية.
| المسار | الوصف |
|---|---|
| /orgs/{orgId}/properties | المنشات واعداداتها |
| /properties/{id}/rooms | الغرف وانواعها |
| /rooms/{id}/beds | الاسرة وحالاتها |
| /reservations | الحجوزات والاسرة المعينة |
| /guests | النزلاء وحالة بياناتهم |
| /payments | طلبات الدفع والتحقق والاسترداد |
| /tasks | مهام النظافة والصيانة |
| /access/credentials | صلاحيات الدخول وحالة اوامرها |
الطلبات والاخطاءقريبا
قواعد عامة لكل الطلبات اللي تغير بيانات.
- ترويسة Idempotency-Key تمنع تكرار العملية لو اعدت نفس الطلب
- تعارض الحجز يرجع 409 مع رمز خطا واضح
- كل رد خطا فيه رمز ورسالة ومعرف طلب للمتابعة
- حدود لعدد الطلبات وتجاوزها يرجع 429
POST /api/v1/orgs/{orgId}/reservations
Idempotency-Key: 5b1f0c1e-7a7e-4f2b-9d0e-1f6c2b9a4e11
Content-Type: application/json
{ "propertyId": "...", "bedId": "...", "checkIn": "2026-11-02", "checkOut": "2026-11-05" }HTTP/1.1 409 Conflict
{ "error": { "code": "bed_unavailable", "message": "...", "requestId": "..." } }تنبيهات الاحداثقريبا
النظام يسجل كل تغيير مهم كحدث. لاحقا تقدر تشترك وتستلم الاحداث على خادمك.
- كل حدث له معرف ثابت. استخدمه لتجاهل التكرار
- التوصيل مرة على الاقل. ممكن يوصلك نفس الحدث اكثر من مرة
- كل طلب موقع بسر خاص بالاشتراك
- اعادة محاولة مع تباعد اذا ما رد خادمك بنجاح
- عناوين الشبكات الداخلية ممنوعة كوجهة
امثلة احداث
- reservation.confirmed
- reservation.cancelled
- stay.checked_in
- stay.checked_out
- payment.verified
- task.completed
- access.credential.confirmed
POST https://your-server.example/hooks
X-Event-Id: evt_...
X-Signature: t=...,v1=...
Content-Type: application/json
{ "type": "reservation.confirmed", "occurredAt": "...", "data": { "reservationId": "..." } }الاجهزة والمزودينقريبا
الاقفال ومزودي الدفع يتربطون عبر موصلات داخل المنصة. ما تحتاج تكتبها انت.
- كل موصل يعلن قدرات الجهاز مثل الرمز المؤقت او الفتح عن بعد
- حالة الامر تمر بالانتظار ثم ارسل ثم استلم ثم مؤكد او فشل او غير معروف
- نزل التجربة يستخدم موصلات اختبار فقط
- حالة كل شركة في صفحة الاجهزة والتكاملات