שרת של שותף

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

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

בתחילה תהיה תמיכה רק בפורמטים של JSON. אם נדרשים פורמטים נוספים של בקשות או תגובות, אפשר לפנות לצוות Travel Transport בכתובת [e-mail] כדי לדון בתרחיש השימוש שלכם.

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

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

חשוב: מומלץ להשתמש בספריות של מאגר אחסון לפרוטוקולים ובכלי השירות הכלולים של JsonFormat של ממשקי API שמונעים שגיאות הקלדה, וכך מובטח שהתגובות שייווצרו יהיו בתחביר תקין. הגדרות ה-enum שמוצגות במסמכי התיעוד לא כוללות את הערך UNSPECIFIED. צריך להוסיף אותם כשמשתמשים ישירות ב-protobufs.

אימות

‫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 נסיעות Transport.

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

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

זמן אחזור

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

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

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

מטבע

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

דוגמה:10.25 USD

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

מיסים ועמלות

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