4. char pmslink HTTPPMS EQUIPMENT BASIC API

08/11/2021.
Specific version for room equipment.
Incorporation of a general message for BOOKING reservation and occupancy management, maintaining specific occupancy messages for compatibility (CHECKIN, UPDATE, MOVE, CHECKOUT).

15/02/2020.
New version of the specification’s document..

Description

char pmslink is an intelligent middleware that allows the integration of Property Management Systems (PMS) with the different devices and hotel systems (PBX, TV, Hotspot, multimedia, home automation, app guest access, minibar, etc.).

www.charpmslink.com

This integration does not only transform links and protocols in order to connect every system. It goes further and adds intelligence to those connections, controlling its status, apporting traceability, managing buffers, adapts the default values of each single system and uses a single PMS interface in order to integrate all the devices and systems connected to it.

char pmslink adapts itself to any architecture, supports any kind of system such as cloud, remote, locals, mono-hotel, multi hotel, etc.

On the other hand, it also makes easier the integration between all the systems/devices connected between themselves. For example, setting up a wakeup call using the TV system or a guest App, it is done on the PABX and notifies the PMS system.

This document includes all the specifications in order to integrate char pmslink, using its API HTTPPMS GUEST BASIC, by linking to a HTTP server and exchanging data in JSON format.

HTTPPMS GUEST BASIC for room equipment is a basic API to facilitate the integration between PMS systems (Cloud, on-premise) with equipment, devices and systems that provide services to the guest:

• PBX
• Access System – keycard – mobile key
• IPTV
• Hotspot
• Multimedia
• Automation – Domotics – Energy Efficiency
• Basic Housekeeping systems
• And more ….

This API, in extended versions, supports advanced features. It also exists an API where pmslink assumes a Server Role, making easier the immediate messages exchange by the PMS. 

The integration is done according to the functionality provided by the PMS system:

PMS > Integrated Systems

Processing the booking / occupancy events provided by the PMS:

• Booking CREATION.
• ROOM ALLOCATION to a booking.
• CANCELLATION of the booking.
• NO SHOW.
• UPDATE, booking and/or Guest data.
• CHECKIN, guest’s arrival.
• ROOM MOVE.
• CHECKOUT, guest’s departure.

Providing data on bookings, guests accommodated and stays

Processing actions and commands to the integrated systems:

• Class of Service (COS)/Profile assignation to PBX, TV, Hotspot, etc.
• Programming / cancelling Reminders (wake up calls).
• Activation / deactivation of Do Not Disturb option (DND).
• Activation / deactivation for message on hold indicator.
• Hotel message to the guest.

Processing stay/occupancy data to the integrated systems:

• Cleaning Room Status and Room Availability. 
• Activation / deactivation of room cleaning request.
• Hotel messages for the guest.
• Guest invoice information.

Integrated Systems > PMS

Processing data, messages, and charges destinated to the PMS system:

• Possible charges linked to the integrated system such as phone calls, minibar, IPTV, Internet, etc.
• Room Status Notification.
• Activation / deactivation of room cleaning request. 
• Activation / deactivation of Do Not Disturb option (DND).
• Guest messages for the hotel.
• Invoice data request.
• Checkout request.

The integration through char pmslink provides to the PMS system a common interface that allows the integration of multiple hotel systems:

https://charpmslink.com/integrations-hotel-equipment-systems/

In general terms, it is possible to expand this API in cases that it is required.

---

Development process, testing, certification, and integration procedure

This API is considered as public domain, but its use is restricted to char pmslink integrations and can’t be allowed its use for direct integration with other systems.

char does not apply any economical charge to the system that creates the integration with char pmslink using this API.

The basic steps in order to create the integration are the following ones:

• The candidate to integrate with char pmslink should contact through  https://www.charpmslink.com/contact/ in order to start the process and obtain more extended information about the process itself and formalize a technical agreement. (https://charpmslink.com/download/doc/templates/char_technology_agreement_template.pdf)
• Once the interface needed by the system willing to integrate has been developed, char will configure a custom driver according to the settings, adjustments and functionalities implemented.
• Using the first driver version, coordinated tests will be done in order to validate the final driver and its documentation.
• Once validated, it will be considered as an integrated system for all intents and purposes, being released to public, including it in the PMS integrated systems list and notifying through the common news channels. The PMS will be able to publish and advertise at its will the integration and the additional value that provides the integration itself.

