Channel Manager API
1. Introduction
The Channel Management Systems linked to the Internet booking systems can be interface with WINCLOUD to receive bookings in WINCLOUD and to distribute rates and inventory across third party websites linked to the Channel Managers.
The document provides the specification of the interface application. The Channel Manager applications can use the below specification to integrate with WINCLOUD to push reservations to WINCLOUD and receive inventory and rate updates from WINCLOUD.
2. Definitions & Acronyms
WINCLOUD | PMS provided by Winsar |
PMS | Property Management System |
OTA | Online Travel Agent (Travel Website) |
ARI | Availability, Rates and Inventory |
3. Interface Description
The WINCLOUD interface application includes a web interface for mapping the master data between the Channel Manager and the PMS. The communication between the interface and the Channel management system is achieved by http post using XML messages. The interface application pushes room inventory and rate update XML messages to the Channel Manager. The interface receives the bookings pushed to the interface by the Channel Manager and it creates the bookings in PMS based on the received booking XML.
The main functionalities of the interface to achieve complete reservation cycle are listed below.
New Reservation creation
Reservation Amendment
Reservation Cancellation
The ARI updates are pushed to the Channel Manager with a User ID and Password
A web interface to map the following with the Channel Manager
Property Information
Room Inventory
Rate Types
4. Interface Integration with Channel Manager
The WINCLOUD Interface package resides in the Property (WinCRS/Interface) Server.
Reservations made in booking systems linked to the Channel Manager are pushed to WINCLOUD and the ARI updates are pushed to the Channel Manager from WINCLOUD.
5. Interface Specification
Interface accepts requests in real time basis and it responds immediately as per the XML format definitions.
Only the new reservations from the Channel Manager will be created/synchronized in PMS and the reservations created from PMS will not be created/synchronized back to the Channel Manager.
The below Masters should be maintained in the Channel Management System.
Room Types
Rate Types
Properties
Master mapping option (For the Inventory codes and Rate codes defined in the Channel Manager) is available property wise.
Only one currency rate is currently supported.
The Channel Manager should provide URLs for pushing Room inventory updates and Rate updates XMLs from PMS to the Channel Manager.
The interface provides a URL to push the bookings from the Channel Manager. The reservation push URL would be different for individual property groups.
For bookings received, a success or failed response message would be sent to the Channel Manager depending upon the status.
For a booking pushed to the interface, if the Channel Manager does not receive a response message within a predefined time period, the Channel Manager should send an email to the property stating that the particular booking had failed in PMS
6. Master Data Synchronization
A master data maintained with the Channel Manager will have the updated Rate and Inventory details from different Properties. A set of rooms / rate types can be allocated to the Channel Manager in PMS. The allocated rates and rooms will be synchronized to the Channel Manager. This synchronization process is defined below
Initially, a full overlay of the Room Type, Rate and Room Inventory data (for the defined period in PMS) will be sent to the Channel Manager and afterwards, only the new and modified data will be sent.
The changes in Room Type, Rate and Room Inventory will be updated / synchronized with the Master data of the Channel Manager as mentioned below.
The full Inventory will be sent to the Channel Manager when a new room type is added.
For an already mapped Room Type, only the changes in the inventory will be sent.
The method of sending Rate update requests are also similar to that of Room Inventory.
7. Room Inventory Update
WINCLOUD interface pushes the inventory updates to the Channel Manager in the below XML format
Room Inventory Update Request Message:
Attribute | Data type | Mandatory (Y/N) | Remarks |
Target | Y | Confirms whether the request is under testing or live environment. Value: Production | |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time of inventory request |
ID | Varchar(20) | Y | The ID/Name of the Channel Manager |
ID_Context | Varchar(20) | Y | Identifies the source of the Request |
MessagePassword | Varchar(20) | Y | Password to authorize the request |
HotelCode | Varchar(10) | Y | The unique identification code of property which is used for mapping |
HotelName | Y | Property Name | |
Inventory | Y | The “Inventory” node will be repeated and each node denotes availability for a single day. | |
InvTypeCode | Varchar(10) | Y | Code that identifies an inventory item (Room Type ID) |
Start | Y | Start Date of Inventory - Date format (YYYY-MM-DD) Start date where updates will take effect. | |
End | Y | End Date of Inventory - Date format (YYYY-MM-DD) End date where updates will take effect. | |
Count | Y | Number of inventory available |
Room Inventory Update Response:
Success Response
Error Response
Element | Data type | Mandatory (Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time |
Code | N | Error Code | |
Type | N | Error Type | |
Status | N | Status message | |
ShortText | Y | Error Message |
8. Rate Update
WINCLOUD interface pushes the rate updates to the Channel Manager in the below XML format
Rate Update Request Message:
Attribute | Data type | Mandatory (Y/N) | Remarks |
Target | Y | Confirms whether the request is under testing or live environment. Value: Production | |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time of inventory request |
ID | Varchar(20) | Y | The ID/Name of the Channel Manager |
ID_Context | Varchar(20) | Y | Identifies the source of the Request |
MessagePassword | Varchar(20) | Y | Password to authorize the request |
HotelCode | Varchar(10) | Y | The unique identification code of property which is used for mapping |
RatePlanCode | Varchar(10) | Y | A particular code or an ID if the guest qualifies for a specific rate, such as AARP, AAA, etc |
InvTypeCode | Varchar(10) | Y | Code that identifies an inventory item (Room Type ID) |
Start | Y | Start Date of Inventory - Date format (YYYY-MM-DD) Start date where updates will take effect. | |
End | Y | End Date of Inventory - Date format (YYYY-MM-DD) End date where updates will take effect. | |
Mon, Tue, Wed, Thu,Fri, Sat, Sun | Y | Values: true, false. Specifies whether the amount applies to that day’s stay | |
CurrencyCode | Y | The code specifying a monetary unit. Use ISO 4217, three alpha codes. Used for an Alpha String | |
BaseByGuestAmt | Y | Base charge for a given number of guests for a given age qualifying code. This element will be included only for the defined occupancy in PMS to a maximum of 4 occupies. | |
AmountBeforeTax | Y | Total Amount not including any tax | |
NumberOfGuests | Numeric(2) | Y | The number of guests associated with this base charge. Values: 1, 2, 3, 4 |
AgeQualifyingCode | Y | Values : 10-Adult, 8-Child, 7-Infant | |
Amount | Y | Additional Guest Amount |
Rate Update Response:
Success Response
Error Response
Element | Data type | Mandatory(Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time |
Code | N | Error Code | |
Type | N | Error Type | |
Status | N | Status message | |
ShortText | Y | Error Message |
9. New Reservations
The Channel Manager pushes the bookings to the interface in the below XML message format.
The received information is validates the received data and creates reservation in PMS and a success response message would be sent to the Channel Manager. For any validation failure, it responds with corresponding failure status along with failure reason.
If the channel manager does not receives a response with in a specified period, the channel manager may send an email to the property stating that the booking request has not delivered to the PMS. This will ensure that the property is informed about the bounced booking and act accordingly.
Reservation Request Message:
Attribute | Data type | Mandatory (Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | Datetime | Y | Creation Date and Time of the message |
ResStatus | Y | Specifies the type of action requested. Value: Commit (specifies new reservation) | |
CreateDateTime | Datetime | Y | The Date and Time the Reservation was originally created |
POS / Source/ RequestorID@ID | Y | The ID/Name of the Channel Manager | |
POS/ Source/ RequestorID @Type | N | ||
POS/ Source/ RequestorID/ BookingChannel @Type | N | The type of booking channel | |
POS/ Source/ RequestorID / CompanyName | Y | The Primary booking source of the reservation (Booking Channel /OTA name) | |
ID (Inside ‘UniqueID’ tag) | Varchar(20) | Y | Unique Reservation ID from the Channel Manager |
Type (Inside ‘UniqueID’ tag) | Y | Type of object defined by Unique ID. (Value:14 -Reservation) | |
RoomStay | Y | A single section in the group normally corresponds to one room booking. Note-1: The number of section normally indicates the number of rooms booked for a particular room type. Different sections can also be used to specify bookings for different room types. (Example: A booking request for 2 rooms may have 2 sections in the XML. Otherwise, the NumberOfUnits attribute can be used to specify the total number of rooms for a room type. Any one method should be used in a booking request). This feature is only supported if the booking amend feature is not used in the interface. Note-2: If the interface is required to support the amendment requests, the new reservation request should contain only one roomstay section, that corresponds only for one number of room. Multiple rooms requests should be sent by the Channel Manager as separate reservation requests as the reservation modification is supported through split booking. In this feature, Channel Manager sends each room of the booking as a separate reservation to PMS. Example: A new booking with ID, 12345 (HotelReservations/ HotelReservation/Unique ID@ID) for 2 rooms received. Channel manager delivers the booking to PMS as 2 separate bookings with the IDs, 12345#1 and 12345#2. | |
IndexNumber | Numeric(2) | N | A unique number to identify the RoomStay in a group of Room Stays. Currently this attribute is not used. |
ID_Context | Y | Source of the ID (Value: Channel Manager ID) | |
HotelCode | Varchar(10) | Y | Hotel ID |
RatePlanCode | Varchar(10) | Y | Rate Code ID |
NumberOfUnits | Y | Number of rooms for that Room Type | |
RoomTypeCode | Varchar(10) | Y | Room Type ID |
Name (Inside ‘RoomType’ tag) | N | Room Type Name | |
GuestCount @AgeQualifying Code | N | Values: 8-child,10-adult | |
GuestCount @RPH | ResGuest’s Index within the message | ||
Count | Numeric(2) | Y | The number of guests in one AgeQualifyingCode or Count. |
TimeSpan @Start | Y | The Start date of the time span. (Arrival Date)-Date format (YYYY-MM-DD) When the field is received in the format, “2014-04-17T12:30”, the time part is taken as Check-in time. | |
TimeSpan @End | Y | The End date of the time span. (Departure Date)-Date format (YYYY-MM-DD) When the field is received in the format, “2014-04-17T11:30”, the time part is taken as Check-out time | |
RoomRates/ RoomRate | Y | Multiple RoomRate elements are not supported. If the rate differs for each day in the the booking period, corresponding Rate elements should be included inside only one RoomRate element | |
RoomRates/ RoomRate/ Rates/ Rate | Y | Specifies the rate for a particular date | |
Rates/Rate @EffectiveDate | Y | Effective date for the Rate Date format (YYYY-MM-DD). | |
AmountBeforeTax (Inside <Rate> tag) | Y | Amount exclusive of tax for the effective date | |
AmountAfterTax (Inside <Rate> tag) |
| N | Total Amount inclusive of tax and other charges for the RoomStay. If AmountAfterTax attribute is available, tariff will be picked from AmountAfterTax. If AmountAfterTax attribute is not available, tariff will be picked from AmountBeforeTax. If both attributes are available in the xml, the required amount would be picked based on the settings in the interface. |
AmountBeforeTax (Inside <Roomstay> <Total> tag) | Y | Total Amount exclusive of tax for the RoomStay | |
AmountAfterTax (Inside <Roomstay> <Total> tag) | N | Total Amount inclusive of tax and other charges for the RoomStay. | |
DepositPayments | N | DepositPayments tag with the amount specifies the advance amount collected while booking for the particular Roomstay. This tag should be included only when advance amount is collected. The total advance amount should be specified in the DepositPayments tag in the first RoomStay node | |
<Comment> <Text> (Inside RoomStay tag) | N | Special request for the particular room | |
ResGuestRPH (Inside ResGuest tag) | Y | ResGuest Index to identify the guest associated with a RoomStay | |
Type | Y | Values: 1 = Guest ID 4 = Corporate/Company ID 5 = Travel Agent ID 7 = Booker ID | |
ProfileType | Y | Values: 1 = Guest 3 = Corporate/Company 4 = Travel Agent 5 = Booker | |
GivenName (Inside ResGuest tag) | Varchar(30) | Y | Booker or Guest First Name |
Surname (Inside ResGuest tag) | Varchar(25) | Y | Booker or Guest Last Name |
PhoneNumber | N | Booker or Guest Phone number | |
PhoneTechType | Y | Values: 1 = Voice 5 = Mobile | |
Varchar(40) | N | Booker or Guest email | |
AddressLine | Varchar(40) | N | Booker or Guest address |
CityName | Varchar(40) | N | Booker or Guest City Name |
PostalCode | Varchar(10) | N | Booker or Guest Postal Code |
CountryName | Varchar(50) | N | Booker or Guest Country Name |
CardCode | N | The 2-character code of the credit card issuer | |
ExpireDate (Inside PaymentCard) | MMYY | N | Card Expiration date in the format MMYY |
CardHolderName | N | Full Name on Credit card | |
CardType | N | Type of card | |
CardNumber | N | Credit Card number | |
<Comment> <Text> (Inside ResGlobalInfo tag) | N | Common (Additional) Request | |
AmountBeforeTax (Inside <ResGlobalInfo> <Total> tag) | Y | Total Amount charged for the booking without tax | |
Amount (Inside <ResGlobalInfo> <Tax> tag) | N | Tax Amount | |
AmountIncluding Markup | Y | Total Amount charged for the booking including tax |
Reservation Response:
Success Response
Error Response
Element | Data type | Mandatory(Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time |
Success | Y | If this element exists, it indicates that the reservation was processed successfully. | |
ResID_Type | Y | The type of Reservation ID. Values: 3-PMS ID, 8-Channel Manager ID. | |
ResID_Value | Y | Reservation Number. This value is required for a successful reservation response | |
Code | N | Error Code | |
Type | N | Error Type | |
Status | N | Status message | |
ShortText | Y | Error Message |
10. Amend Reservations
The reservation modification is only supported through split booking. The reservation request should contain only one roomstay section, that corresponds to one number of room. In this feature, Channel Manager sends each room request in the booking as a separate reservation to PMS.
Example: For a reservation request with 3 rooms for either the same room type or different room type, the reservation should be split and pushed to the interface as 3 separate reservations. The reservation ID for each of the 3 separate reservations can be created as specified in the element description table below.
The modified bookings are pushed to the interface in the XML message format specified below. The received information is validated and the reservation is created in PMS and a success response message is sent to the Channel Manager. For any validation failure, it responds with corresponding failure status along with failure reason.
If the channel manager does not receives a response with in a specified period, the channel manager may send an email to the property stating that the booking amend request has not delivered to the PMS. This will ensure that the property is informed about the bounced amend request and act accordingly.
Reservation Amend Request Message:
Attribute | Data type | Mandatory(Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | Datetime | Y | Creation Date and Time of the message |
ResStatus | Y | Specifies the type of action requested. Value: Commit (specifies new reservation) | |
CreateDateTime | Datetime | Y | The Date and Time the Amend Reservation was originally created |
Type (Inside ‘BookingChannel’ tag) | N | The type of booking channel | |
CompanyName | Y | The Primary booking source of the reservation (Booking Channel /OTA name) | |
ID (Inside ‘RequestorID’ tag) | Y | The ID/Name of the Channel Manager | |
ID (Inside ‘UniqueID’ tag) | Varchar(20) | Y | Unique Reservation ID from the Channel Manager |
Type (Inside ‘UniqueID’ tag) | Y | Type of object defined by Unique ID. (Value:14 -Reservation) | |
RoomStay | Y | A single section in the group corresponds to a single booking for one number of room Modification example: For a new booking request, a reservation with Id, 12345#1 in OTA_ HotelResNotifRQ.xml will be delivered. When this was amended with one more room, 2 reservations will be delivered to PMS, One is the modification with id 12345#1 in OTA_ HotelResModifyNotifRQ XML message and the second one is a new room booking with id 12345#2 in OTA_HotelResNotifRQ XML message will be delivered. | |
IndexNumber | Numeric(2) | N | A unique number to identify the RoomStay in a group of Room Stays. Currently this attribute is not used. |
ID_Context | Y | Source of the ID (Value: Channel Manager ID) | |
HotelCode | Varchar(10) | Y | Hotel ID |
RatePlanCode | Varchar(10) | Y | Rate Code ID |
NumberOfUnits | Y | Number of rooms for that Room Type | |
RoomTypeCode | Varchar(10) | Y | Room Type ID |
Name (Inside ‘RoomType’ tag) | N | Room Type Name | |
AgeQualifyingCode | N | Values: 8-child,10-adult | |
RPH (Inside ResGuestRPHs tag) | Y | ResGuest’s Index within the message | |
Count | Numeric(2) | Y | The number of guests in one AgeQualifyingCode or Count. |
Start | Y | The Start date of the time span. (Arrival Date)-Date format (YYYY-MM-DD) When the field is received in the format, “2014-04-17T12:30”, the time part is taken as Check-in time. | |
End | Y | The End date of the time span. (Departure Date)-Date format (YYYY-MM-DD) When the field is received in the format, “2014-04-17T11:30”, the time part is taken as Check-out time | |
EffectiveDate | Y | Effective date for the Rate Date format (YYYY-MM-DD). | |
AmountBeforeTax (Inside <Rate> tag) | Y | Amount exclusive of tax for the effective date | |
AmountAfterTax (Inside <Rate> tag) |
| N | Amount inclusive of tax and other charges for the effective date. If AmountAfterTax attribute is not available, tariff will be picked from AmountBeforeTax. If both attributes are available in the xml, the amount would be picked based on the settings in the interface. |
AmountBeforeTax (Inside <Roomstay> <Total> tag) | Y | Total Amount exclusive of tax for the RoomStay | |
AmountAfterTax (Inside <Roomstay> <Total> tag) | N | Total Amount inclusive of tax and other charges for the RoomStay. | |
DepositPayments | N | DepositPayments tag with the amount specifies the advance amount collected while booking for the particular Roomstay. This tag should be included only when advance amount is collected. The total advance amount should be specified in the DepositPayments tag in the first RoomStay node | |
<Comment> <Text> (Inside RoomStay tag) | N | Special request for the particular room | |
ResGuestRPH (Inside ResGuest tag) | Y | ResGuest Index to identify the guest associated with a RoomStay | |
Type | Y | Values: 1 = Guest ID 4 = Corporate / Company ID 5 = Travel Agent ID 7 = Booker ID | |
ProfileType | Y | Values: 1 = Guest 3 = Corporate/Company 4 = Travel Agent 5 = Booker | |
GivenName (Inside ResGuest tag) | Varchar(30) | Y | Booker or Guest First Name |
Surname (Inside ResGuest tag) | Varchar(25) | Y | Booker or Guest Last Name |
PhoneNumber | N | Booker or Guest Phone number | |
PhoneTechType | Y | Values: 1 = Voice 5 = Mobile | |
Varchar(40) | N | Booker or Guest email | |
AddressLine | Varchar(40) | N | Booker or Guest address |
CityName | Varchar(40) | N | Booker or Guest City Name |
PostalCode | Varchar(10) | N | Booker or Guest Postal Code |
CountryName | Varchar(50) | N | Booker or Guest Country Name |
CardCode | N | The 2-character code of the credit card issuer | |
ExpireDate (Inside PaymentCard Tag) | MMYY | N | Card Expiration date in the format MMYY |
CardHolderName | N | Full Name on Credit card | |
CardType | N | Type of card | |
CardNumber | N | Credit Card number | |
<Comment> <Text> (Inside ResGlobalInfo tag) | N | Common (Additional) Request | |
AmountBeforeTax (Inside <ResGlobalInfo> <Total> tag) | Y | Total Amount charged for the booking without tax | |
Amount (Inside <ResGlobalInfo> <Tax> tag) | N | Tax Amount | |
AmountIncluding Markup | Y | Total Amount charged for the booking |
Reservation Amend Response:
Success Response
Error Response
Element | Data type | Mandatory(Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time |
Success | Y | If this element exists, it indicates that the reservation was processed successfully. | |
ResID_Type | Y | The type of Reservation ID. Values: 3-PMS ID, 8-Channel Manager ID. | |
ResID_Value | Y | Reservation Number. This value is required for a successful reservation response | |
Code | N | Error Code | |
Type | N | Error Type | |
Status | N | Status message | |
ShortText | Y | Error Message |
11. Reservation Cancellation
The booking cancellation requests are pushed to the interface in the XML message format specified below. When the booking is cancelled in PMS, a success response message would be sent to the Channel Manager. For any validation failure, it responds with corresponding failure status along with failure reason.
If the channel manager does not receive a response with in a specified period, the channel manager may send an email to the property stating that the booking cancellation request has been failed in PMS. This will ensure that the property is informed about the failed request for booking cancellation and act accordingly.
Reservation Cancellation Request Message:
Element | Data type | Mandatory(Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time |
CancelType | Y | Specifies the type of action requested. Value: Cancel | |
Type (Inside ‘BookingChannel’ tag) | N | The type of booking channel | |
CompanyName | Y | The Primary booking source of the reservation (Booking Channel /OTA name) | |
ID (Inside ‘RequestorID’ tag) | Y | The ID/Name of the Channel Manager | |
ID (Inside ‘UniqueID’ tag) | Varchar(20) | Y | Unique Reservation ID from the Channel Manager |
Type (Inside ‘UniqueID’ tag) | Y | Type of object defined by Unique ID. (Value: 14 - Reservation) | |
ID_Context | Y | Source of the ID (Value: Channel Manager ID) | |
GivenName | Varchar(30) | Y | Booker or Guest First Name |
Surname | Varchar(25) | N | Booker or Guest Last Name |
ReservationTimeSpan | N | The start and end date of the reservation | |
HotelCode | Varchar(10) | Y | The unique identification code of property which is used for mapping |
HotelName | N | Property Name |
Reservation Cancellation Response:
Success Response
Error Response
Element | Data type | Mandatory(Y/N) | Remarks |
EchoToken | Varchar(10) | Y | A unique ID- generated from Source (A sequence number can be used) |
Timestamp | DateTime | Y | Current date and Time |
Success | Y | If this element exists, it indicates that the reservation was processed successfully. | |
Type | Y | The type of Reservation ID. Values: 10-PMS ID, 14-Channel Manager ID. | |
ID | Y | Reservation Number. This value is required for a successful reservation response | |
Code | N | Error Code | |
Type | N | Error Type | |
Status | N | Status message | |
ShortText | Y | Error Message |
Last updated
