خادم الشريك

لدمج معلومات الأسعار ومدى التوفّر، على الشركاء استخدام Partner API. تستند واجهة برمجة التطبيقات هذه إلى REST وتسمح لـ Google بإرسال مكالمات مباشرة عبر HTTP. في حين يتم وصف تفاصيل طرق واجهة برمجة التطبيقات الفردية في قسم المراجع، يمكنك العثور على معلومات حول المشاكل الشاملة لاحقًا.

تنسيق الطلب والاستجابة

في البداية، لن يتم توفير سوى تنسيقات JSON. إذا كنت بحاجة إلى تنسيقات إضافية للطلبات أو الردود، يُرجى التواصل مع فريق "النقل والسفر" على transport-help@google.com لمناقشة حالة الاستخدام.

سيتم إرسال الطلبات باستخدام طريقة HTTP POST، مع تضمين رسالة الطلب في نص POST.

يُرجى العِلم أنّه لتوضيح البنية، يتم توفير مستندات واجهة برمجة التطبيقات على شكل تعريفات رسائل Protocol Buffer، ويتم تحديد ترجمة تعريف رسالة Protocol Buffer إلى عنصر JSON من خلال عملية الربط بين JSON الأساسي وProtocol Buffer، وذلك باستخدام الخيارات لإصدار الحقول بالقيم التلقائية واستخدام أسماء حقول proto بدلاً من أسماء lowerCamelCase.

المصادقة

تتيح Google مصادقة الملخّص عبر HTTP وOAuth 2.0 ومصادقة شهادة العميل (راجِع إعدادات الشريك). على الشريك تقديم بيانات الاعتماد الصحيحة إلى Google أثناء اختبار واجهة برمجة التطبيقات:

  • بالنسبة إلى Digest: اسم المستخدم وكلمة المرور
  • بالنسبة إلى OAuth 2.0: client_id وclient_secret
  • بالنسبة إلى "الشهادة": شهادة عميل بروتوكول SSL (طبقة المقابس الآمنة).

رموز الحالة والتعامل مع الأخطاء

بشكل عام، يمكن إرجاع رموز الحالة التالية في استجابات HTTP:

رمز HTTP وصف HTTP ملاحظات
2xx حسنًا ليس خطأ، بل يتم عرضه عند النجاح. من المتوقّع أن يحتوي نص الاستجابة على نتيجة ناجحة (مثل TripOptionsResult)، وليس استجابة خطأ.
400 طلب سيئ الطلب الذي تم تلقّيه غير صالح. يجب استخدام ردود الأخطاء الخاصة بالطريقة لعرض تفاصيل إضافية عن الخطأ في نص الرد. يجب بشكل عام استخدام الخطأ HTTP 400 فقط إذا ارتكب محرّك بحث Google خطأً فنيًا (مثل حقل تمت تسميته بشكل خاطئ في الطلب).
403 ممنوع تم رفض الإذن أو حظره (المتصل معروف وتم رفضه). يجب عدم استخدام رمز الحالة هذا للرفض بسبب استنفاد بعض الموارد (استخدِم رمز Too Many Requests بدلاً من ذلك لهذه الأخطاء). يجب عدم استخدام Forbidden إذا تعذّر تحديد هوية المتصل (استخدِم Unauthorized بدلاً من ذلك لهذه الأخطاء).
404 لم يتم العثور على عرض تعذَّر العثور على المورد المطلوب. يجب استخدام ردود الأخطاء الخاصة بالطريقة لعرض تفاصيل إضافية حول الخطأ في نص الرد.
429 أرسلت عددًا كبيرًا جدًا من الطلبات تم استنفاد بعض الموارد، ربما حصة لكل مستخدم.
500 خطأ في الخادم الداخلي أخطاء داخلية وهذا يعني أنّه تم انتهاك بعض الثوابت التي يتوقّعها النظام الأساسي. رمز الخطأ هذا مخصّص للأخطاء الجسيمة، ويشير إلى وجود خطأ في تنفيذ خادم واجهة برمجة التطبيقات لدى الشريك.
503 الخدمة غير متوفرة الخدمة غير متاحة. من المرجّح أنّ هذه الحالة عابرة ويمكن تصحيحها من خلال إعادة المحاولة مع التراجع.
504 انتهت مهلة البوابة انتهت المهلة قبل أن تتمكّن العملية من الاكتمال. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح. على سبيل المثال، قد يتأخر الردّ الناجح من الخادم لفترة طويلة بما يكفي لانتهاء الموعد النهائي.