Once the previous steps are done, char will have a fluid relationship with the integrated system in order to solve possible issues with its installations, adjustments and updating its functionalities in the cases that is needed.

---

General use terms

The integrated PMS system assumes the role of SERVER, keeping open the HTTP/HTTPS server to which PMSLINK will send the necessary actions, data and requests.

In this way of working:

• The integrated systems through pmslink will send real-time HTTP requests to the PMS via http client connection to this server.
• pmslink shall periodically query the PMS system to update reservation and occupancy data and perform actions on the integrated equipment.

To minimise the impact of these queries, the PMS system will maintain a queue of booking and action request events, which will be queried periodically by PMSLINK at a frequency (configurable) sufficient to obtain the data at the required interval without over-processing the PMS. 

This event queue (FIFO):

• I will store the events related to Reservations in case of any change in the reservation data that affect the Integration and/or occupant data.
• It will return in each request the data stored since the last query, automatically deleting the data sent. In this way it will not be necessary to keep a record of requests or process requests in a range of dates.
• The data will be provided in the format defined in these specifications

PMS – PMSLINK communication

PMSLINK will send request for action GET_REQUEST.

The PMS will return:

Events and booking related data.

BOOKING data:

From the creation of a booking, any change in the booking data and/or its occupants will generate a ‘booking’ record:

• Booking creation.
• Change of status / occupancy of a booking: cancellation, No Show, occupancy, departure, etc.
• Changes in the data of a booking related to the Integration: Stay data, property data, etc.
• Room assignment, first room assignment, room change, etc.
• Change in Guest data: personal data, contact data, add/remove occupants, etc.

In general terms, any change that affects the data processed by the API for a reservation and its guests.

Information related to the stay – Data:

• ROOM_STATUS: Change of Room Status and/or Room Availability

Actions related to equipment and integrated systems:

If the PMS system offers room equipment control, actions:

• MUR: Room cleaning request.
• COS: Class of Service (COS) / Profile for PBX, TV, HOTSPOT, etc. systems assignment. 
• WMSG: Message on hold indicator, activation / deactivation.
• WAKE:  Wake Up calls, set Up / Cancellation.
• DND: Do Not Disturb (DND) status Activation/ Deactivation. 
• MSGTXT: Message to guests.

SYSTEMS/EQUIPMENT (PMSLINK) – PMS communication

Requests to HTTP/HTTPS server of the PMS, sent in real time for actions:

• POST: Charges PBX, TV, Internet, Services, etc.
• ROOM_STATUS: Change of Room Status and/or Room Availability
• MUR: Room Cleaning Request.
• DND: Do Not Disturb (DND) status Activation/ Deactivation. 
• BILL_REQUEST:  Request for billing data.
• CHECKOUT: Express checkout request.
• CALL: Phone call data. Alternative to charge PBX.
• WAKE:  Wake Up calls, Set Up / Cancellation / Executed / Failure.
• DND: Do Not Disturb (DND) status Activation/ Deactivation.
• MSGTXT: Message to hotel from guest.

---

Link Connection

char pmslink, through HTTPPMS GUEST BASIC will link with the PMS server/servers using HTTP/HTTPS.

URLs:

The destination URL can be:

• Specific for each ACTION and request. Containing the hotel ID in case of multi-hotel scenarios. Example: https://pms.api.com/checkin?hotel=123456
• Common for all ACTIONS and requests. Containing the ACTION as parameter and the hotel ID in case of multi-hotel scenarios. Example: https://pms.api.com/action?id=chko&hotel=123456
• Common for all ACTIONS and requests. ACTION and the rest of parameters will be sent as message. Example: https://pms.api.com

Data Format:

JSON is the recommended data format, however XML can be used. On this document, all the examples shown will be using JSON format. 

