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

البدء السريع

هذا الدليل يأخذك من لا شيء إلى تكامل يعمل في حوالي 30 دقيقة. بنهايته سيكون لديك:

  • أسعار حية للفنادق في مدينة، من Partner API،
  • رابط حجز يُنسب الحجز إلى حسابك،
  • حجز تجريبي، وwebhook يخبرك بأنه حدث.

كل شيء يحدث في بيئة الاختبار، بيئة الاختبار الخاصة بنا. لا تحتاج إلى طلب وصول منا، والانتقال إلى الإنتاج لاحقًا لا يحتاج إلى موافقة أيضًا.

هل هذا الدليل مناسب لك؟

Section titled “هل هذا الدليل مناسب لك؟”
تريد أن…ابدأ من هنا
عرض الفنادق في تطبيقك أو موقعك أو منتج الذكاء الاصطناعي وإرسال المسافرين للحجز، وكسب عمولةهذا الدليل
الحجز نيابة عن عملائك كوكالة سفر مرخصةهذا الدليل حتى الخطوة 5، ثم الحجز كوكالة سفر
تضمين فنادق قابلة للحجز بدون كتابة تكاملمكونات الويب
السماح لوكيل ذكاء اصطناعي بالبحث والحجزخوادم MCP و Agentic Payments
ربط مدير قناة أو نظام إدارة الممتلكاتأضف مدير قناتك

تستخدم Partner API للعثور على الفنادق وأسعارها الحية. كل فندق يأتي مع urlName ثابت. تحوله إلى رابط إلى محرك حجز Wink، book.wink.travel، يحمل معرفاتك. يقوم المسافر بالحجز والدفع هناك، ويتم نسب الحجز إلى حسابك.

ستحتاج إلى:

  • grpcurl، أو Postman أو Insomnia. Partner API هو gRPC، وليس REST.
  • curl.

الخطوة 1: إنشاء حساب في بيئة الاختبار

Section titled “الخطوة 1: إنشاء حساب في بيئة الاختبار”

بيئة الاختبار منفصلة تمامًا عن الإنتاج، مع تسجيل دخول وحسابات خاصة بها.

  1. اذهب إلى staging-app.wink.travel، انقر على تسجيل الدخول / تسجيل وسجل حسابًا.

  2. انقر على الحسابات في الشريط الجانبي الأيسر، ثم إنشاء، واختر أنا تابع. الحجوزات التي ترسلها تُنسب إلى هذا الحساب. راجع إنشاء حساب.

التطبيق يمنح كودك بيانات الاعتماد الخاصة به.

  1. على بطاقة حسابك، انقر على الإجراءات > إدارة الحساب، ثم تبويب التطبيقات.

  2. انقر على إنشاء تطبيق جديد، أعطه اسمًا واختر آلة إلى آلة كنوع العميل.

  3. ضمن الصلاحيات، اختر المخزون والأسعار (قراءة). Partner API يتحقق من inventory.read.

  4. انقر على إنشاء تطبيق ونسخ معرف العميل و سر العميل. السر يظهر مرة واحدة ولا يمكن استرجاعه لاحقًا.

راجع التطبيقات لأنواع العملاء والصلاحيات الأخرى.

الخطوة 3: الحصول على رمز وصول

Section titled “الخطوة 3: الحصول على رمز وصول”
نافذة طرفيّة
curl -X POST https://staging-iam.wink.travel/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=<YOUR_CLIENT_ID>" \
-d "client_secret=<YOUR_CLIENT_SECRET>" \
-d "scope=inventory.read"

احفظ access_token من الاستجابة:

نافذة طرفيّة
export WINK_TOKEN=<access_token>

الرموز تنتهي صلاحيتها. في كودك الخاص، استخدم مكتبة OAuth2 لجلبها وتحديثها. راجع المصادقة.

إذا تم رفض طلب الرمز، تكون الاستجابة جسم JSON مع رمز error:

errorحالة HTTPالسبب المعتاد
invalid_client401معرف العميل أو السر خاطئ، أو تم استخدام بيانات اعتماد الإنتاج على staging-iam
invalid_scope400الطلب يطلب صلاحية لم يُسجل لها التطبيق
unauthorized_client400التطبيق غير مسموح له باستخدام منحة client_credentials
invalid_request400معلمة مطلوبة مفقودة، مثلاً عندما يكون الجسم JSON بدلاً من نموذج

الخطوة 4: العثور على معرف حسابك

Section titled “الخطوة 4: العثور على معرف حسابك”

كل مكالمة Partner API تسمي الحساب الذي تعمل نيابة عنه في رأس managing-entity-id. قم بسرد الحسابات التي يمكن لرمزك العمل نيابة عنها:

نافذة طرفيّة
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-d '{}' \
staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccounts

انسخ accountId لحساب التابع من الخطوة 1:

نافذة طرفيّة
export WINK_ACCOUNT_ID=<accountId>

الخطوة 5: البحث عن فنادق في مدينة

Section titled “الخطوة 5: البحث عن فنادق في مدينة”

بيئة الاختبار تحتوي على فنادق اختبار متاحة في بانكوك، لذا يستخدم هذا البحث معرفها، bangkok-thailand:

