تخطَّ إلى المحتوى

أضف مدير القناة الخاص بك

يرشد هذا الدليل مطوري مديري القنوات وأنظمة إدارة الممتلكات خلال العملية الكاملة للتكامل مع Wink — من إنشاء حساباتكم إلى تعيين المخزون وتشغيل أول اختبار شامل.

واجهة برمجة تطبيقات مدير القناة (التكاملات) متاحة في بيئتين. استخدم بيئة الاختبار لجميع التطوير والشهادات؛ وانتقل إلى الإنتاج فقط عند الإطلاق.

البيئةعنوان URL الأساسي
الإنتاجhttps://integrations.wink.travel
الاختبارhttps://staging-integrations.wink.travel

تتبع واجهة برمجة تطبيقات مدير القناة معايير بروتوكول OTA (SOAP/XML) لضمان التوافق مع أنظمة الضيافة الحالية. ابدأ بمراجعة توثيق نقاط النهاية الخاصة بالشريك:

واجهة برمجة تطبيقات مدير القناة — نقاط نهاية الشريك

  1. إنشاء حساب مستخدم في Wink

    سجّل في staging-app.wink.travel. جميع الخطوات أدناه تستخدم بيئة الاختبار — ستكرر العملية كاملة في الإنتاج قبل الإطلاق.

  2. إنشاء حساب تابع / مدير قناة

    تحت حساب المستخدم الجديد، أنشئ حسابًا واختر نوع الحساب تابع / مدير قناة. هذا هو الحساب الذي ستستخدمه المصادقة في التكامل.

  3. تسجيل تطبيق وإنشاء أول رمز وصول

    أنشئ تطبيقًا واربطه بحساب مدير القناة من الخطوة 2. اختر نوع العميل MACHINE_2_MACHINE — هذا تكامل خادم إلى خادم بدون إعادة توجيه للمستخدم النهائي. انسخ معرف العميل والمفتاح السري فورًا؛ المفتاح السري يظهر مرة واحدة فقط ولا يمكن استرجاعه لاحقًا.

    التطبيق هو الذي يصدر رمز الحامل الذي تحمله كل مكالمة في هذا الدليل كـ Authorization: Bearer <access_token>. استبدل بيانات اعتمادك برمز باستخدام منحة client_credentials عبر https://staging-iam.wink.travel/oauth2/token، مع طلب صلاحيات integrations.read integrations.write. قم بذلك قبل المتابعة — لا يمكنك البحث عن معرفات الحساب أو الوصول إلى أي نقطة نهاية لمدير القناة بدون رمز. راجع المصادقة للتدفق الكامل، المضيف الإنتاجي، وكامل قائمة الصلاحيات.

  4. إنشاء حساب فندق

    تحت نفس المستخدم، أنشئ حسابًا ثانيًا واختر نوع الحساب فندق. هذا يمنحك منشأة يمكنك استخدامها للاختبار دون الحاجة لفندق حقيقي.

  5. تأكيد الموافقة على كلا الحسابين

    لا يمكن استخدام أي من الحسابين حتى تتم الموافقة عليه: حساب مدير القناة غير الموافق عليه لا يظهر في قائمة مديري القنوات لأي فندق، والفندق غير الموافق عليه لا يتم إرجاعه بواسطة API.

    • الاختبار — الموافقة تلقائية. كلا الحسابين قابلان للاستخدام فور إنشائهما، ولا حاجة لطلب شيء.
    • الإنتاج — الموافقة يدوية. أرسل إلى جهة اتصال تكاملات Wink أسماء كلا الحسابين والمستخدم الذي ينتميان إليه، ثم انتظر التأكيد قبل المتابعة.
  6. ربط الحسابين

    سجّل الدخول إلى حساب الفندق وانتقل إلى القنوات → مدير القناة. اختر حساب مدير القناة الخاص بك من القائمة — هذا يربط المنشأة بتكاملتك. إذا لم يكن حسابك في القائمة، فهو لم يُوافق عليه بعد؛ راجع الخطوة 5.

  7. إنشاء نوع غرفة وخطة أسعار أساسية

    داخل حساب الفندق، أنشئ على الأقل نوع غرفة واحد وخطة أسعار واحدة. هذه مطلوبة قبل أن تتمكن من دفع الأسعار والتوافر أو سحب الحجوزات.

  8. التعيين والاختبار

    في نظامك الخاص، عين معرفات نوع الغرفة وخطة الأسعار التي يعيدها API. ادفع تحديث سعر وتحديث توافر، ثم قم بحجز اختبار وتحقق من أن نقطة نهاية استرجاع الحجز تعيده بشكل صحيح.