The type ‘real’ has the format ‘integer’ + separator (‘.’) + ‘decimal’ using two digits. Example: 123.50

The type ‘number’ refers to an integer without decimals. Example: 1

Date values will be expressed in string YYYY-MM-DDTHH:NN:SS and will refer to the local time (and time zone) for each installation. Ex: 01/01/2021 at 10:30 = 2021-10-01T10:30:00

The language codes used will be the ones according to ISO 639-1.

Authentication:

There are three possibilities:

BASIC:

• HTTP Basic access authentication. Request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the Base64 encoding of ID and password, based on RFC 7617.

TOKEN:

• Authentication done using an agreed token between the pmslink and the integrated system.
• Example: 12345-12345-12345-12345

MD5:

• The authentication will be done using an encrypted token using MD5 algorithm generated based on User + date-time value (YYYYMMDDHHNNSS) + password for each request.
• Example: User ‘user1’, date ‘20150101101112’, password ‘password1’ = MD5(user120150101101112password1) = 61e7c7371170a948eaf63fa578840025.

Password is an internal value, agreed as general use or unique on each installation, but not sent as data.

HTTP commands:

Requests will be done using POST commands in all cases:

• To communicate actions and data to the PMS: phone calls, charges, reminders, Room Status, etc…
• To request actions and messages to the PMS: GET_REQUEST.

Confirmations and replies:

The responses to each request will have in all cases, and in all directions (PMSLINK > PMS and PMS > PMSLINK) a common part and will be based on:

• All responses to the execution of a Process will return HTTP 200 code.
• Other HTTP codes will indicate a result at HTTP link level.

The response to a process (code 200), will include in the BODY:

Code (REQUIRED):

Result code under the criteria: 0 success, 1xx error that requires a retry (range 100-125), 2xx error not recoverable on retry (range 200-225).

Description (REQUIRED):

Comment on the result in case of code 0. Description of the error in case of code <> 0. This description must be sufficiently, clearly, and precisely given so that the causes can be determined.

Additional data (OPTIONAL):

In case of data return, these shall be included in addition to the response structure as appropriate.

Example 1:

{
    "code": 1,
    "description": "CHARGE PROCESS: Destination account does not exist or is closed"
}

Example 2:

{
    "code": 0,
    "description": "OK"
}

Example 3:

{
    "code": 0,
    "description": "OK",
    "data": [{"name": "name 1", "id": "1"}, {"name": "name 2", "id": "2"}]
}

Link connection control:

char pmslink will keep a buffer (FIFO) as a queue for pending information to be sent in the following cases:

• Physical linking errors with the PMS server.
• Actions that return the following codes: 400, 401 and/or 500. Those are addressed as one-time errors which will be assumed that will be recovered by the server or settings adjustments that will allow the process.

In case of link connection errors, char pmslink will retry to resend in a programmed frequency all the information on that queue.

---

PMS > pmslink

GET_REQUEST Action

Sent by char pmslink as a request to the PMS for the actions and stored data in the pending queue.

If exists pending messages, the PMS will return a maximum of 100 messages per query, and on receiving a reply confirming the reception, it will remove them from the sending queue.

If there are no messages, the PMS will confirm the process through the HTTP code 200, {“code”: 0, “description”: “OK”} without including response data.

Send

