通知

本頁面概述傳送預訂活動警示的「通知服務」。

簡介

「Rapid API 通知」解決方案可讓您更緊密地與 Rapid 整合。若發生可能影響您業務的變更，Rapid 會利用標準 POST 訊息，直接將變更詳細資料推播至您的系統。推播通知可讓您隨時接收最新資訊、簡化操作以及調整業務範圍。

我們目前支援在 API 外部發生的所有預訂活動通知。因此，若客戶服務中心發生變更或飯店取消預訂，您便會立即收到通知。這只是開始，很快地我們會支援更多通知活動類型。

這些通知功能與您的業務無縫整合後，可強化下列 Rapid 產品與服務：

• Rapid
• Affiliate Voyager 服務專員預訂工具
• 合作夥伴與客戶服務

我們現在為全部「通知」支援的活動類型提供「測試 API」。請查看下方的下一個主要區段瞭解詳細資訊。若您想要設定自己的要求，也可以使用我們全新的「通知測試」工具。

支援的訊息類型

「Rapid 通知」可將下列活動的通知訊息傳送到您的系統：

訊息結構描述與詳細資料

全部訊息皆採用下方概述的結構描述。系統會針對不同活動新增訊息類型，因此結構描述可能有異。

每則訊息皆為訊息內文為 JSON 格式的 HTTPS POST 要求。

請注意：合作夥伴必須個別啟動每種活動類型，才能收到通知。如果您想啟動新的「通知 API」活動類型，請聯絡 Rapid 支援。

itinerary.agent.create 範例

{
     "event_id": "dbacce6c-afcb-4b23-ae66-48050757551c",
     "event_type": "itinerary.agent.create",
     "event_time": "2017-08-09T16:47:32.039Z",
     "itinerary_id": "8091234567890",
     "email": "customer@example.com",
     "message": "An agent created a new itinerary.",
     "affiliate_reference_id": "b086d299-2f1f-4134-a23c-f4a1c9286fac"
 }

itinerary.supplier.confirm 範例

{
    "event_id": "e02d6f41-4708-476f-915d-8a7032942e94",
    "event_type": "itinerary.supplier.confirm",
    "event_time": "2018-04-28T20:31:03.423Z",
    "itinerary_id": "8999989898988",
    "email": "alice@example.com",
    "message": "The supplier confirmed one or more rooms on this itinerary.",
    "affiliate_reference_id": "R194193582",
    "rooms": [
        {
            "confirmation_id": {
                "expedia": "926784314",
                "property": "BEF23123AA"
            }
        },
        {
            "confirmation_id": {
                "expedia": "926784315"
            }
        }
    ]
}

itinerary.message.received 範例

{
  "event_id": "1aed5641-7285-4c42-b079-f5f2f139d148",
  "event_type": "itinerary.message.received",
  "event_time": "2023-11-14T02:33:18.860105363Z",
  "itinerary_id": "9025254271673",
  "email": "john@email.com",
  "message": "We accept your request for river view room. Looking forward to your visit",
  "affiliate_reference_id": "b086d299-2f1f-4134-a23c-f4a1c9286fac"
}

整合

接收訊息

若要開始接收通知，您必須支援的端點需能夠接受推播至您端點的 POST 訊息。此端點必須能夠：

• 可公開存取。
• 啟用 HTTPS 和 TLS 1.2 或更高版本。
• 安裝受大多現代化應用程式信任的 TLS 有效憑證 (自簽署的憑證恐將不受信任)。

與 Rapid 整合顧問一起完成設定，並提供以下資訊給對方：

• 您想訂閱的活動類型清單 (如上所列)。
• 處理訊息之端點的 URL。

我們正在努力研發可測試整合的自助工具。在那之前，整合顧問可協助您進行預訂測試，以確認您能夠收到您所訂閱之離線活動的通知。

重要設定備註

• Rapid 使用雲端伺服器：務必將接聽程式端點設為接收各個可能 IP 位址發出的推播通知。
• 若要變更端點 URL，則在我們驗證您的新 URL 之前，請務必讓原始 URL 維持上線狀態，以接收推播通知。進行上述變更前，請先聯絡您的 Rapid 服務專員。
• 您只能使用一個 URL 接收通知：不支援 event_type 的變體或其他條件。

處理訊息

您接收預訂活動已發生的訊息時，請使用該訊息中的行程 ID 和電子郵件地址來取回最新的預訂詳細資料。

訊息可能不會依序送達。請參閱時間戳記以判斷順序，並取回預訂活動行程以取得更新狀態。

收到訊息後，您的整合作業必須以正確的 HTTP 狀態碼回應。通知服務會將所有未收到 200 級狀態碼的訊息，視為未傳遞且會排入重試佇列。

無法傳遞的訊息

若無法將訊息成功傳遞至您的端點，則我們會依照以下排程自動重試：

• 5 分鐘後進行第一次重試。
• 1 小時過後進行第二次重試。
• 7 天內每 12 小時執行後續重試 (共 14 次)。