العثور على معرفات حسابك

Section titled “العثور على معرفات حسابك”

كل مسار في واجهة برمجة تطبيقات مدير القناة مرتبط بحسابك الخاص:

/api/managing-entity/{managingEntityIdentifier}/channel-manager/...

{managingEntityIdentifier} هو معرف الحساب (UUID) الخاص بـ حساب مدير القناة الخاص بك — وليس حساب الفندق. استرجعه مع معرف وحالة كل حساب آخر يملكه المستخدم الخاص بك من خلال منصة API:

نافذة طرفيّة
curl -s -X GET \
"https://staging-api.wink.travel/api/managing-entity/list" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

الاستجابة هي مصفوفة من الحسابات التي تملكها:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "مدير القناة الخاص بك",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "منشأتك الاختبارية",
"urlName": "your-test-property",
"status": "ACTIVE"
}
]
  • id الخاص بمدير القناة هو {managingEntityIdentifier}.
  • id الخاص بالفندق هو {propertyIdentifier}.
  • status هو المكان الذي تؤكد فيه أن كل حساب تمت الموافقة عليه — مفيد جدًا في الإنتاج حيث الموافقة يدوية. يجب أن يقرأ الفندق ACTIVE قبل أن يكون قابلاً للحجز أو مرئيًا لـ واجهة برمجة تطبيقات مدير القناة. يستمر حساب مدير القناة في القراءة PENDING_APPROVAL حتى تجتاز الشهادة؛ وهذا متوقع ولا يعيق التطوير.

الشهادة هي الطريقة التي تثبت بها — وتؤكد Wink — أن تكاملك يعين المخزون بشكل صحيح، ويدفع الأسعار والتوافر، ويتلقى الحجوزات بشكل شامل. تم تصميمها لتكون خدمة ذاتية: أنت تدير كل خطوة من نظامك الخاص، وترسل حزمة أدلة واحدة في النهاية. تراجع Wink الحزمة وعند النجاح، ترفع حالة حساب التابع / مدير القناة الخاص بك من PENDING_APPROVAL إلى ACTIVE.