Data	Required	Type	Name	Value
Date -Time	YES	String	datetime	Date-Time requirement (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Required according to the type of authentication.
Authentication	(YES)	String	usertoken	Token. Required according to the type of authentication.
Action	YES	String	GET_REQUEST	Object containing action data
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.

Response

Code	YES	Number	Code	According to specified response codes
Description		String	Description	Description of the returned code value.
Record List	YES	String	ACTION_LIST	Actions and Data Array
Actions		Object	According to Action ID. Mandatory if exists data in the pending queue	BOOKING: Reservation data COS: Class of Service WMSG: Waiting Messag WAKE: Wake Up message DND: Do Not Disturb RS: Housekeeping code MSGTXT: Message to the Guest MUR: Request for room cleaning

Data and structure according to type of record

JSON Example

Request: POST

{
    "datetime": "20150101101112",
    "user" : "user1",
    "usertoken" : "61e7c7371170a948eaf63fa578840025",
    "action": "GET_REQUEST",
    "property": "myhotel"
}

Response

{
    "code": 0,
    "description": "OK",
    "ACTION_LIST": [ (Data and structure according to each type of record) ]
}

Booking Data

Response to GET_REQUEST action. Data of anew reservation or changes in its status, data and/or occupants.

Data	Required	Type	Name	Value
Date – Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	BOOKING
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UID	YES	String	booking_uid	Internal booking UID, it may or may not match with (public) locator. Mandatory on multi – hotel scenarios
Locator		String	locator	Public locator of the booking, if it does not exist, the same value as the ‘id’ field will be sent.
Status	YES	String	status	“expected”, “cancel”, “noshow”,”checkin”, ”checkout”
Room	(YES)	String	room	Room name occupied by the booking. Required for the “checkin”, “checkout” status. In case of room move, new room assigned.
Account	(YES)	String	account	Account associated to the booking. If the PMS treats them at occupant level, it is the account of the main guest. Mandatory in cases of multi-occupancy.
Arrival	YES	String	arrival	Arrival Date-Time in format YYYY-MM-DDTHH:NN:SS. The Time will be the estimated time.
Departure	YES	String	departure	Departure Date-Time in format YYYY-MM-DDTHH:NN:SS. The Time will be the estimated time.
Level	(YES)	String	level	Generic VIP level of the booking. If the PMS treats them at occupant level, it must be used the VIP level of the main guest. Required in case of integration with equipment that manages profiles based on VIP level.
COS PBX	(YES)	String	cos_pbx	Class of Service of the PBX allowed on booking. Example: 0 = Deny calls; 1= Allow calls. Mandatory in case of managing call restriction at booking level.
COS TV	(YES)	String	cos_tv	TV service profile allowed on booking. Example: A=Adult profile; 0= restrict purchases; 1= allow purchases. Mandatory in case of TV profile management at booking level.
COS INTERNET	(YES)	String	cos_inet	Internet profile Access. Example: A= profile without limit; B=   profile with limitations.Mandatory in case of Internet profile at booking level.
PAX		Number	pax	Total number of occupants
GUEST LIST		Array	GUEST_LIST
Guest UID	YES	String	uid	Internal guest UID
Main guest		Boolean	main	‘true’ = Main guest‘false’ = Additional occupant. If the PMS does not send the specific data, pmslink will assign the first in the list as the main guest.
Age stage		Boolean	adult	true = adultfalse = children
Account	(YES)	String	account	Account associated with the guest.Mandatory in cases of multi-occupancy.
Title		String	title	Guest treatment.Recommended for systems that display personalised information.
Name	YES	String	name	Guest’s Name
Surname	YES	String	surname	Guest’s Surname
Gender		String	gender	Guest’s Gender
Level	(YES)	String	level	Guest’s VIP level.Mandatory in case of integration with equipment managing profiles based on VIP level.
Language	YES	String	language	Guest’s Language (ISO 639-1)
e-mail	(YES)	String	email	Guest’s e-mail address. Mandatory for Mobile Key.
Mobile phone	(YES)	String	mobile	Guest’s mobile phone number. Mandatory for Mobile Key.
Allows contact	(YES)	Boolean	acontact	true = Allows contactfalse = NOT allow contact. Mandatory for Mobile Key.
Passport	(YES)	String	passport	Guest’s Passport. Mandatory for equipment requiring user login
Identity card	(YES)	String	idcard	Identity card. Mandatory for equipment requiring user login
COS PBX	(YES)	String	cos_pbx	PBX Class of Service allowed to the booking. Example: 0= Deny calls; 1= Allow outgoing calls. Mandatory in case of managing call restriction at guest level.
COS TV		String	cos_tv	TV profile service allowed to the Guest.Example: A = Adult profile; 0= Restrict purchases; 1= Allow purchases. Mandatory in case of managing TV profiles at guest level.
COS INTERNET		String	cos_inet	Internet profile Access. Example: A= profile without limit; B= profile with limitations. Mandatory in case of Internet profile at guest level.

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "action": "BOOKING",
    "property": "myhotel",
    "booking_uid": "qwertyu-1234",
    "status": "checkin",
    "room": "101",
    "account": "123456",
    "arrival": "2015-01-01T10:00:00",
    "departure": "2015-01-06T12:00:00",
    "level": "1",
    "cos_pbx": "1",
    "cos_tv": "A1",
    "cos_inet": "A",
    "pax": 2,
    "GUEST_LIST": [{
                        "uid": "987654",
                        "main": true,
                        "adult": true,
                        "account": "456789",
                        "title": "Mr.",
                        "name": "john",
                        "surname": "Doe",
                        "gender": "male",
                        "level": "1",
                        "language": "en",
                        "email": "john.doe@sample.com",
                        "mobile": "12345678901234567890",
                        "allow_contact": true,
                        "passport": "1234567890",
                        "identity_card": "1234567890",
                        "cos_pbx": "1",
                        "cos_tv": "A1",
                        "cos_inet": "A"
                    }]
}