若我們未收到收取確認 (200 OK 狀態碼)，且訊息已排入重試佇列，則您可能會收到重覆的訊息。尋找具有相同 event_id，但 timestamp 比原始訊息晚的訊息，即可找出重覆的訊息。

無法傳送通知 API

此要求會為您的訂閱和測試端點把無法傳送的通知回傳。訊息會根據所提供的 API 金鑰回傳。在 7 天連續嘗試傳送訊息未果後 (請參閱前面章節)，系統就會將之認定為無法傳送訊息，並轉移到儲存器供日後取回。

• 無法傳送訊息只會回傳一次。依您要求回傳的訊息將會從資料儲存庫移除。請以此原則為此 API 安排您的回應處理。
• 每次要求可回傳至多 25 則無法傳送訊息。
• 向 api.ean.com 傳送的要求，將可在同一回應中同時收到測試環境和生產環境的通知。傳送到我們的測試端點 (即 test.ean.com) 的要求，目前還無法正式支援。建議您在正式生產端點上線後，就不要再使用測試端點，因為這麼做會導致實際通知被回傳然後刪除。

訊息結構描述與詳細資料

此 API 回傳的無法傳送訊息係遵循和實際生產通知相同的結構描述 (請參見上一段落的說明)。

範例：2 則無法傳送訊息

[
    {
        "event_id": "e02d6f41-4708-476f-915d-8a7032942e94",
        "event_type": "itinerary.agent.change",
        "event_time": "2018-04-28T20:31:03.423Z",
        "itinerary_id": "1204309424793",
        "email": "alice@example.com",
        "message": "An agent changed this itinerary.",
        "affiliate_reference_id": "R194193582"
    },
    {
        "event_id": "fe97op1b-595a-406e-8e0e-90108d5cb4a1",
        "event_type": "itinerary.agent.cancel",
        "event_time": "2018-05-24T04:08:50.839Z",
        "itinerary_id": "1204329124126",
        "email": "bob@sample.net",
        "message": "An agent canceled one or more rooms on this itinerary.",
        "affiliate_reference_id": ""
    }
]

通知測試 API

「Rapid 通知測試 API」能讓您要求傳送測試通知至您指定的測試端點，以驗證您的通知服務整合成果。您也可以使用我們的「通知服務測試」(Notifications Service Tester) 直接將測試通知傳送至您的端點，而無需自行提出要求。

重要注意事項

此服務的要求功能不支援產品通知 API，您無法傳送要求至即時端點，以觸發或重新整理產品通知。透過此測試 API 提出的請求僅能用於測試用途。

由於此 API 僅用於測試用途，其 POST 要求的觸發程序僅在 test.ean.com 上有效。

訊息結構描述與支援訊息類型

所有測試通知均遵守與產品通知相同的結構描述和同樣的訊息類型，如同在此區段前提供的通知 API 文件所列。

整合

接收訊息

若要開始接收測試通知，您必須支援可公開存取的 HTTPS 端點，該端點需能夠接受推播至您端點的 POST 訊息。

與 Rapid 整合顧問一起完成設定，並提供以下資訊給對方：

• 您想訂閱的測試活動類型清單 (如前一個區段所列)。
• 處理測試通知之測試端點的 URL。

若您在提出要求的 30 分鐘後無法收到測試通知，請聯絡您的 Rapid 整合顧問，協助您解決問題。

重要注意事項

重要注意事項

• 在您收到的通知中，測試通知和實際環境通知不會有任何差別。我們強烈建議您為測試通知設定指定的端點，以正確分別測試與實際環境訊息。
• 為測試與實際環境設定不同端點時，您在測試端點只會收到測試通知，而同樣地，在實際環境端點也只會收到實際環境通知。

為測試與產品設定不同端點時，您在測試端點只會收到測試通知，而同樣地，在產品端點也只會收到產品通知。

驗證通知

為驗證通知是否來自 Rapid，我們會寄出要求標頭來驗證該項活動。

當 Rapid 發送通知時，您會收到一個授權標頭，就和您用 API 傳送要求時的授權標頭相同。

Rapid 將以下列格式發送授權標頭：

Authorization: EAN
APIKey=yourAPIKey,Signature=sha512Hash,timestamp=UNIXTimestampUsedForTheSignature

驗證

驗證若要驗證活動，請將標頭中的 signature SHA512 hash 與要求標頭中您使用 API 金鑰、共用密碼和時間戳記自行產生的內容進行比對。

請參閱我們的簽章驗證資料頁面以進一步了解如何建構散列。

重要注意事項

API 詳細資料

在這個頁面上探索通知相關端點的定義，然後使用 API Explorer 或其他測試軟體，了解範例和結構描述定義與實際輸出的比較。

其他資源

無論您是想嘗試所有 Rapid API 端點，還是下載其 OpenAPI 規格或我們的 Postman Collection，我們都可協助您完成。

前往 API Explorer