البدء السريع

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

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

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

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

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

كيف يعمل

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

قبل أن تبدأ

ستحتاج إلى:

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

ملاحظة

بيئة الاختبار تدخل في وضع السكون عندما لا يستخدمها أحد. أول مكالمة بعد فترة هدوء قد تستغرق حوالي دقيقة بينما تستيقظ الخوادم.

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

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

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

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

الخطوة 2: إنشاء تطبيق

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

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

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

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

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

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

الخطوة 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 تجلبها وتحدثها. راجع المصادقة.

الخطوة 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: البحث عن فنادق في مدينة

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: بناء رابط الحجز

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 هو معرف التخصيص الخاص بك: إدارة الحساب > التخصيصات. التخصيص يحدد أيضًا علامتك التجارية، اللغة الافتراضية والعملة في صفحة الحجز.

تنبيه

تضمّن كلا المعرفين. بدونهما الصفحة تُحمّل، لكن بعلامة تجارية افتراضية، والحجز لا يُنسب إليك. لا تضع سر العميل في الرابط أبدًا.

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

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

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

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

1. في البوابة، اذهب إلى التطبيقات > Webhooks وأضف نقطة نهاية تقبل طلبات POST.

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

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

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

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

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

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

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

   بيئة الاختبار	الإنتاج
   https://staging-iam.wink.travel	https://iam.wink.travel
   staging-partner.wink.travel:443	partner.wink.travel:443
   https://staging-book.wink.travel	https://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.

الخطوات التالية

• توليد عميل مكتوب الأنواع من مخطط .proto بدلاً من استدعاء grpcurl يدويًا.
• ربط خادم MCP واستخدام مهارات الذكاء الاصطناعي ليكتب مساعدك البرمجي التكامل ضد API الحي.
• قراءة القائمة الكاملة لـ البيئات والمضيفين.