يُرجى العِلم أنّه بالنسبة إلى جميع الشروط المسبقة أو الوسيطات غير الصالحة أو الأخطاء التي لم يتم العثور عليها:

  • يجب استخدام الردود أو رسائل الخطأ الخاصة بالطريقة والمحدّدة في واجهات برمجة التطبيقات.
  • يجب استخدام رمز http الصحيح، كما هو محدّد في الرموز الخاصة بالطريقة (راجِع على سبيل المثال TripOptionsErrorType)

ويتيح ذلك تقديم معلومات أكثر تفصيلاً حول هذه الأنواع من الأخطاء. يمكن استخدام هذه المعلومات في ما يلي:

  • تحديد ما إذا كان يمكن إعادة محاولة تنفيذ عملية نتج عنها خطأ
    • لا يمكن إعادة محاولة SEGMENT_KEY_NOT_FOUND.
  • تصحيح المعلومات القديمة
    • يشير الرمز Unavailable.Reason.CANCELED إلى أنّه يجب إزالة الرحلة (يُرجى العِلم أنّ هذا الرمز جزء من استجابة ناجحة).
    • بالإضافة إلى رموز الخطأ SEGMENT_KEY_NOT_FOUND وSUBOPTIMAL_ITINERARY وBOOKING_WINDOW_NOT_SUPPORTED وTICKETING_PROHIBITED، ستؤدي الاستجابة Unavailable.Reason.TEMPORARILY_UNAVAILABLE إلى إزالة أي أسعار تلقّيناها سابقًا من ذاكرة التخزين المؤقت.
  • تقديم إرشادات مناسبة للمستخدمين

تمثّل القائمة الحالية بالأخطاء الخاصة بطريقة معيّنة والمقدَّمة في TripOptionsError نقطة البداية. إذا كنت بحاجة إلى أنواع أخطاء إضافية، يُرجى التواصل مع فريق Google Travel Transport.

الطلبات في الثانية

من المرجّح أن يختلف مستوى طلبات البحث في الثانية التي ترسلها Google استنادًا إلى المساحة الإعلانية الخاصة بالشريك وعدد المستخدمين الذين يشاهدون البيانات المخزّنة مؤقتًا أو ينقرون للوصول إلى مواقع الشركاء الإلكترونية لإجراء الحجز.

وقت الاستجابة

ستنتهي مهلة الطلبات بعد 10 ثوانٍ. لن تكون هناك إرشادات إضافية بشأن وقت الاستجابة لعمليات الدمج مع الشركاء في الإصدار التجريبي. ومع ذلك، سيتم تحديد المزيد من اتفاقيات مستوى الخدمة المتعلقة بوقت الاستجابة في "إرشادات جودة بيانات الشركاء".

العملات والضرائب والرسوم

يجب أن تشمل جميع الأسعار المُرسَلة إلى Google كل الضرائب والرسوم، ويجب أن تكون محددة بعملة متوافقة.

العملة

يتم تحديد عملة السعر باستخدام الحقل currency_code، الذي يجب أن يكون رمز عملة صالحًا وفقًا لمعيار ISO 4217.

المثال 10,25 USD:

{
  "price": {
    "currency_code": "USD",
    "units": 10,
    "nanos": 250000000
  }
}

الضرائب والرسوم

يجب أن يكون السعر الذي تقدّمه هو السعر الإجمالي النهائي الذي سيدفعه المستخدم، ويشمل جميع الضرائب (مثل ضريبة القيمة المضافة) وأي رسوم إضافية (مثل رسوم الحجز أو بطاقة الدفع). يمكن إضافة تفاصيل اختيارية عن الأجرة باستخدام الحقل المتكرّر line_items. ستعرض Google السعر الإجمالي مع تفصيل اختياري للأجرة للمستخدم.