Room Status Data

Response to GET_REQUEST action. Notified by the PMS as an indication of the cleaning status/availability of a room as a result of the actions made by the user or the PMS process itself.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	RS
Hotel	(YESX)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
State	YES	String	status	According to values by the PMS, normally combining cleaning status / availability.

JSON Example

pmslink Request

{
    "datetime": "2015-01-01T10:11:12",
    "action": "RS",
    "property": "myhotel",
    "room": "101",
    "status": "C"
}

MUR Action

Response to GET_REQUEST action, as a request / indicating availability for room cleaning.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	MUR
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
MUR state	YES	Boolean	active	Enabled / Disabled (true / false).

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "action": "MUR",
    "property": "myhotel",
    "room": "101",
    "active": true
}

COS Action

Response to GET_REQUEST action. Notified by the PMS as an action for the Class of Service assignment of the integrated systems.

Typically sent in the case of restrictions of all/any of the systems involved, immediately after the guest arrival (checkin action), or at the moment that the restriction is applied.

By default:

• Changing a booking to checkin status removes all restrictions.
• Changing a booking to checkout status applies all restrictions.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	COS
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Room	YES	String	room	Room’s ID.
PBX Service Level	YES	String	cos_pbx	PBX Class of Service allowed to the booking. Example: 0= Deny calls; 1= Allow outgoing calls.
TV Service Level	YES	String	cos_tv	TV profile service allowed to the Guest.Example: A = Adult profile; 0= Restrict purchases; 1= Allow purchases.
HOTSPOT Service Level	YES	String	cos_inet	Internet profile Access. Example: A= profile without limit; B=   profile with limitations.

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "action": "COS",
    "property": "myhotel",
    "room": "101",
    "cos_pbx": "0",
    "cos_tv": "0",
    "cos_inet": "0"
}

WMSG Action

Response to GET_REQUEST action. Notified by the PMS indicating that there are messages for the guest (phone’s led, TV, multimedia systems, etc.).

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	WMSG
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
Message Waiting state.	YES	Boolean	active	Enabled / Disabled (true / false).

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "action": "WMSG",
    "property": "myhotel",
    "room": "101",
    "active": true
}

WAKE Action

Response to GET_REQUEST action. Notified by the PMS as the action of the programming / cancellation of the Reminder (Wake Up call)

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	WAKE
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID.
Action type	YES	String	mode	S: Setting up C: Cancellation
Identifier	(YES)	String	uid	Reminder’s unique identifier.
Reminder Time	YES	String	waketime	Reminder Date-Time (YYYY-MM-DDTHH:NN:SS)

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "action": "WAKE",
    "property": "myhotel",
    "room": "101",
    "mode": "S",
    "uid": "12345",
    "waketime": "2015-01-02T08:00:00"
}

DND Action

Response to GET_REQUEST action. Notified by the PMS as action for enable / disable the Do Not Disturb (DND) feature.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	DND
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
DND state	YES	Boolean	active	Enabled / Disabled (true / false).

