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

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

يرشدك هذا الدليل خلال العملية الكاملة لتكامل مديري القنوات ومطوري أنظمة إدارة الممتلكات مع 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. ربط الحسابين

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

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

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

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

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

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

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

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

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

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

Terminal window
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 لحساب HOTEL هو {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 في بيئة الاختبار مع حساب تابع / مدير قناة وحساب فندق مرتبط به (Extranet → التوزيع → مدير القناة). يتم اعتماد حسابات بيئة الاختبار تلقائيًا، لذلك لا حاجة لطلب شيء هنا.
  • على الأقل نوع غرفة واحد وخطة أسعار واحدة تم إنشاؤها داخل حساب الفندق. انشر الفندق ليكون قابلاً للحجز على 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 الإصدار 2.
  • Content-Type: application/json يضاف في طلبات PUT التي تحمل جسمًا.

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

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

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

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

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

Terminal window
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 عليك.

الخطوة ب — قائمة العقارات

Section titled “الخطوة ب — قائمة العقارات”

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

Terminal window
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}.

Terminal window
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 + نافذة LOS أضيق.
5200.000falsefalse130كمية نفدت.
6225.005falsefalse35نافذة LOS مقيدة.
7250.001falsefalse130توافر الغرفة الأخيرة.

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

Terminal window
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 “الخطوة هـ — قراءة أسبوع الشهادة”

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

Terminal window
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) المعروض للضيف.

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

Terminal window
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 الخاص به. ثم استرجع هذا الحجز المفرد:

Terminal window
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 إلغاء حجز الشهادة نيابة عنك (أو قم بإلغائه بنفسك من خلال Extranet حساب الفندق إذا كان لديك الإذن). ثم أعد استرجاع نفس الحجز باستخدام المكالمة من الخطوة ز.

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

  • 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 للتفاصيل.