保留和復原

快速預訂 API 的暫停與恢復功能，讓您能夠支援兩步驟預訂模式。

使用雙步驟預訂模式時，合作夥伴或旅客可先暫停一間客房的預訂而無須立即付費，且若其取消或放棄客房而未完成預訂，也不會產生任何取消罰款。

若旅客或合作夥伴想要在指定期限內確認客房，可以在第二個步驟完成預訂。若放棄預訂，系統會復原預訂狀態，選擇的空房也會釋出。

簡介

預訂申請可轉移到 `hold`狀態，再透過回應中的連結轉移到 `retrieve`、 `resume`，或 `cancel` 狀態。

需進行哪些變更？

「暫停與繼續處理」在回應中使用現有的 API，以及新的要求標記與記號化連結。不需新的個別 API 方法即可整合。若要整合「暫停與繼續處理」，您必須針對以下項目更新要求和/或回應處理：

建立預訂處理。
預訂擷取處理。
繼續處理 -「擷取」回應中的新記號化連結處理。
取消 -「建立」回應中的新記號化連結處理。

請仔細檢閱本頁面，再閱讀我們的各項 API 整合文件，有助於了解完整的「暫停與繼續處理」程序。本頁記載的特定選項，亦可於下列專用文件頁面中查閱：現有 API 介面：Booking Manage Booking

可持有的旗幟

並非所有利率都能維持不變。快速商店回應中的可保留標記，用以指示特定費率是否符合保留與恢復的資格。為使「可持有」標記在快速商店回應中顯示，合作夥伴必須在請求中包含include=rooms.rates.holdable。

建立暫停預訂

預訂要求現在新增了一個名稱為 hold 的布林值欄位。若傳送 true 值，會使旅宿狀態變成暫停。

暫停的預訂應僅在特定應用程式要求的最短時間內，維持暫停狀態。若預訂未經確認即處於暫停狀態，該狀態將自動復原。

若暫停預訂回應成功，系統會再多傳回一個用於繼續處理 (確認並付款) 暫停預訂的記號化連結。由於尚無任何要取消的客房，因此該回應也會忽略平時用於提供取消連結的 rooms 陣列。

on-hold 預訂的範例回覆

{
    "itinerary_id": "2667552437552",
    "links": [
        {
            "rel": "retrieve",
            "method": "GET",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "resume",
            "method": "PUT",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        },
        {
            "rel": "cancel",
            "method": "DELETE",
            "href": "/v3/itinerary/{itinerary_id}?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
        }
    ]
}

若使用 hold 標記進行預訂，我們將不會收取任何預訂付款費用。只有在暫停期間於暫停預訂回應中加入 PUT 方法連結，系統才會完成預訂並收取付款。

擷取暫停預訂

使用暫停預訂回應中提供的 retrieve 連結，便可擷取暫停預訂。在管理預約 API () 中，檢索暫停與恢復預約的方法與單步驟預約的常規檢索無異，且無需請求本體。

回應案例：

擷取仍為暫停狀態的暫停預訂，會傳回具備有限資料的回應，這些資料包括可立即繼續處理及完成或取消預訂的連結。
擷取已取消 (已依要求復原) 或逾時 (已自動復原) 的暫停預訂，會傳回 “itinerary not found” (找不到行程) 的錯誤訊息。
檢索已先前恢復並確認的 on-hold 預訂 ()，其運作方式將與管理預訂 API 中的標準行程檢索相同 ()，並將返回完整的預訂詳情。

on-hold 預訂的範例檢索

{
    "itinerary_id": "8701934321257",
    "creation_date_time": "2018-03-09T14:42:58.159Z",
    "links": {
        "resume": {
            "method": "PUT",
            "href": "/v3/itineraries/8701934321257?token=QldfCGlcUA…{example trimmed for length}="
        },
        "cancel": {
            "method": "DELETE",
            "href": "/v3/itineraries/9700934721257?token=QldfCGlcUA…{example trimmed for length}="
        }
    }
}

針對已取消或超時的 on-hold 預訂之範例檢索回應

{
    "type": "resource_not_found",
    "message": "Itinerary was not found with provided request."
}

繼續處理暫停預訂

若要確認狀態已設為暫停的預訂並完成付款，則必須繼續處理預訂。

使用原始暫停預訂回應中提供的 resume 連結，便可繼續處理已執行的暫停預訂，且無需要求的本文。

回應案例：

繼續處理仍為暫停狀態的暫停預訂可完成預訂，並傳回表示順利完成的 HTTP 204 - 無內容回應。使用初始暫停預訂回應中的 GET 連結，可擷取完整行程。
擷取已取消 (已依要求復原) 或逾時 (已自動復原) 的暫停預訂，會傳回先前擷取章節取所述的同一個 “itinerary not found” (找不到行程) 錯誤訊息。
若繼續處理已成功繼續處理的暫停預訂，系統便會傳回表示預訂已確認的錯誤訊息。

已繼續處理的預訂繼續處理回應範例

{
    "type": "resume.already_resumed",
    "message": "Booking has already been resumed."
}

取消暫停預訂 (復原)

預訂建立和擷取回應中提供的 cancel 記號化連結，會在行程層級運作。使用此連結，會將要求的旅宿解除暫停狀態，並復原暫停的行程。系統只會在成功繼續處理預訂後，才會於「擷取」回應中提供客房層級取消連結。

若執行 cancel 操作，系統也會傳回 HTTP 204 狀態碼，與成功繼續處理回應傳回的相同。兩個狀態都使用 HTTP 204 訊息表示伺服器已成功履行要求，且不需在回應承載本文傳送其他內容。

要求取消暫停的預訂會導致最終情況相同，就如同系統已允許自動復原預訂一樣。

回應案例：

取消仍為暫停狀態的暫停預訂，會將可訂空房解除暫停狀態並傳回 HTTP 204 狀態。
取消已取消 (已依要求復原) 或逾時 (已自動復原) 的暫停預訂，將會傳回本頁面前段所述的 “itinerary not found” (找不到行程) 錯誤訊息。
取消已成功繼續處理的暫停預訂，會傳回 itinerary level cancel not supported (不支援在行程層級取消) 錯誤訊息。發出「擷取」呼叫並使用回應中提供的客房層級連結，可取消個別客房。

已繼續處理的預訂取消回應範例

{
    "type": "resume.itinerary_level_cancel_not_supported",
    "message": "Itinerary level cancel on confirmed booking is not supported."
}