שרת של שותף

כדי לשלב מידע על מחירים וזמינות, השותפים צריכים להטמיע את Partner API. הממשק הזה מבוסס על REST ומאפשר ל-Google לשלוח שיחות בזמן אמת באמצעות HTTP. פרטים על שיטות API ספציפיות מפורטים בקטע הפניה, ומידע על בעיות חוצות אפשר למצוא בהמשך.

פורמט הבקשה והתגובה

בתחילה תהיה תמיכה רק בפורמטים של JSON. אם אתם צריכים פורמטים נוספים של בקשות או תגובות, אתם יכולים לפנות לצוות Travel Transport בכתובת transport-help@google.com כדי לדון בתרחיש השימוש שלכם.

הבקשות יישלחו באמצעות שיטת ה-HTTP‏ POST, עם הודעת הבקשה בגוף ה-POST.

שימו לב: כדי להבהיר את המבנה, תיעוד ממשק ה-API מסופק כהגדרות של הודעות Protocol Buffer, והתרגום של הגדרת הודעת Protocol Buffer לאובייקט JSON מוגדר על ידי מיפוי JSON קנוני, באמצעות האפשרויות לפליטת שדות עם ערכי ברירת מחדל ולשימוש בשמות שדות פרוטו במקום בשמות lowerCamelCase.

אימות

‫Google תומכת באימות HTTP Digest, ב-OAuth 2.0 ובאימות באמצעות אישור לקוח (ראו הגדרת שותף). השותף צריך לספק ל-Google את פרטי הכניסה הנכונים במהלך בדיקת ה-API:

  • עבור Digest: שם משתמש וסיסמה.
  • ‫OAuth 2.0: client_id ו-client_secret.
  • בשדה Certificate (אישור): אישור לקוח SSL.

קודי סטטוס וטיפול בשגיאות

באופן כללי, קודי המצב הבאים יכולים להיות מוחזרים בתגובות HTTP:

קוד HTTP תיאור HTTP הערות
‫2xx אישור לא שגיאה, מוחזר אם הפעולה הצליחה. גוף התגובה אמור להכיל תוצאה מוצלחת (למשל TripOptionsResult), ולא תגובה של שגיאה.
400 בקשה פגומה הבקשה שהתקבלה לא תקינה. צריך להשתמש בתשובות שגיאה ספציפיות לשיטה כדי להחזיר פרטים נוספים על השגיאה בגוף התשובה. בדרך כלל צריך להשתמש ב-HTTP 400 רק אם Google ביצעה שגיאה טכנית (למשל, שדה עם שם שגוי בבקשה).
403 אסור ההרשאה נדחתה או נאסרה (המתקשר מזוהה ונדחה). אין להשתמש בתגובה הזו לדחיות שנגרמות בגלל מיצוי של משאב מסוים (במקום זאת, צריך להשתמש בתגובה 'יותר מדי בקשות' לשגיאות האלה). ‫Forbidden אסור להשתמש אם לא ניתן לזהות את המתקשר (במקום זאת צריך להשתמש ב-Unauthorized בשביל השגיאות האלה).
404 לא נמצא לא נמצא המשאב המבוקש. צריך להשתמש בתגובות שגיאה ספציפיות לשיטה כדי להחזיר פרטים נוספים על השגיאה בגוף התגובה.
429 יותר מדי בקשות הגעתם למיצוי של משאב מסוים, אולי מכסת משאבים לכל משתמש.
500 שגיאת שרת פנימית שגיאות פנימיות. המשמעות היא שחלק מהתנאים הקבועים שהמערכת הבסיסית מצפה להם לא מתקיימים. קוד השגיאה הזה שמור לשגיאות חמורות ומציין באג בהטמעה של שרת ה-API של השותף.
503 השירות לא זמין השירות לא זמין. הסיבה היא כנראה מצב זמני שאפשר לתקן אותו באמצעות ניסיון חוזר עם השהיה.
504 הזמן הקצוב לתפוגת השער הסתיים המועד האחרון חלף לפני שהפעולה הסתיימה. בפעולות שמשנות את מצב המערכת, יכול להיות שהשגיאה הזו תוחזר גם אם הפעולה הושלמה בהצלחה. לדוגמה, יכול להיות שחל עיכוב בתגובה מוצלחת משרת, והמועד האחרון חלף.

הערה: לגבי כל התנאים המוקדמים, הארגומנטים הלא תקפים או השגיאות שלא נמצאו:

  • צריך להשתמש בתגובות או בהודעות השגיאה הספציפיות לשיטה שמוגדרות בממשקי ה-API.
  • צריך להשתמש בקוד ה-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 נסיעות.

QPS (שאילתות לשנייה)

סביר להניח שרמת השאילתות לשנייה שנשלחות על ידי Google תשתנה בהתאם למלאי שטחי הפרסום של השותף ולמספר המשתמשים שצופים בנתונים שבמטמון או לוחצים כדי לעבור לאתרים של השותפים כדי לבצע הזמנה.

זמן אחזור

הבקשות יפסיקו לפעול אחרי 10 שניות. לא יהיו הנחיות נוספות לגבי זמן אחזור בשילובים של שותפים בגרסת בטא. עם זאת, נגדיר עוד יעדי רמת שירות (SLO) בנוגע לזמן האחזור בהנחיות שלנו בנושא איכות נתונים לשותפים.

מטבעות, מיסים ועמלות

כל המחירים שנשלחים ל-Google צריכים לכלול את כל המיסים והעמלות, ולהיות מצוינים במטבע נתמך.

מטבע

המטבע של המחיר מצוין בשדה currency_code. בשדה הזה צריך להזין קוד מטבע חוקי לפי תקן ISO 4217.

דוגמה:10,25 USD

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

מיסים ועמלות

המחיר שאתם מציינים צריך להיות המחיר הסופי והכולל שהמשתמש ישלם, כולל כל המיסים (כמו מע"מ) וכל העמלות הנוספות (כמו עמלות הזמנה או עמלות על כרטיס תשלום). אפשר להוסיף פירוט אופציונלי של התעריף באמצעות השדה החוזר line_items. ‫Google תציג למשתמש את המחיר הכולל עם פירוט אופציונלי של המחיר.