合作夥伴伺服器

如要整合價格和供應情形資訊，合作夥伴必須實作 Partner API。這個介面以 REST 為基礎，可讓 Google 透過 HTTP 傳送即時通話。個別 API 方法的詳細資料請參閱「參考資料」一節，而跨領域問題的相關資訊則請見後續章節。

要求和回應格式

一開始只支援 JSON 格式，如需其他要求或回應格式，請傳送電子郵件至 [e-mail] 與 Travel Transport 團隊聯絡，討論您的用途。

系統會使用 HTTP 方法 POST 傳送要求，並將要求訊息放在 POST 主體中。

請注意，為清楚說明結構，API 介面說明文件是以通訊協定緩衝區訊息定義的形式提供，而通訊協定緩衝區訊息定義到 JSON 物件的轉換，則是由標準 JSON 對應定義，並使用選項發出含有預設值的欄位，以及使用通訊協定欄位名稱而非 lowerCamelCase 名稱。

重要事項： 建議使用通訊協定緩衝區程式庫和隨附的 JsonFormat 公用程式，確保 API 類型安全，並產生語法正確的回應。說明文件中顯示的列舉定義不包含 UNSPECIFIED 值。直接使用 Protobuf 時，應新增這些項目。

驗證

Google 支援 HTTP 摘要驗證、OAuth 2.0 和用戶端憑證驗證 (請參閱「合作夥伴設定」)。合作夥伴應在 API 測試期間向 Google 提供正確的憑證：

• 摘要：使用者名稱和密碼。
• OAuth 2.0：client_id 和 client_secret。
• 憑證：SSL 用戶端憑證。

狀態碼和錯誤處理

一般來說，HTTP 回應中可能會傳回下列狀態碼：

HTTP 代碼	HTTP 說明	附註
2xx	確定	非錯誤；於成功時傳回。回應內容應包含成功結果 (例如 TripOptionsResult)，而非錯誤回應。
400	要求無效	收到的要求無效。方法專屬的錯誤回應 應在回應主體中傳回其他錯誤詳細資料。 一般來說，只有在 Google 發生技術錯誤 (例如要求中的欄位名稱有誤) 時，才應使用 HTTP 400。
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 Travel Transport 團隊聯絡。

QPS (每秒查詢次數)

Google 傳送的每秒查詢數層級可能會因合作夥伴的目錄和使用者人數而異，這些使用者會查看快取資料或點選連結前往合作夥伴網站進行預訂。

延遲時間

要求會在 10 秒後逾時。Beta 版合作夥伴整合服務不會有額外的延遲時間規範。不過，合作夥伴資料品質指南中會定義進一步的延遲 SLO。

貨幣、稅金和手續費

傳送給 Google 的所有價格都必須包含所有稅金及費用，並以支援的幣別指定。

幣別

價格的幣別是使用 currency_code 欄位指定，且必須是有效的 ISO 4217 幣別代碼。

範例：10.25 美元：

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

稅金和費用

你提供的價格必須是使用者最終支付的總價，包含所有稅金 (例如加值稅) 和任何額外費用 (例如預訂或信用卡費用)。您可以使用可重複的 line_items 欄位，視需要新增車資明細。Google 會向使用者顯示總價，並提供票價明細 (選填)。