تتم الشهادة بالكامل في بيئة الاختبار (https://staging-integrations.wink.travel). لا شيء في هذا القسم يمس الإنتاج.

  1. المصادقة. يمكن لعميل OAuth2 الخاص بك الحصول على رمز وصول واستدعاء نقطة النهاية /ping بنجاح ضد حساب التابع / مدير القناة الخاص بك.

  2. تعيين المخزون. يمكنك سرد الفندق (أو الفنادق) المرتبطة بحسابك، واسترجاع السعر الرئيسي (نوع الغرفة × خطة السعر) الذي قمت بتكوينه، وتحديد masterRateIdentifier الذي سيستهدفه نظامك بشكل صحيح.

  3. دفع السعر والتوافر. يمكنك تحديث جميع أيام الأسبوع السبعة لشهر الشهادة بشكل مستقل — مع تركيبات مختلفة من المبلغ، والكمية، وعلامات الإغلاق عند الوصول / المغادرة، والحد الأدنى / الأقصى لطول الإقامة في كل يوم — وقراءة القيم الدقيقة مرة أخرى من Wink.

  4. سحب الحجز. يمكنك استرجاع حجز حقيقي في بيئة الاختبار تم إجراؤه ضد منشأتك الاختبارية، عرضه في واجهة نظام إدارة الممتلكات / مدير القناة الخاص بك مع تفاصيل الغرفة، الضيف، والإجمالي بشكل صحيح، ثم عكس الإلغاء بمجرد أن تعلن Wink أن الحجز ملغى.

قبل بدء الشهادة، أكمل الخطوات 1–7 من خطوات التكامل بحيث يكون لديك:

  • مستخدم Wink في بيئة الاختبار مع حساب تابع / مدير قناة وحساب فندق مرتبط به (القنوات → مدير القناة). حسابات الاختبار تتم الموافقة عليها تلقائيًا.
  • على الأقل نوع غرفة واحد وخطة أسعار واحدة تم إنشاؤها داخل حساب الفندق. انشر الفندق ليكون قابلاً للحجز على https://staging-book.wink.travel/hotel/<your-slug>.
  • تطبيق مسجل تحت حساب التابع / مدير القناة الخاص بك مع معرف العميل، المفتاح السري، وصلاحيات integrations.read integrations.write (راجع المصادقة).
  • managingEntityIdentifier الخاص بحساب التابع / مدير القناة و propertyIdentifier الخاص بحساب الفندق (كلاهما UUID — راجع العثور على معرفات حسابك).

اتفاقيات الطلب الشائعة

Section titled “اتفاقيات الطلب الشائعة”

كل طلب في هذا القسم يستخدم هذه الرؤوس:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> يأتي من منحة client_credentials عبر https://staging-iam.wink.travel/oauth2/token — راجع المصادقة.
  • رأس Wink-Version مطلوب؛ إغفاله لن يوجه إلى واجهة برمجة التطبيقات JSON v2.
  • Content-Type: application/json يضاف في طلبات PUT التي تحمل جسمًا.

في الأمثلة أدناه، تمثل العناصر النائبة القيم التي جمعتها في المتطلبات المسبقة:

العنصر النائبالمعنى
{managingEntityIdentifier}معرف حساب التابع / مدير القناة الخاص بك (UUID) — راجع العثور على معرفات حسابك.
{propertyIdentifier}معرف حساب الفندق (المنشأة) المرتبط بحساب مدير القناة.
{masterRateIdentifier}السعر الرئيسي (تركيبة نوع الغرفة × خطة السعر) الذي ستعتمد عليه في الشهادة.
{bookingIdentifier}معرف الحجز في بيئة الاختبار الذي أعادته قائمة الحجوزات.

الخطوة أ — اختبار الاتصال (Ping)

Section titled “الخطوة أ — اختبار الاتصال (Ping)”

أكد أن بيانات اعتمادك تشير إلى حساب التابع / مدير القناة الذي تتوقعه.

نافذة طرفيّة
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/ping" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

الاستجابة المتوقعة:

{
"apiVersion": "2.0",
"name": "اسم حساب مدير القناة الخاص بك",
"status": "PENDING_APPROVAL"
}

استجابة 200 مع اسم مطابق هي إشارة إلى أن المصادقة وحل الحساب صحيحان. ستقرأ status القيمة PENDING_APPROVAL حتى تصادق Wink عليك.

استرجع قائمة الفنادق المرتبطة بحسابك مع الترقيم وتأكد من وجود منشأتك الاختبارية.

نافذة طرفيّة
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/list?page=0&size=25" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

الاستجابة هي صفحة Spring من إدخالات ChannelManagerProperty. حدد الإدخال الذي يطابق identifier الخاص بـ {propertyIdentifier} وسجل currencyCode الخاص به — ستحتاجه لتفسير تحديثات الأسعار في الخطوة د.

الخطوة ج — جلب الأسعار الرئيسية

Section titled “الخطوة ج — جلب الأسعار الرئيسية”

استرجع المنشأة مع كل سعر رئيسي (تركيبة نوع الغرفة × خطة السعر) تنشره. اختر السعر الذي تنوي الشهادة ضده وسجل identifier الخاص به كـ {masterRateIdentifier}.

نافذة طرفيّة
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

مغلف الاستجابة هو PropertyWithRoomRateList: كتلة property بالإضافة إلى مصفوفة rooms من إدخالات PropertyRoomRate. كل إدخال يعرض نوع الغرفة، خطة السعر، حدود الإشغال، السعر الأساسي، ومعدلات التعديل التي ستحافظ عليها عند دفع الأسعار اليومية.

الخطوة د — تحميل أسبوع الشهادة

Section titled “الخطوة د — تحميل أسبوع الشهادة”

حمّل تقويم أسعار لمدة سبعة أيام يغطي أول سبعة أيام تقويمية من الشهر التالي للشهر الذي تبدأ فيه الشهادة. على سبيل المثال، إذا بدأت الشهادة في 21 أغسطس، استهدف من 1 سبتمبر إلى 7 سبتمبر.

سترسل سبع مكالمات PUT منفصلة — واحدة لكل يوم — حيث startDate == endDate. كل يوم يحمل تركيبة مختلفة عمدًا من المبلغ، والكمية، وعلامات الإغلاق عند الوصول / المغادرة، وحدود الحد الأدنى / الأقصى لطول الإقامة بحيث يتم اختبار كل حقل قابل للكتابة مرة واحدة على الأقل. القيم بالعملة الخاصة بالمنشأة (المسجلة في الخطوة ب)؛ إذا حذفت currencyCode سيتم تعيينها بشكل صحيح افتراضيًا.

اليومالمبلغالكميةمغلق عند الوصولمغلق عند المغادرةالحد الأدنى للإقامةالحد الأقصى للإقامةما يثبته
1100.005falsefalse130يوم الأساس.
2125.004falsefalse114تغيير المبلغ + الكمية + maxLengthOfStay.
3150.003truefalse130تبديل closedOnArrival.
4175.002falsetrue27تبديل closedOnDeparture + نافذة إقامة أكثر تقييدًا.
5200.000falsefalse130كمية نفدت.
6225.005falsefalse35نافذة إقامة مقيدة.
7250.001falsefalse130توافر الغرفة الأخيرة.

جسم الطلب لليوم 1 يبدو هكذا. كرر مع تعديل startDate / endDate / القيم حسب الصف، للأيام 2 إلى 7.

نافذة طرفيّة
curl -s -X PUT \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"amount": 100.00,
"master": true,
"closedOnArrival": false,
"closedOnDeparture": false,
"quantity": 5,
"minLengthOfStay": 1,
"maxLengthOfStay": 30
}'

