أضف مدير القناة الخاص بك
يرشد هذا الدليل مطوري مديري القنوات وأنظمة إدارة الممتلكات خلال العملية الكاملة للتكامل مع Wink — من إنشاء حساباتكم إلى تعيين المخزون وتشغيل أول اختبار شامل.
البيئات
Section titled “البيئات”واجهة برمجة تطبيقات مدير القناة (التكاملات) متاحة في بيئتين. استخدم بيئة الاختبار لجميع التطوير والشهادات؛ وانتقل إلى الإنتاج فقط عند الإطلاق.
| البيئة | عنوان URL الأساسي |
|---|---|
| الإنتاج | https://integrations.wink.travel |
| الاختبار | https://staging-integrations.wink.travel |
مرجع API
Section titled “مرجع API”تتبع واجهة برمجة تطبيقات مدير القناة معايير بروتوكول OTA (SOAP/XML) لضمان التوافق مع أنظمة الضيافة الحالية. ابدأ بمراجعة توثيق نقاط النهاية الخاصة بالشريك:
واجهة برمجة تطبيقات مدير القناة — نقاط نهاية الشريك
خطوات التكامل
Section titled “خطوات التكامل”-
إنشاء حساب مستخدم في Wink
سجّل في staging-app.wink.travel. جميع الخطوات أدناه تستخدم بيئة الاختبار — ستكرر العملية كاملة في الإنتاج قبل الإطلاق.
-
إنشاء حساب تابع / مدير قناة
تحت حساب المستخدم الجديد، أنشئ حسابًا واختر نوع الحساب تابع / مدير قناة. هذا هو الحساب الذي ستستخدمه المصادقة في التكامل.
-
تسجيل تطبيق وإنشاء أول رمز وصول
أنشئ تطبيقًا واربطه بحساب مدير القناة من الخطوة 2. اختر نوع العميل MACHINE_2_MACHINE — هذا تكامل خادم إلى خادم بدون إعادة توجيه للمستخدم النهائي. انسخ معرف العميل والمفتاح السري فورًا؛ المفتاح السري يظهر مرة واحدة فقط ولا يمكن استرجاعه لاحقًا.
التطبيق هو الذي يصدر رمز الحامل الذي تحمله كل مكالمة في هذا الدليل كـ
Authorization: Bearer <access_token>. استبدل بيانات اعتمادك برمز باستخدام منحةclient_credentialsعبرhttps://staging-iam.wink.travel/oauth2/token، مع طلب صلاحياتintegrations.read integrations.write. قم بذلك قبل المتابعة — لا يمكنك البحث عن معرفات الحساب أو الوصول إلى أي نقطة نهاية لمدير القناة بدون رمز. راجع المصادقة للتدفق الكامل، المضيف الإنتاجي، وكامل قائمة الصلاحيات. -
إنشاء حساب فندق
تحت نفس المستخدم، أنشئ حسابًا ثانيًا واختر نوع الحساب فندق. هذا يمنحك منشأة يمكنك استخدامها للاختبار دون الحاجة لفندق حقيقي.
-
تأكيد الموافقة على كلا الحسابين
لا يمكن استخدام أي من الحسابين حتى تتم الموافقة عليه: حساب مدير القناة غير الموافق عليه لا يظهر في قائمة مديري القنوات لأي فندق، والفندق غير الموافق عليه لا يتم إرجاعه بواسطة API.
- الاختبار — الموافقة تلقائية. كلا الحسابين قابلان للاستخدام فور إنشائهما، ولا حاجة لطلب شيء.
- الإنتاج — الموافقة يدوية. أرسل إلى جهة اتصال تكاملات Wink أسماء كلا الحسابين والمستخدم الذي ينتميان إليه، ثم انتظر التأكيد قبل المتابعة.
-
ربط الحسابين
سجّل الدخول إلى حساب الفندق وانتقل إلى القنوات → مدير القناة. اختر حساب مدير القناة الخاص بك من القائمة — هذا يربط المنشأة بتكاملتك. إذا لم يكن حسابك في القائمة، فهو لم يُوافق عليه بعد؛ راجع الخطوة 5.
-
إنشاء نوع غرفة وخطة أسعار أساسية
داخل حساب الفندق، أنشئ على الأقل نوع غرفة واحد وخطة أسعار واحدة. هذه مطلوبة قبل أن تتمكن من دفع الأسعار والتوافر أو سحب الحجوزات.
-
التعيين والاختبار
في نظامك الخاص، عين معرفات نوع الغرفة وخطة الأسعار التي يعيدها 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حتى تجتاز الشهادة؛ وهذا متوقع ولا يعيق التطوير.
الشهادة
Section titled “الشهادة”الشهادة هي الطريقة التي تثبت بها — وتؤكد Wink — أن تكاملك يعين المخزون بشكل صحيح، ويدفع الأسعار والتوافر، ويتلقى الحجوزات بشكل شامل. تم تصميمها لتكون خدمة ذاتية: أنت تدير كل خطوة من نظامك الخاص، وترسل حزمة أدلة واحدة في النهاية. تراجع Wink الحزمة وعند النجاح، ترفع حالة حساب التابع / مدير القناة الخاص بك من PENDING_APPROVAL إلى ACTIVE.
تتم الشهادة بالكامل في بيئة الاختبار
(https://staging-integrations.wink.travel). لا شيء في هذا القسم يمس الإنتاج.
ما ستثبته
Section titled “ما ستثبته”-
المصادقة. يمكن لعميل OAuth2 الخاص بك الحصول على رمز وصول واستدعاء نقطة النهاية
/pingبنجاح ضد حساب التابع / مدير القناة الخاص بك. -
تعيين المخزون. يمكنك سرد الفندق (أو الفنادق) المرتبطة بحسابك، واسترجاع السعر الرئيسي (نوع الغرفة × خطة السعر) الذي قمت بتكوينه، وتحديد
masterRateIdentifierالذي سيستهدفه نظامك بشكل صحيح. -
دفع السعر والتوافر. يمكنك تحديث جميع أيام الأسبوع السبعة لشهر الشهادة بشكل مستقل — مع تركيبات مختلفة من المبلغ، والكمية، وعلامات الإغلاق عند الوصول / المغادرة، والحد الأدنى / الأقصى لطول الإقامة في كل يوم — وقراءة القيم الدقيقة مرة أخرى من Wink.
-
سحب الحجز. يمكنك استرجاع حجز حقيقي في بيئة الاختبار تم إجراؤه ضد منشأتك الاختبارية، عرضه في واجهة نظام إدارة الممتلكات / مدير القناة الخاص بك مع تفاصيل الغرفة، الضيف، والإجمالي بشكل صحيح، ثم عكس الإلغاء بمجرد أن تعلن Wink أن الحجز ملغى.
المتطلبات المسبقة
Section titled “المتطلبات المسبقة”قبل بدء الشهادة، أكمل الخطوات 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.0Accept: 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 عليك.
الخطوة ب — سرد المنشآت
Section titled “الخطوة ب — سرد المنشآت”استرجع قائمة الفنادق المرتبطة بحسابك مع الترقيم وتأكد من وجود منشأتك الاختبارية.
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 سيتم تعيينها بشكل صحيح افتراضيًا.
| اليوم | المبلغ | الكمية | مغلق عند الوصول | مغلق عند المغادرة | الحد الأدنى للإقامة | الحد الأقصى للإقامة | ما يثبته |
|---|---|---|---|---|---|---|---|
| 1 | 100.00 | 5 | false | false | 1 | 30 | يوم الأساس. |
| 2 | 125.00 | 4 | false | false | 1 | 14 | تغيير المبلغ + الكمية + maxLengthOfStay. |
| 3 | 150.00 | 3 | true | false | 1 | 30 | تبديل closedOnArrival. |
| 4 | 175.00 | 2 | false | true | 2 | 7 | تبديل closedOnDeparture + نافذة إقامة أكثر تقييدًا. |
| 5 | 200.00 | 0 | false | false | 1 | 30 | كمية نفدت. |
| 6 | 225.00 | 5 | false | false | 3 | 5 | نافذة إقامة مقيدة. |
| 7 | 250.00 | 1 | false | false | 1 | 30 | توافر الغرفة الأخيرة. |
جسم الطلب لليوم 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) المعروض للضيف.
الخطوة ز — سحب الحجز
Section titled “الخطوة ز — سحب الحجز”استرجع كل الحجوزات التي تم إنشاؤها لمنشأتك الاختبارية ضمن نافذة زمنية تغطي توقيت الحجز.
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:
-
نص 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واحد كلاهما مقبول. -
لقطة شاشة للواجهة: الحجز النشط. لقطة الشاشة من الخطوة ز تظهر الحجز في واجهة نظام إدارة الممتلكات / مدير القناة الخاص بك، مع الضيف، التواريخ، نوع الغرفة، خطة السعر، والإجمالي واضحة.
-
لقطة شاشة للواجهة: الحجز الملغي. لقطة الشاشة من الخطوة ح تظهر نفس الحجز في واجهتك بعد الإلغاء، مع حالة الإلغاء والطابع الزمني واضحة.
-
ملخص الشهادة. ملف
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
Section titled “إشعارات Webhook”يمكنك الاشتراك في أحداث Webhook الخاصة بمدير القناة لتلقي إشعارات في الوقت الحقيقي:
channel-manager.update.rate— تم استلام تحديث السعر.channel-manager.update.availability— تم استلام تحديث التوافر.channel-manager.update— تحديث عام لمدير القناة.
راجع كتالوج أحداث Webhook للتفاصيل.
قراءة إضافية
Section titled “قراءة إضافية”- واجهة برمجة تطبيقات مدير القناة — توثيق كامل لنقاط نهاية API.
- مدير القناة — إدارة مزودي الأسعار في الواجهة الخارجية.
- كتالوج أحداث Webhook — كل الأحداث القابلة للاشتراك.
- البناء على Wink — نظرة عامة على المنصة للمطورين.
