# 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>