كل PUT يرد بـ 200 مع مصفوفة من إدخالات PropertyRate المحدثة للنطاق الذي أرسلته (إدخال واحد عندما startDate == endDate). احتفظ بهذه الاستجابة — ستكون جزءًا من أدلتك.

الخطوة هـ — قراءة أسبوع الشهادة

Section titled “الخطوة هـ — قراءة أسبوع الشهادة”

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

نافذة طرفيّة
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}?startDate=2026-09-01&endDate=2026-09-07" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

الاستجابة هي PropertyRoomRateWithRateList. يجب أن تحتوي مصفوفة rates على سبعة إدخالات، واحد لكل يوم، كل منها يحتوي على amount، quantity، closedOnArrival، closedOnDeparture، minLengthOfStay، وmaxLengthOfStay التي حمّلتها. أي اختلاف في أي حقل يعني أن PUT المقابل في الخطوة د لم يُطبق كما هو متوقع — أصلح ذلك وأعد التحقق قبل المتابعة.

الخطوة و — إجراء حجز اختبار

Section titled “الخطوة و — إجراء حجز اختبار”

افتح الرابط التالي في متصفح، مع استبدال <your-slug> بالمعرف الخاص بحساب الفندق الذي نشرته في المتطلبات المسبقة:

https://staging-book.wink.travel/hotel/<your-slug>

اختر تاريخ وصول ومغادرة يقعان بالكامل ضمن أسبوع الشهادة، اختر تركيبة نوع الغرفة + خطة السعر التي شهدت عليها، وأكمل الحجز. بيئة الاختبار تستخدم مسار دفع تجريبي — لا يتم خصم بطاقة حقيقية.

عند ظهور صفحة التأكيد، سجل رمز الحجز (بصيغة WNKxxxxx) المعروض للضيف.

استرجع كل الحجوزات التي تم إنشاؤها لمنشأتك الاختبارية ضمن نافذة زمنية تغطي توقيت الحجز.

نافذة طرفيّة
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/list?startDate=2026-09-01T00:00:00&endDate=2026-09-08T00:00:00" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

ابحث عن الإدخال الذي يطابق bookingCode الرمز الذي سجلته في الخطوة و. سجل bookingIdentifier الخاص به. ثم استرجع ذلك الحجز المفرد:

نافذة طرفيّة
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/{bookingIdentifier}" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