JSON Example

{
    "datetime":"2015-01-01T10:11:12",
    "action": "DND",
    "property": "myhotel",
    "room": "101",
    "active": true
}

MSGTXT Action

Response to GET_REQUEST action. Notified by the PMS as text message to be transmitted to the guest (TV, multimedia, app’s, etc).

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYY-MM-DDTHH:NN:SS)
Action	YES	String	action	MSGTXT
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Room	YES	String	room	Room’s ID
Identifier		String	uid	Message Identifier
Message	YES	String	text	Message Text

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "action": "MSGTXT",
    "property": "myhotel",
    "room": "101",
    "uid": "12345",
    "text": "Welcome to the hotel"
}

---

pmslink > PMS

POST Request

Sent to the PMS as information and charges of services performed, purchases, usage fees, etc.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only required if MD5 authentication is used.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5.
Action	YES	String	action	POST
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UID		String	booking_uid	Internal UID of the associated booking. If not sent, the charge will be made on the account or room indicated.
Room	YES	String	room	Room’s ID
Account		String	account	User account on which the charge will be applied. If not sent, the charge will be made generically on the reservation or room indicated.
Type of charge	YES	String	post_type	P: PBX (Alternative to CALL request) M: Minibar T: TV / Video N: Internet (-): Others to be defined
Article	YES	String	article	Article Code
Description		String	description	Charge description
Units	YES	Numeric	units	Article Units
Article price	(YES)	Numeric	price	Price (taxes included) per article unit, required in case total amount is not sent.
Total charge Amount	(YES)	Numeric	amount	Total charge amount, taxes included.
Type of TAX		String	tax	Type of tax’s code that it is included in the charge according PMS codification.

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "POST",
    "property": "myhotel",
    "booking_uid": "qwertyu-123456",
    "room": "101",
    "account": "12345678",
    "post_type": "M",
    "article": "WA",
    "description": "Water",
    "units": 1,
    "amount": 2.50,
    "tax": "23"
}

Room Status Request

Sending to the PMS the Room Status change made by maids/housekeepers through phone devices, housekeeping systems, etc.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	RS
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
State	YES	String	status	According to values by the PMS, normally combining cleaning status / availability.
Worker		String	maid	Worker’s ID that makes the change.

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "RS",
    "property": "myhotel",
    "room": "101",
    "roomstatus": "C",
    "maid": "123"
}

MUR Request

Sent to the PMS (and housekeeping systems) as request / indicating availability for room cleaning.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	MUR
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
MUR state	YES	Boolean	active	Enabled / Disabled (true / false)

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "MUR",
    "property": "myhotel",
    "room": "101",
    "active": true
}

DND Request

Sent to the PMS as action for enable / disable the Do Not Disturb (DND) feature.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	DND
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID
DND state	YES	Boolean	active	Enabled / Disabled (true / false).

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "DND",
    "property": "myhotel",
    "room": "101",
    "active": true
}

Bill Request

Sending to the PMS as a request for invoice details of the reservation / account or room indicated.

Typically, as information to be displayed on TV/Multimedia systems, especially as a confirmation step prior to the express checkout request.

The invoice items are returned in the response to the request.

Request:

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	BILL_REQUEST
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Booking UID		String	booking_uid	Internal UID of the associated booking. If the data is not sent, it will correspond to the account / room indicated.
Room	YES	String	room	Room’s ID
Account		String	account	User account on which the payment will be made. If the data is not sent, it will correspond to the booking / room indicated.

Response:

Data	Required	Type	Name	Value
ITEM LIST IDENTIFIER INVOICE			ITEM_LIST	Identifier of the array containing the items of the invoice.
BILL ITEM OBJECT
Date – Time	YES	String	datetime	Date-Time of item (YYYY-MM-DDTHH:NN:SS)
Article		String	article	Article code
Description	YES	String	description	Article description
Net amount		Real	net	Net amount of the article
Taxes		Real	taxes	Taxes charged on the article
Total	YES	Real	total	Total charge including taxes
BILL DATA
Total Factura		Real	bill_total	Total bill including taxes
Notes		String	notes	General bill notes