نافذة طرفيّة
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
-H "managing-entity-id: $WINK_ACCOUNT_ID" \
-d '{
"urlName": "bangkok-thailand",
"userSession": {
"itinerary": {
"startDate": "2026-12-01",
"nights": 2,
"room": { "adults": 2 }
},
"currencyCode": "USD",
"languageCode": "en"
}
}' \
staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCity

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

  • name، starRating و heroImageUrl، كافية لعرض صف النتيجة،
  • roomTypes، العروض الحية، أرخص غرفة أولاً،
  • urlName، المعرف الذي تحتاجه لرابط الحجز.

الأسعار أعداد صحيحة بوحدات فرعية: اقسم على 10 مرفوعًا لقوة currencyExponent من الاستجابة (2 للدولار الأمريكي، لذا 12500 تعني 125.00 دولار).

لا تعرف معرف المدينة؟ حلله باستخدام wink.partner.v1.Lookup/Search. لمحتوى العقار الكامل، استخدم خدمة Content. توثيق Partner API يشرح كل مكالمة.

الخطوة 6: بناء رابط الحجز

Section titled “الخطوة 6: بناء رابط الحجز”
https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>
  • <urlName> هو urlName للفندق من الخطوة 5.
  • client-id هو معرف العميل لتطبيقك من الخطوة 2.
  • configuration-id هو معرف التخصيص الخاص بك: إدارة الحساب > التخصيصات. التخصيص يحدد أيضًا علامتك التجارية، اللغة الافتراضية والعملة في صفحة الحجز.

أضف تواريخ المسافر، الضيوف، اللغة والعملة إلى نفس الرابط حتى تفتح صفحة الفندق مع تعبئتها:

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD
المعاملالمعنىمثال
sdتاريخ تسجيل الوصولsd=2027-03-14
n أو edعدد الليالي، أو تاريخ تسجيل المغادرةn=2 أو ed=2027-03-16
rcعدد الضيوف في الغرفةrc=a2 (2 بالغين)
lلغة العرضl=en
cعملة العرضc=USD
pرمز الترويجp=ABC123

هذه المعاملات تتجاوز الإعدادات الافتراضية في تخصيصك. يغطي دليل زر الحجز الآن صيغة rc الكاملة، بما في ذلك الأطفال وعدة غرف.

الرابط يفتح صفحة الفندق؛ لا يمكنه اختيار غرفة أو سعر مسبقًا. يختار المسافر الغرفة في صفحة الفندق، بالسعر الحي.

راجع الربط المباشر للربط بصفحة محرك الحجز الرئيسية بدلًا من فندق واحد.

الخطوة 7: إجراء حجز تجريبي

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

افتح رابطك، اختر التواريخ والغرفة، وأكمل الدفع باستخدام بطاقة اختبار Stripe، مثلاً 4242 4242 4242 4242 مع أي تاريخ انتهاء مستقبلي وأي CVC. لا يتم خصم أي مبلغ حقيقي في بيئة الاختبار. لاحظ رمز الحجز في صفحة التأكيد؛ يبدأ بـ WNK.

الخطوة 8: الحصول على إشعارات بالحجوزات

Section titled “الخطوة 8: الحصول على إشعارات بالحجوزات”
  1. في البوابة، اذهب إلى التطبيقات > Webhooks وأضف نقطة نهاية تقبل طلبات POST.

  2. اشترك في booking.create، أو اترك قائمة الأحداث فارغة لتستقبل كل شيء أثناء التطوير.

  3. أرسل لنفسك حدث اختبار، ثم قم بحجز تجريبي آخر وراقب وصوله.

تحقق من توقيع كل تسليم قبل الوثوق به. راجع تكامل Webhook و كتالوج أحداث Webhook.

الخطوة 9: الانتقال إلى الإنتاج

Section titled “الخطوة 9: الانتقال إلى الإنتاج”

لا توجد خطوة موافقة للمطورين. (حسابات وكالات السفر تُعتمد أولاً؛ راجع أدناه.) عندما يعمل تكاملك في بيئة الاختبار:

  1. أنشئ حسابًا وتطبيقًا في app.wink.travel، كما في الخطوتين 1 و2. بيانات الاعتماد لا تنتقل بين البيئات.

  2. احذف staging- من كل مضيف:

    بيئة الاختبارالإنتاج
    https://staging-iam.wink.travelhttps://iam.wink.travel
    staging-partner.wink.travel:443partner.wink.travel:443
    https://staging-book.wink.travelhttps://book.wink.travel
  3. ابحث عن معرف حساب الإنتاج (الخطوة 4) ومعرف التخصيص (الخطوة 6) مرة أخرى. يختلفان عن بيئة الاختبار.

يتم قياس استخدام Partner API بعدد ليالي الفنادق، مع حصة مجانية شهرية. راجع Partner API للأسعار والحدود.

إذا كان حسابك وكالة سفر مرخصة، لا تحتاج إلى إرسال المسافرين إلى book.wink.travel: يمكنك إنشاء الحجوزات مباشرة باستخدام wink.partner.v1.Booking/CreateBooking، وإدارتها باستخدام مكالمات Booking الأخرى. الحسابات الأخرى ترسل المسافرين إلى رابط الحجز بدلاً من ذلك.

حسابات وكالات السفر معتمدة: تقوم Wink بمراجعة تسجيل كل وكالة قبل أن تتمكن من الحجز. الوكالات التي تريد تحصيل الدفع من عملائها بأنفسهم، كتاجر مسجل، يجب أن تحجز عبر Partner API وتحصل على موافقة مكتوبة من Wink. راجع البدء كوكالة سفر و توثيق Partner API.