الاستجابة هي PropertyBooking. استوردها في نظام إدارة الممتلكات / واجهة مدير القناة الخاص بك وتأكد من أن كل مما يلي يظهر بشكل صحيح للمشغل:

  • bookingCode, bookingIdentifier, createdDate
  • الضيف: firstName, lastName, email
  • totalAmount + currencyCode (صافي المبلغ الذي يستلمه الفندق عبر كل الغرف)
  • paymentMethodType, paymentMethodStatus, salesChannelName
  • كل إدخال في roomStays: guestRoomName, ratePlanName, adults, children, startDate, endDate، والمبلغ لكل غرفة

التقط لقطة شاشة للحجز كما يظهر في واجهتك — هذه اللقطة هي واحدة من الأدلة المطلوبة.

الخطوة ح — إلغاء الحجز والتحقق

Section titled “الخطوة ح — إلغاء الحجز والتحقق”

اطلب من فريق Wink إلغاء حجز الشهادة نيابة عنك (أو قم بإلغائه بنفسك من حساب الفندق في الواجهة الخارجية إذا كان لديك الإذن). ثم أعد جلب نفس الحجز باستخدام المكالمة من الخطوة ز.

تأكد من أن الاستجابة الآن تظهر:

  • cancelled: true
  • طابع زمني cancelDate مملوء
  • paymentMethodStatus يعكس دورة حياة الإلغاء (CANCELLED, PARTIALLY_REFUNDED, أو FULLY_REFUNDED حسب سياسة الاسترداد)

استورد الحجز المحدث في واجهتك وتأكد من أن الإلغاء مرئي للمشغل — الحالة، وطابع الإلغاء، وأي مؤشر استرداد تدعمه واجهتك. التقط لقطة شاشة ثانية للحجز الملغي في واجهتك. هذه هي الدليل النهائي.

الخطوة ط — تقديم حزمة الأدلة

Section titled “الخطوة ط — تقديم حزمة الأدلة”

اجمع ما يلي في أرشيف واحد (.zip) باسم wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip:

  1. نص API. لكل طلب أرسلته في الخطوات أ حتى ح، التقط الطلب HTTP الكامل (الطريقة، URL، رؤوس الطلب مع إخفاء قيمة Authorization، وجسم JSON لطلبات PUT) والاستجابة HTTP الكاملة (رمز الحالة، رؤوس الاستجابة، وجسم JSON). نظم النص بحيث يكون كل زوج طلب/استجابة معنونا بوضوح بالخطوة التي ينتمي إليها (step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json، وهكذا). ملفات .http نصية عادية أو تصدير .har واحد كلاهما مقبول.

  2. لقطة شاشة للواجهة: الحجز النشط. لقطة الشاشة من الخطوة ز تظهر الحجز في واجهة نظام إدارة الممتلكات / مدير القناة الخاص بك، مع الضيف، التواريخ، نوع الغرفة، خطة السعر، والإجمالي واضحة.

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

  4. ملخص الشهادة. ملف README.md قصير داخل الأرشيف يذكر:

    • اسم وإصدار مدير القناة / نظام إدارة الممتلكات الخاص بك.
    • managingEntityIdentifier, propertyIdentifier, masterRateIdentifier, و bookingIdentifier التي استخدمتها.
    • معرف الفندق في بيئة الاختبار (الـ <your-slug> في https://staging-book.wink.travel/hotel/<your-slug>).
    • نطاق تواريخ أسبوع الشهادة (اليوم 1 → اليوم 7 بصيغة ISO-8601).
    • اسم وبريد المهندس الذي أجرى الشهادة.

أرسل الأرشيف إلى جهة اتصال تكاملات Wink. ستراجع Wink، تتابع أي اختلاف، وعند النجاح، تغير حالة حساب التابع / مدير القناة الخاص بك من PENDING_APPROVAL إلى ACTIVE. يصبح تكاملك مؤهلاً للانضمام إلى الإنتاج.

يمكنك الاشتراك في أحداث Webhook الخاصة بمدير القناة لتلقي إشعارات في الوقت الحقيقي:

  • channel-manager.update.rate — تم استلام تحديث السعر.
  • channel-manager.update.availability — تم استلام تحديث التوافر.
  • channel-manager.update — تحديث عام لمدير القناة.

راجع كتالوج أحداث Webhook للتفاصيل.