JSON Example

Request

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": " BILL_REQUEST ",
    "property": "myhotel",
    "booking_uid": "qwertyui-123456",
    "room": "101",
    "account": "1234567"
}

Response

{
    "code": 0,
    "description": "OK",
    "ITEM_LIST":    [{
                        "datetime": "2015-01-01T15:16:17",
                        "article": "WA",
                        "description": "Water",
                        "net": 2.00,
                        "taxes": 0.20,
                        "total": 2.20
                    }],
    "bill_total": 2.20,
    "notes": "taxes included"
}

Checkout Request

Sending to the PMS as request of booking checkout / indicated room.

The PMS will confirm or deny the request depending on whether automatic execution is possible.

Typically, as information to be displayed on TV/Multimedia systems, especially as a confirmation step prior to the express checkout request.

The invoice items are returned in the response to the request.

Request

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	CHECKOUT
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Booking UID		String	booking_uid	Internal UID of the associated booking. If the data is not sent, it will correspond to the account / room indicated.
Room	YES	String	room	Room’s ID
Account		String	account	User account on which the payment will be made. If the data is not sent, it will correspond to the booking / room indicated.

Response

Data	Required	Type	Name	Value
Message to guest		String	notes	Message to the Guest according to the acceptance or rejection of the request.

JSON Example

Request

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "CHECKOUT",
    "property": "myhotel",
    "booking_uid": "qwertyui-123456",
    "room": "101",
    "account": "1234567"
}

Response

{
    "code": 0,
    "description": "OK",
    "notes": "The invoice will be charged to your credit card. We wish you had a happy stay at our hotel"
}

Call Request

Optional to sending PBX type charges. Sent to the PMS as information and specific charge of the phone call.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	CALL
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Room	YES	String	room	Room’s ID
Type of call	YES	String	call_type	O: Outbound call I: Incoming call (optional) L: Internal call (optional)
Line		String	line	Line’s link used
Number	YES	String	number	Destination / origin number
Answer Time		Numeric	response	Response time (seconds)
Call Duration	YES	Numeric	duration	Call duration (0 = not answered)
Call Accounting Units		Numeric	units	Call Accounting units (Outbound calls)
Phone call cost		Real	price	Phone call cost (outgoing call)In case of no “charge units” it is calculated with the call duration and the phone number destination

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "CALL",
    "property": "myhotel",
    "room": "101",
    "call_type": "O",
    "line": "sip-12345",
    "number": "5555555",
    "response": 3,
    "duration": 12,
    "Price": 2.50
}

WAKE Request

Sent to the PMS as action information related to a Reminder (Wake Up call).

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	WAKE
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios
Room	YES	String	room	Room’s ID.
Action type	YES	String	mode	S: Setting up C: Cancellation E: Confirmation/Done. Only required in case to be sent to the PMS F: Failed. Only required in case to be sent to the PMS
Identifier		String	uid	Reminder’s unique identifier.
Reminder Time	YES	String	waketime	Reminder Date-Time (YYYY-MM-DDTHH:NN;SS)

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "WAKE",
    "property": "myhotel",
    "room": "101",
    "mode": "E",
    "uid": "12345",
    "waketime": "2015-01-02T08:00:00"
}

MSGTXT Request

Sent to the PMS as guest’s message to the hotel through TV, multimedia, app’s, etc.

Data	Required	Type	Name	Value
Date-Time	YES	String	datetime	Date-Time of the action (YYYYMMDDHHNNSS)
User	(YES)	String	user	User. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication	(YES)	String	usertoken	According to the method chosen – fixed or MD5. Only required in case to be sent to the PMS.
Action	YES	String	action	MSGTXT
Hotel	(YES)	String	property	Hotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Room	YES	String	room	Room’s ID
Identifier		String	uid	Message Identifier
Message	YES	String	text	Message Text

JSON Example

{
    "datetime": "20150101101112",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "MSGTXT",
    "property": "myhotel",
    "room": "101",
    "uid": 12345,
    "text": "I need help with my luggage"
}