خادم الشريك

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

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

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

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

يُرجى العِلم أنّه لتوضيح البنية، يتم توفير مستندات واجهة برمجة التطبيقات على شكل تعريفات رسائل Protocol Buffer، ويتم تحديد ترجمة تعريف رسالة Protocol Buffer إلى عنصر JSON من خلال عملية الربط بين JSON الأساسي، وذلك باستخدام الخيارات لإصدار الحقول بالقيم التلقائية ولاستخدام أسماء حقول 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 إلى أنّه يجب إزالة الرحلة (يُرجى العِلم أنّ هذا الرمز هو جزء من استجابة ناجحة)
    • Unavailable.Reason.TEMPORARILY_UNAVAILABLE بالإضافة إلى رموز الخطأ SEGMENT_KEY_NOT_FOUND وSUBOPTIMAL_ITINERARY وBOOKING_WINDOW_NOT_SUPPORTED وTICKETING_PROHIBITED، ستؤدي إلى إزالة أي أسعار تلقّيناها سابقًا من ذاكرة التخزين المؤقت.
  • تقديم إرشادات مناسبة للمستخدمين

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

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

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

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

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

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

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

العملة

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

مثال 10.25 SAR:

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

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

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