Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CHM API extensions - due to Choice implementation #180

Merged
merged 11 commits into from
Jun 24, 2024
Merged

CHM API extensions - due to Choice implementation #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
fa91418
choice extensions
ondrahermanek May 13, 2024
cd024cf
CR
ondrahermanek May 15, 2024
5539623
Merge branch 'master' into choice-extensions
ondrahermanek Jun 11, 2024
2e8fc8c
Merge branch 'master' of github.com:MewsSystems/gitbook-channel-manag…
ondrahermanek Jun 18, 2024
570548c
CR
ondrahermanek Jun 18, 2024
a369ed4
cr
ondrahermanek Jun 20, 2024
c91f9c3
cr
ondrahermanek Jun 20, 2024
e60979d
cr
ondrahermanek Jun 20, 2024
0a5af61
Update reservations.md
MikeAdamsMews Jun 24, 2024
2449ff5
Update README.md
MikeAdamsMews Jun 24, 2024
a90b6cd
Update reservations.md
MikeAdamsMews Jun 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions changelog/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Changelog

## 24th June 2024

* [Availability block](/channel-manager-operations/availabilityBlock.md#availability-block) extended with `notes` field.
* [Loyalty info](/mews-operations/reservations.md#loyalty-info) extended with `tierCode` field.
* [Reservation](/mews-operations/reservations.md#reservation) extended with `timeState` field and [`paymentCardData`](/mews-operations/reservations.md#payment-card-data) object. Note these properties are only used by [CHM: Process group](/channel-manager-operations/reservations.md#process-group), _not_ by [Mews: Process group](/mews-operations/reservations.md#process-group).
* Correction: Minor corrections to examples in [CHM: Process group](/channel-manager-operations/reservations.md#process-group) and [Mews: Process group](/mews-operations/reservations.md#process-group).
* Correction: `paymentType` removed from Request in [CHM: Process group](/channel-manager-operations/reservations.md#process-group). This is only used on the Mews side.

## 16th May 2024

* Clarified [Synchronous error response](../guidelines/responses.md#synchronous-error-response)
Expand Down
4 changes: 3 additions & 1 deletion channel-manager-operations/availabilityBlock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,8 @@
"loyaltyCode": null,
"address": null
},
"company": null
"company": null,
"notes": "This is the block for Mews conference."
}
}
```
Expand All @@ -122,6 +123,7 @@
| `spaceCategories` | [`Space category allocation`](#space-category-allocation) collection | required | Allocated categories of the block. |
| `booker` | [`Customer`](../mews-operations/reservations.md#customer) object | required | The main booker. This does not mean that the person has arrived at the property. |
| `company` | [`Company`](../channel-manager-operations/reservations.md#company) object | optional | The company associated with the block. |
| `notes` | `string` | optional | Notes for the block. |

#### Dates

Expand Down
36 changes: 21 additions & 15 deletions channel-manager-operations/reservations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Process group

\[`async`\] This operation allows the Mews to push a group of reservations (bookings) to channel manager.
This option allows creations, modifications, and partial or complete cancellations. Confirmation is done asynchronous.
\[`async`\] This operation allows Mews to push a group of reservations or bookings to the Channel Manager.
The operation supports creations, modifications, and partial or complete cancellations. Confirmation is done asynchronously.

### Request

Expand All @@ -18,6 +18,8 @@ This option allows creations, modifications, and partial or complete cancellatio
"responseUrl": "https://api.mews-demo.com/api/channelManager/v1/processGroupConfirmation",
"channelId": "EXP-123456",
"channelManagerId": "123456",
"availabilityBlockCode": "Channel-manager-Wedding123",
"availabilityBlockConfirmationNumber": "Mews-Wedding123",
Comment on lines +21 to +22
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they are documented, were just not in the example

"comments": [
"Approximate arrival: 16:30.",
"Guest request a room with ocean view."
Expand All @@ -40,7 +42,13 @@ This option allows creations, modifications, and partial or complete cancellatio
"title": "Mister",
"nationalityCode": "US",
"languageCode": "en-US",
"telephone": "1-3526-88918"
"telephone": "1-3526-88918",
"loyaltyCode": "PG60972345",
"loyaltyInfo": {
"membershipId": "PG60972345",
"programCode": "BWR",
"tierCode": "Gold"
}
Comment on lines +46 to +51
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was added to wrong level. only for main customer (as documented)

},
"sources": [
{
Expand All @@ -54,7 +62,7 @@ This option allows creations, modifications, and partial or complete cancellatio
"name": "ChoiceCRS",
"type" : 0,
"isPrimary" false
},
}
],
"company": {
"id": "MEWS",
Expand Down Expand Up @@ -86,14 +94,6 @@ This option allows creations, modifications, and partial or complete cancellatio
}
}
},
"paymentCard": {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not sent here. Replaced with PaymentCardData on Reservation level

"cvv": "666",
"expireDate": "1222",
"holderName": "John Smith",
"number": "4111111111111111",
"type": 1
},
"paymentType": 1,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sent in res sync

"reservations": [
{
"guestCounts": [
Expand Down Expand Up @@ -135,8 +135,7 @@ This option allows creations, modifications, and partial or complete cancellatio
"title": "Misses",
"nationalityCode": "US",
"languageCode": "en-US",
"telephone": "1-369-81891",
"loyaltyCode": "PG60972345"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

incorrect placement, moved to main customer

"telephone": "1-369-81891"
}
],
"amounts": [
Expand Down Expand Up @@ -184,6 +183,7 @@ This option allows creations, modifications, and partial or complete cancellatio
"ratePlanCode": "NR",
"spaceTypeCode": "DBL",
"state": 2,
"timeState": 1,
"to": "2020-05-09",
"totalAmount": {
"net": 275.4,
Expand All @@ -203,6 +203,13 @@ This option allows creations, modifications, and partial or complete cancellatio
"spaceTypeCode": "DBL",
"state": 3,
"to": "2020-05-09"
},
"paymentCardData": {
"identifier": "12345678-1011-1213-1415-161718192021"
"expireDate": "1222",
"holderName": "John Smith",
"obfuscatedNumber": "41111*******1111",
"type": 1
}
],
"totalAmount": {
Expand All @@ -224,7 +231,6 @@ This option allows creations, modifications, and partial or complete cancellatio
| `availabilityBlockConfirmationNumber` | `string` | optional | Unique identification of the availability block in the Mews. |
| `currencyCode` | `string` | required \(exc. Cancellation\) | 3 letter code of currency of all prices within the booking. |
| `totalAmount` | [`Amount`](../mews-operations/reservations.md#amount) object | required \(exc. Cancellation\) | Total amount of the whole booking. |
| `paymentType` | `int` | required \(exc. Cancellation\) | [Payment Type](../mews-operations/configuration.md#payment-types) code - determines whether the booking is prepaid or not. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this field being deprecated? Or is there some reason we are not marking it as a deprecation?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is never passed, it was never used. It is used on the Mews side (it was copied here incorrectly).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't have been here in the first place, copy paste issue (same like the payment card above)

| `customer` | [`Customer`](../mews-operations/reservations.md#customer) object | required \(exc. Cancellation\) | Represents the main booker. Does not necessarily mean that the person arrives to the property. |
| `sources` | [`Source`](../mews-operations/reservations.md#source) collection | optional | Represents the sources for the booking. |
| `company` | [`Company`](../mews-operations/reservations.md#company) object | optional | Represents the company associated with the booking. |
Expand Down
55 changes: 40 additions & 15 deletions mews-operations/reservations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@
> * When **modifying** some reservations from a multi-reservation group, the whole group definition with all other unchanged reservations needs to be sent, i.e. Mews doesn't process diffs.
> * When **cancelling** a reservation from a multi-reservation group, all remaining reservations need to be present in the group definition as well.
> * There are two ways to cancel a reservation from a multi-reservation group:
> 1. If the `reservation.state` is set to [Reservation States](#reservation-states).`Cancelled`.
> 1. If the `reservation.state` is set to [Reservation State](#reservation-states) 'Canceled'.
> 2. If the reservation is not included in the group definition message.
> * When **cancelling** a whole group, the `reservations` collection can be empty of all reservations provided as cancelled \(as per case 1 above\).
> * When **cancelling** a whole group, the `reservations` collection can be empty of all reservations provided as canceled \(as per case 1 above\).

### Request

Expand All @@ -29,7 +29,7 @@

The example shows a valid group definition with two space reservations plus cancellation of a third space reservation.
The first `reservation` definition shows all details, the second `reservation` definition shows the minimal required details for creation / modification of a `reservation`.
The third `reservation` definition shows the partial cancellation - cancelling the third space reservation.
The third `reservation` definition shows the partial cancellation - canceling the third space reservation.

```javascript
{
Expand Down Expand Up @@ -61,7 +61,13 @@ The third `reservation` definition shows the partial cancellation - cancelling t
"title": "Mister",
"nationalityCode": "US",
"languageCode": "en-US",
"telephone": "1-3526-88918"
"telephone": "1-3526-88918",
"loyaltyCode": "PG60972345",
"loyaltyInfo": {
"membershipId": "PG60972345",
"programCode": "BWR",
"tierCode": "Gold"
}
Comment on lines +65 to +70
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here, example had it on incorrect place

},
"sources": [
{
Expand Down Expand Up @@ -156,12 +162,7 @@ The third `reservation` definition shows the partial cancellation - cancelling t
"title": "Misses",
"nationalityCode": "US",
"languageCode": "en-US",
"telephone": "1-369-81891",
"loyaltyCode": "PG60972345",
"loyaltyInfo": {
"membershipId": "PG60972345",
"programCode": "BWR"
}
"telephone": "1-369-81891"
}
],
"amounts": [
Expand Down Expand Up @@ -254,7 +255,7 @@ The third `reservation` definition shows the partial cancellation - cancelling t
| `sources` | [`Source`](#source) collection | optional | Represents the sources for the booking. |
| `company` | [`Company`](#company) object | optional | Represents the company associated with the booking. |
| `travelAgency` | [`Travel Agency`](#travel-agency) object | optional | Represents the travel agency associated with the booking. |
| `reservations` | [`Reservation`](#reservation) collection | optional | Each reservation within the booking. If the value is null or an empty collection, this implies that the whole group will be cancelled. |
| `reservations` | [`Reservation`](#reservation) collection | optional | Each reservation within the booking. If the value is null or an empty collection, this implies that the whole group will be canceled. |
| `comments` | `string` collection | optional | Represents any comments related to the booking. |

#### Customer
Expand All @@ -277,7 +278,8 @@ The third `reservation` definition shows the partial cancellation - cancelling t
| Property | Type | Contract | Description |
| :-- | :-- | :-- | :-- |
| `membershipId` | `string` | required | Loyalty membership identifier of the Customer. |
| `programCode` | `string` | required | Loyalty program code. |
| `programCode` | `string` | optional | Loyalty program code. |
| `tierCode` | `string` | optional | Loyalty tier code. |
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added 1 more field, present in the examples for both direction


#### Title

Expand Down Expand Up @@ -373,18 +375,30 @@ The third `reservation` definition shows the partial cancellation - cancelling t
| `from` | `string` | required \(exc. Cancellation\) | Start date in format `"yyyy-MM-dd"` \(e.g. `"2021-12-24"` for Christmas Eve\). |
| `to` | `string` | required \(exc. Cancellation\) | End date \(exclusive\) in format `"yyyy-MM-dd"` \(e.g. `"2021-12-31"` for New Year's Eve\). This is the date of resrvation departure. |
| `totalAmount` | [`Amount`](#amount) object | required \(exc. Cancellation\) | Total amount of the reservation. |
| ~~`adultCount`~~ | ~~`int`~~ | ~~required \(exc. Cancellation\)~~ | ~~Number of adults in the reservation.~~ **[Deprecated!](../deprecations/README.md)** |
| ~~`childCount`~~ | ~~`int`~~ | ~~optional \(exc. Cancellation\)~~ | ~~Number of children in the reservation.~~ **[Deprecated!](../deprecations/README.md)** |
Comment on lines -376 to -377
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this reservation object is shared with res sync from the CHM operations, I moved this to a specific section, as this is supported for only 1 direction (CHM -> Mews)

| `guestCounts` | array of [`Guest Count`](#guest-count) | required | Number of guests in the reservation for each age category. |
| `state` | `int` | optional | [Reservation State](#reservation-states) code of reservation state. _If not provided, Mews will handle the reservation as `Created` or `Modified`._ |
| `amounts` | [`Amount`](#amount) collection | required \(exc. Cancellation\) | Collection of amounts for each night of the reservation. _The count of amounts in this collection has to correspond with number of nights in the reservation._ |
| `extras` | [`Extra`](#extra) collection | optional | Collection of extra ordered products for the reservation \(e.g. Breakfast\). _Their total amount is included in the _`totalAmount`_ of the reservation._ |
| `guests` | [`Customer`](#customer) collection | optional | Collection of guests that will arrive to the property. |
| `timeState` | `int` | required (used only in [CHM: Process group](../channel-manager-operations/reservations.md#process-group) operation) | [Reservation Time State](#reservation-time-states) code of reservation state. |
| `paymentCardData` | [`Payment Card Data`](#payment-card-data) object | optional (used only in [CHM: Process group](../channel-manager-operations/reservations.md#process-group) operation) | Represents the payment card of the [`Customer`](#customer) to cover for the booking. It doesn't contain the acutal card number. |
| ~~`adultCount`~~ | ~~`int`~~ | ~~required \(exc. Cancellation\)~~ | ~~Number of adults in the reservation.~~ **[Deprecated!](../deprecations/README.md)** |
| ~~`childCount`~~ | ~~`int`~~ | ~~optional \(exc. Cancellation\)~~ | ~~Number of children in the reservation.~~ **[Deprecated!](../deprecations/README.md)** |

> **Codes:** It is required that `code` remains the same within each booking modification message and partial modification message. If this can't be achieved because the channel doesn't provide it, simple generation of codes "01", "02", ... will suffice as long as those codes are generated in the same way for each message regarding that one booking.

> **From/To:** This represents the reservation arrival, `from` is arrival date, `to` is departure date. So reservation for 2 nights (e.g. 2021-12-24/25 and 2021-12-25/26 is represented as `"from": "2021-12-24", "to": "2021-12-26"`).

#### Payment Card Data

| Property | Type | Contract | Description |
| :-- | :-- | :-- | :-- |
| `type` | `int` | required | [Payment Card Type](#payment-card-types) code. |
| `obfuscatedNumber` | `string` | required | Obfuscated payment card number. |
| `expireDate` | `string` | required | Expiration date of card in `"MMyy"` format \(e.g `"0222"` for February 2022 expiration\). |
| `identifier` | `string` | required | Mews identifier of the payment card.|
| `holderName` | `string` | optional | Card holder name. |

#### Guest Count

| Property | Type | Contract | Description |
Expand All @@ -406,7 +420,18 @@ The third `reservation` definition shows the partial cancellation - cancelling t
| :-- | :-- |
| `1` | Created |
| `2` | Modified |
| `3` | Cancelled |
| `3` | Canceled |

#### Reservation Time States

| Code | Description |
| :-- | :-- |
| `0` | Optional - any tentative reservation that has not been confirmed yet. By default Mews does not synchronize such reservations to Channel Managers. |
| `1` | Confirmed - reservation with arrival date in the future. |
| `2` | CheckedIn - reservation that is currently checked-in. |
| `3` | CheckedOut - reservation that is already checked out (i.e. past reservation) |
| `4` | Canceled - reservation that is canceled. |
| `5` | NoShow - reservation that is canceled with `NoShow` reason. |

#### Extra

Expand Down