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
Was this helpful?
