# Cancellation API

## Document Hotel API Cancellation <a href="#document-hotel-api-cancellation" id="document-hotel-api-cancellation"></a>

![Luồng huỷ phòng khách sạn](https://developer.gotadi.com/img/cancellation-process.png)

### Mô tả hình thức phạt khi huỷ <a href="#mo-ta-hinh-thuc-phat-khi-huy" id="mo-ta-hinh-thuc-phat-khi-huy"></a>

Nếu không nhận phòng, hoặc nếu hủy hay thay đổi đặt phòng này sau thời gian nhận phòng, thì bạn có thể phải chịu phí phạt lên đến `100%` giá trị đặt phòng.

#### Các hình thức phạt <a href="#cac-hinh-thuc-phat" id="cac-hinh-thuc-phat"></a>

**Ví dụ 1: Phạt theo đêm**

```json
[{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "NIGHTS",
    "currency": "VND",  
    "percent": "",  
    "nights": "1.0",
    "amount": "",
    "description": ""
}]
```

* Được hủy miễn phí đến trước ngày `2021-05-12T18:00:00.000+07:00`
* Phạt `1` đêm khi hủy phòng từ ngày `2021-05-12T18:00:00.000+07:00` đến ngày `2021-05-13T18:00:00.000+07:00`

**Ví dụ 2: Phạt theo giá tiền**

```json
[{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "AMOUNT",
    "currency": "VND",
    "percent": "",
    "nights": "",
    "amount": "200000",
    "description": ""
}]
```

* Được hủy miễn phí đến trước ngày `2021-05-12T18:00:00.000+07:00`
* Bị Phạt `200000` `VND` khi hủy phòng từ ngày `2021-05-12T18:00:00.000+07:00` đến ngày `2021-05-13T18:00:00.000+07:00`

**Ví dụ 3: Phạt theo phần trăm**

```json
[{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "70%",
    "nights": "",
    "amount": "",
    "description": ""
}]
```

* Được hủy miễn phí đến trước ngày `2021-05-12T18:00:00.000+07:00`
* Bị Phạt `70%` giá trị của phòng khi hủy phòng từ ngày `2021-05-12T18:00:00.000+07:00` đến ngày `2021-05-13T18:00:00.000+07:00`

**Ví dụ 4: Nhiều hình phạt**

```json
[{
    "startDate": "2021-05-10T18:00:00.000+07:00",
    "endDate": "2021-05-12T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "50%",
    "nights": "",
    "amount": "",
    "description": ""
},
{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "70%",
    "nights": "",
    "amount": "",
    "description": ""
}]
```

* Được hủy miễn phí đến trước ngày `2021-05-10T18:00:00.000+07:00`
* Bị Phạt `50%` giá trị của phòng khi hủy phòng từ ngày `2021-05-10T18:00:00.000+07:00` đến ngày `2021-05-12T18:00:00.000+07:00`
* Bị Phạt `70%` giá trị của phòng khi hủy phòng từ ngày `2021-05-12T18:00:00.000+07:00` đến ngày `2021-05-13T18:00:00.000+07:00`

**Ví dụ 5: Nhiều hình phạt**

```json
[{
    "startDate": "2021-05-10T18:00:00.000+07:00",
    "endDate": "2021-05-12T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "50%",
    "nights": "",
    "amount": "25000",
    "description": ""
}]
```

* Được hủy miễn phí đến trước ngày `2021-05-10T18:00:00.000+07:00`
* Bị Phạt `50%` giá trị của phòng khi hủy phòng từ ngày `2021-05-10T18:00:00.000+07:00` đến ngày `2021-05-12T18:00:00.000+07:00` kèm theo khoản phí
* Bị phạt `25000` `VND` tiền phí khi hủy phòng từ ngày `2021-05-10T18:00:00.000+07:00` đến ngày `2021-05-12T18:00:00.000+07:00`

**Ví dụ 6: Hủy miễn phí**

```json
[{
    "startDate": "2021-05-01T18:00:00.000+07:00",
    "endDate": "2021-05-12T18:00:00.000+07:00",
    "type": "NIGHTS",
    "currency": "VND",
    "percent": "",
    "nights": "0",
    "amount": "",
    "description": ""
}]
```

* Được hủy miễn phí đến trước ngày `2021-05-12T18:00:00.000+07:00`

***

### 1. API Kiểm tra khả năng huỷ phòng và phí phạt <a href="#id-1-api-kiem-tra-kha-nang-huy-phong-va-phi-phat" id="id-1-api-kiem-tra-kha-nang-huy-phong-va-phi-phat"></a>

POST: /api/v3/hotel/check-cancel-penalty

Trả về thông tin trạng thái khả năng huỷ phòng, và thông tin phí phạt khi huỷ.

#### Request Body <a href="#request-body" id="request-body"></a>

Model

<details>

<summary>Request Body</summary>

* bookingNumber (String, Required)

  Mã dùng tham chiếu đến booking. Mã này là duy nhất.

</details>

Example

#### Response <a href="#response" id="response"></a>

**Code 200**

> OK

<details>

<summary>Model</summary>

* result (CheckCancelPenaltyResult, Optional)

  Thông tin kết quả trả về

  * status (string, optional) = \[‘ALLOW\_CANCELLATION’, ‘NOT\_ALLOW\_CANCELLATION’, ‘UNKNOWN’]

    Thông tin xác định trạng thái huỷ phòng

    * `ALLOW_CANCELLATION`: Chấp nhận huỷ phòng
    * `NOT_ALLOW_CANCELLATION`: Không chấp nhận huỷ phòng
    * `UNKNOWN`: Không xác định trạng thái, cần được xác định lại
  * cancelPenalties (Array\[CancelPenalty], optional),

    Thông tin phí phạt khi huỷ phòng. [Xem mô tả thêm ở đây](https://developer.gotadi.com/dev-guide/api-hotel/api-cancellation/#cac-hinh-thuc-phat)
  * cancelPenaltyTotal (number, optional),

    Thông tin phí phạt khi huỷ phòng
* duration (Integer, Optional)
* success (Integer, Bool)
* infos (Array\[InfosDTO], Optional)
* errors (Array\[ErrorsDTO], Optional)
* textMessage (String, Optional)

</details>

***

### 2. API yêu cầu huỷ booking hotel <a href="#id-2-api-yeu-cau-huy-booking-hotel" id="id-2-api-yeu-cau-huy-booking-hotel"></a>

POST: /api/partner/cancellation

API gửi yêu cầu huỷ booking đợi trả lời từ nhà cung cấp

Chú ý

Yêu cầu bảo mật: Mã hóa dữ liệu và kèm theo chữ ký điện tử

* Request: Không yêu cầu phải được mã hóa và kèm theo chữ ký điện tử
* Response: Một phần dữ liệu của response được yêu cầu phải mã hóa và kèm theo chữ ký điện tử

#### Request Body <a href="#request-body_1" id="request-body_1"></a>

<details>

<summary>Model</summary>

* key (string, required),

  Key giải mã dữ liệu (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)
* data (string, required),

  Dữ liệu kèm theo chữ ký điện tử (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)

  *Signature data schema:*

  ```
  <access_code>|<booking_number>|<cancel_penalty_amount>
  ```

  *Original data schema:*

  ```
  <access_code>|<booking_number>|<cancel_penalty_amount>|<signature>
  ```

  * access\_code (String, required)

    Access code do Gotadi cung cấp cho Đối tác.
  * bookingNumber (String, required)

    Mã dùng tham chiếu đến booking
  * cancel\_penalty\_amount (String, optional)

    Số tiền phí phạt. Được định dạng 2 chữ số thập phân `0.00`

</details>

#### Response <a href="#response_1" id="response_1"></a>

**Code 200**

> OK

<details>

<summary>Model</summary>

* key (String, required)

  Key giải mã dữ liệu (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)
* data (String, required)

  Dữ liệu kèm theo chữ ký điện tử (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)

  *Signature data schema:*

  ```
  <access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>
  ```

  *Original data schema:*

  ```
  <access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>|<signature>
  ```

  * access\_code (String, required)

    Access code do Gotadi cung cấp cho Đối tác.
  * booking\_number (String, required)

    Mã dùng tham chiếu đến booking
  * error\_code (String, required)

    [Mã lỗi](https://developer.gotadi.com/dev-guide/#7-ma-loi)
  * product\_type (String, optional)

    Loại sản phẩm, có giá trị là `AIR` hoặc `HOTEL` tương ứng với loại sản phẩm được mua
  * cancellation\_status (String, optional)

    Thông tin trạng thái huỷ:

    * `CANCEL_UNKNOWN` Trạng thái không xác định, cần kiểm tra lại.
    * `CANCEL_PENALTY_MISMATCH` Phí phạt không khớp. Cần gọi lại [API Kiểm tra khả năng huỷ phòng và phí phạt](https://developer.gotadi.com/dev-guide/api-hotel/api-cancellation/#1-api-kiem-tra-kha-nang-huy-phong-va-phi-phat) để lấy thông tin phí phạt sau đó gủi lại yêu cầu huỷ phòng
    * `CANCEL_WAITING_CONFIRM` Gửi yêu cầu huỷ thành công, đợi nhà cung cấp xác nhận
    * `CANCEL_CONFIRMED` Huỷ thành công
    * `CANCEL_EXPIRED` Yêu cầu huỷ quá hạn

</details>

### 3. API Kiểm tra trạng thái huỷ phòng <a href="#id-3-api-kiem-tra-trang-thai-huy-phong" id="id-3-api-kiem-tra-trang-thai-huy-phong"></a>

POST: /api/partner/cancellation-check

API kiểm tra trạng thái huỷ phòng

Chú ý

Yêu cầu bảo mật: Mã hóa dữ liệu và kèm theo chữ ký điện tử

* Request: Không yêu cầu phải được mã hóa và kèm theo chữ ký điện tử
* Response: Một phần dữ liệu của response được yêu cầu phải mã hóa và kèm theo chữ ký điện tử

#### Request Body <a href="#request-body_2" id="request-body_2"></a>

<details>

<summary>Model</summary>

* key (string, required),

  Key giải mã dữ liệu (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)
* data (string, required),

  Dữ liệu kèm theo chữ ký điện tử (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)

  *Signature data schema:*

  ```
  <access_code>|<booking_number>>
  ```

  *Original data schema:*

  ```
  <access_code>|<booking_number>|<signature>
  ```

  * access\_code (String, required)

    Access code do Gotadi cung cấp cho Đối tác.
  * bookingNumber (String, required)

    Mã dùng tham chiếu đến booking

</details>

#### Response <a href="#response_2" id="response_2"></a>

**Code 200**

> OK

<details>

<summary>Model</summary>

* key (String, required)

  Key giải mã dữ liệu (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)
* data (String, required)

  Dữ liệu kèm theo chữ ký điện tử (đã được mã hóa). [Tham khảo thêm tại đây](https://developer.gotadi.com/dev-guide/#3-ma-hoa-du-lieu-truyen-va-xac-thuc-chu-ky-ien-tu)

  *Signature data schema:*

  ```
  <access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>|<cancel_penalty_amount>
  ```

  *Original data schema:*

  ```
  <access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>|<cancellation_feee>|<signature>
  ```

  * access\_code (String, required)

    Access code do Gotadi cung cấp cho Đối tác.
  * booking\_number (String, required)

    Mã dùng tham chiếu đến booking
  * error\_code (String, required)

    [Mã lỗi](https://developer.gotadi.com/dev-guide/#7-ma-loi)
  * product\_type (String, optional)

    Loại sản phẩm, có giá trị là `AIR` hoặc `HOTEL` tương ứng với loại sản phẩm được mua
  * cancellation\_status (String, optional)

    Thông tin trạng thái huỷ:

    * `CANCEL_UNKNOWN` Trạng thái không xác định, cần kiểm tra lại.
    * `CANCEL_PENALTY_MISMATCH` Phí phạt không khớp. Cần gọi lại [API Kiểm tra khả năng huỷ phòng và phí phạt](https://developer.gotadi.com/dev-guide/api-hotel/api-cancellation/#1-api-kiem-tra-kha-nang-huy-phong-va-phi-phat) để lấy thông tin phí phạt sau đó gủi lại yêu cầu huỷ phòng
    * `CANCEL_WAITING_CONFIRM` Gửi yêu cầu huỷ thành công, đợi nhà cung cấp xác nhận
    * `CANCEL_CONFIRMED` Huỷ thành công
    * `CANCEL_EXPIRED` Yêu cầu huỷ quá hạn
  * product\_type (String, optional)

    Số tiền phí huỷ. Được định dạng 2 chữ số thập phân `0.00`

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gotadi.com/vietnamese/doi-tac-b2b2c/phuong-thuc-api/hotel/cancellation-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.