3. char pmslink HTTPCNX API FOR GUEST APP

12/05/2022.
Review of formats and fields.

15/02/2020.
Added booking message for booking and occupancy events.

20/12/2019.
MD5 examples fixed.

25/11/2019.
New version of Specification’s document.

Description

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

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.

The integration is done according to the needs of Guest App system:

Transmitting to the guest app system hotel booking and occupancy events.

PMS > Guest App systems

• EXPECTED, booking creation.
• CHECKIN, guest’s arrival.
• UPDATE, modification of guest’s data.
• MOVE, guest room change.
• CHECKOUT, guest’s departure.
• CANCEL, booking cancellation.
• NO SHOW, guest not present.

Providing guest data and their stay information.

Transmitting to the Guest App system data regarding the stay/hotel occupancy status.

PMS > Guest App system

• Room cleaning done.
• Activation / deactivation for message on hold indicator.
• Hotel messages for the guest.

Sent to PMS and/or other hotel equipment and systems.

Guest App system -> PMS / housekeeping, services, PBX, TV, etc

• Do not disturb.
• Room cleaning request.
• Reminder programming.
• Message to the hotel.
• Through http SERVER API
  • Hotel service request
  • Incident response to technical services
  • Invoice data request
  • Express checkout request

Interacting with the hotel Access System to facilitate the management of digital keys on mobile terminals.

Guest App system < > Hotel Access System server.

Through http SERVER API

• Sending digital key token in the booking messages when rooms are assigned.
• Sending to the System Access server the request for sending key to the terminal.

The integration through char pmslink supplies the integrated system a common interface that allows the integration of any PMS and other systems. However, any particularities and limitations of each PMS depending on its functionality and data provided, needs to be taken into account. 

The data exchanged will depend on the following points:

• Data provided by each PMS according with the various interfaces active from the PMS.
• Data provided by the interface(s) active on the hotel. 
• Data that the hotel allows to share with third parties.

This document includes all the specifications in order to integrate char pmslink, using its API HTTPCNX GUEST BASIC for Guest App, by linking to a HTTP server and exchanging data in JSON format. This API is considered as public domain.

In general terms, it is possible to expand this API in cases that it is required, and the PMS system supports the functionality or provides the needed information.

The extended version of this API, http SERVER API will require additional connection to pmslink http server of pmslink WebSocket.

---

Development process, testing, certification and realease

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 integrations@char.es in order to start the process and obtain more extended information about the process itself.
• We establish a contact in order to establish the scope of the integration and the particularities of the integration that will allow the process to move forward.
• The system to be integrated starts the development. Throughout the whole process, char will provide support to its developers or technicians, as well as the test elements that are assessed as indicated according to the scope set.
• Once the development has been completed, joint tests are carried out to validate the integration, its scope and the specific driver for the integrated system that will be included in the pmslink installer.
• Validation is formalised through the standard char technical collaboration agreement:  https://charpmslink.com/download/doc/templates/char_technology_agreement_template.pdf and/or with the specific document of the integrated system it proposes.
• From this point onwards, it will be considered as an integrated system for all intents and purposes, being released to public, including it in the integrated systems’ list and notifying through the common news channels. The integrated system 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.

---

Data flow and basic functionalities

Bookings and occupancy

PMSLINK > Integrated system

The basic information exchange is related to the reservation made by a guest and occupancy.

The integrated system will use this event to manage according to its needs, saving guest and occupation data for immediate or future actions such as system activations, functions and permissions, welcome messages, customization, specific configurations, etc.

In all cases a BOOKING message is sent to the integrated system, containing the data of the booking made an its occupants. 

The format and structure of this data will be similar for all BOOKING messages sent.

Each BOOKING message shall indicate for which it is sent:

• EXPECTED Action: Reports the creation of the booking.
• CANCEL Action: Reports he cancellation of the booking.
• CHECKIN Action: Reports the guest arrival (check-in).
• UPDATE Action: Reports changes in the booking and/or its occupants.
• MOVE Action: Reports room change.
• CHECKOUT Action: Reports de the guest’s departure (check-out), finishing the occupancy.

The sending off these messages is configurable in pmslink and will always be subject to the notifications and data provided by the PMS or the interface available in the hotel.

Stay

During the stay (booking in CHECKIN status) both the integrated system and the PMS or other systems will exchange information related to the guest, such as information or to execute actions. 

PMSLINK > Integrated system

• HOUSEKEEPING message, CLEAN action: At the moment of room cleaning.
• MESSAGE message, WAIT action: When a message is waiting for the guest at the reception desk.
• MESSAGE message, TEXT action: When sending text message to the guest.

Integrated system > PMSLINK (PMS, Housekeeping, Services, PBX, TV, etc.)

• DND message, ON / OFF actions: At the moment of activating / deactivating do not disturb.
• HOUSEKEEPING message, MUR action: When requesting room cleaning.
• WAKEUP message, SET / CANCEL action: When programming / cancelling the reminder (wakeup call).
• MESSAGE message, TEXT action: When sending a text message to the hotel.

---

Connection and data format

pmslink through HTTPCNX GUEST BASIC will link with the integrated system 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://sample.api.com/booking/checkin?hotelid:123456
• Common for all ACTIONS and requests. Containing the ACTION as parameter and the hotel ID in case of multi-hotel scenarios. Example: https://sample.api.com?message=booking&action=checkin&hotelid:123456
• Common for all ACTIONS and requests. ACTION and the rest of parameters will be sent as message.
  Example: https://sample.api.com

The embedded system will decide the format at the time of setting the integration details beforehand. For char pmslink, it is a configurable parameter so it can be changed at any time.

Data formatting:

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

The ‘number’ format will be using ‘integer’ + separation (‘.’) + ‘decimal’ using two digits.  Example: 123.50

The ‘date/time’ format shall be YYYY-MM-DDTHH:NN:SS and will refer to the local time (and time zone) for each installation. Ex: 01/01/2019 at 10:30 = 2019-01-01T10:30:00

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

---

Authentication

The embedded system will decide the type of authentication to be used and where it will be included among the possible types and locations:

None.

HTTP basic authentication

• According to https://datatracker.ietf.org/doc/html/rfc2617.
• Location: Authorization header.

FIXED TOKEN:

• Authentication done using an agreed token between the pmslink and the integrated system in general, or for each installation:
• Example: 12345-12345-12345-12345
• Location: Authorization header o message body.

MD5:

• The authentication will be done using an encrypted token using MD5 algorithm generated using: 
• User + time stamp (YYYYMMDDHHNNSS) + password for each request. 
• Example: User ‘user1’, date ‘20150101101112’, password ‘password1’ = MD5(user120150101101112password1) = 61e7c7371170a948eaf63fa578840025.
• Location: Message body.
• Password is an internal value, agreed as general use or unique on each installation but not sent as data.

---

Requests and Responses

HTTP commands:

All the requests will be done using POST commands in all cases:

• Communicate actions to the integrated system server (checkin, checkout, etc.).
• Request data to the integrated system server (GET_DATA).

Confirmations and replies:

All responses will generate HTTP 200 code. 

The result will be indicated in the body of the response, based on the following structure:

DATA	Mandatory	Type	Name	Value
Result Code	Yes	integer	code	0 : OK.100 – 199 : Errors requiring retry.200 – 299 : Errors that do NOT require a retry.
Description		string	description	Result description

EXAMPLE: POST

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

Connection control:

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

• Physical linking errors with the integrated system server.
• Actions that return the codes: 100 – 199. 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 connection errors, char pmslink will retry to resend in a programmed frequency all the information on that queue.

---

PMS > Integrated System

Booking message

All booking messages are based on the same data structure, regardless of the actions involved.

Certain actions may send additional data (e.g. room move indicates room of origin).

DATA	Mandatory	Type	Name	Value
Date –Time	Yes	Date/time	datetime	Date-Time requirement (YYYY-MM-DDTHH:NN:SS)
User	Only MD5 authentication	string	user	User of MD5 authentication.
Authentication	Only MD5 or fixed authentication	string	usertoken	Password/token according to the method chosen – fixed or MD5.
Message	Yes	string	message	Type of message
Action	Yes	string	action	Actions on the booking: EXPECTED CANCEL: Informs about the cancellation of the booking. UPDATE: Reports changes to the booking and/or its occupants. CHECKIN: Informs about the guest arrival. MOVE: Informs about a room change. CHECKOUT: Informs of the guest’s departure, putting an end to the occupancy.
Hotel	Only in case of multi – hotel	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.
Locator	No	string	locator	Public locator of the booking, if it does not exist, the same value as the ‘id’ field will be sent.
State	Yes	string	state	Booking status: Expected: On hold / Stand-by. Cancel: Booking cancelled. No_show: Guest not presented. Checkin: Hosted guest. Checkout: Departure of guest and end of occupancy.
Room	Yes	string	room	Room name occupied by the booking. In case of room move, new room assigned.It may be NULL in case of booking in state other than ‘CHECKIN’ or ‘CHECKOUT’ and room not assigned.
Origin Room	Only in case of action ‘MOVE’	string	origin_room	Previous room of the reservation.In case of booking in ‘EXPECTED’ status it can be NULL if no room was assigned.
Account	Only in case of multi – occupancy	string	account	Account associated to the booking. If the PMS treats them at occupant level, it is the account of the main guest.
Arrival	Yes	Date/time	arrival	Arrival Date-Time in format YYYY-MM-DDTHH:NN:SS. The time will be the estimated time.
Departure	Yes	Date/time	departure	Departure Date-Time in format YYYY-MM-DDTHH:NN:SS. The Time will be the estimated time.
Level	No	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.
Pax	Only in case of multi-occupant PMS interfaces	integer	pax	Number of occupants of the booking.
IDENTIFIER LIST OF OCCUPANTS			GUEST_LIST	GUEST OBJECT array indicator
GUEST OBJECT
Guest UID	Yes	string	uid	Internal guest UID
Main guest	No	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	No	boolean	adult	‘true’ = adult‘false’ = children
Account	Mandatory in cases of multi-occupancy	string	account	Account associated with the guest.
Title	No	string	title	Guest treatment.
Name	Yes	string	name	Guest’s Name
Surname	Yes	string	surname	Guest’s Surname
Gender	No	string	gender	Guest’s Gender. Data received from PMS and transferred to value coordinated with the integrated system.
Level	No	string	level	Guest’s VIP level.
Language	Yes	string	language	Guest’s Language (ISO 639-1)
e-mail	No	string	email	Guest’s e-mail address.
Mobile phone	No	string	mobile	Guest’s mobile phone number.
Allows contact	No	boolean	acontact	true = Allows contactfalse = NOT allow contact.
Passport	No	string	passport	Guest’s Passport.
Identity card	No	string	idcard	Identity card.
Nationality	No	string	nationality	Nationality (ISO 3)
Birth date	No	Date	birth_date	Birth date in format YYYY-MM-DD
Occupation	No	string	occupation	Occupation
Permanent Address	No	string	paddress	Permanent address
Postal code	No	string	pcode	Postal code
City	No	string	rcity	City of residence
State	No	string	rstate	State of residence
Country	No	string	rcountry	Country of residence

JSON Example

pmslink Request

{
    "datetime": "2015-01-01T10:11:12",
      
    "user": "user1",
    "usertoken": "61a7c7371170a94aefa578840025",

    "message": "BOOKING", 
    "action": "CHECKIN",
    "property": "myhotel",
    "booking_uid": "qwertyu-1234",
    "state": "checkin",
    "room": "100",
    "account": "123456",
    "arrival": "2015-01-01T10:00:00",
    "departure": "2015-01-06T12:00:00",
    "level": "1",
    "pax": 1,

    "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",
                        "acontact": true,
                        "passport": "1234567890",
                        "idcard": "1234567890",
                        "nationality": "ESP",
                        "birth_date": "2000-01-01",
                        "occupation": "engineer",
                        "paddress": "Pablo Iglesias 56", 
                        "pcode": "08302",
                        "rcity": "Mataro",
                        "rstate": "Barcelona",
                        "rcountry": "Spain"
                    }]
 
}

Integrated system Response

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

Housekeeping message

Sent when the daily cleaning of the room takes place, informing the guest of its availability. Only sent for bookings in ‘checkin’ status.

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:NN:SS)
User	Only MD5 authentication	string	user	User of MD5 authentication.
Authentication	Only MD5 or fixed authentication	string	usertoken	Password/token according to the method chosen – fixed or MD5.
Message	Yes	string	message	HOUSEKEEPING
Action	Yes	string	action	CLEAN
Hotel	Only in case of multi – hotel	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.
Room	Yes	string	room	Room name occupied by the booking.

JSON Example

pmslink Request

{
    "datetime": "2015-01-01T10:11:12",
      
    "user": "user1",
    "usertoken": "61a7c7371170a94aefa578840025",

    "message": "HOUSEKEEPING", 
    "action": "CLEAN",
    "property": "myhotel",
    "booking_uid": "qwertyu-1234",
    "room": "100"
}

Integrated system Response

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

 

Wait message

Sent through char pmslink to the integrated systems reporting that there are messages to be transmitted/sent by the guest (reception, indicators for voicemail, TV, multimedia systems, etc.).

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:NN:SS)
User	Only MD5 authentication	string	user	User of MD5 authentication.
Authentication	Only MD5 or fixed authentication	string	usertoken	Password/token according to the method chosen – fixed or MD5.
Message	Yes	string	message	MESSAGE
Action	Yes	string	action	WAIT
Hotel	Only in case of multi – hotel	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.
Room	Yes	string	room	Room name occupied by the booking.

JSON Example

pmslink Request

{
    "datetime": "2015-01-01T10:11:12",
      
    "user": "user1",
    "usertoken": "61a7c7371170a94aefa578840025",

    "message": "MESSAGE", 
    "action": "WAIT",
    "property": "myhotel",
    "booking_uid": "qwertyu-1234",
    "room": "100"
}

Integrated system Response

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

Text message

Sent through char pmslink to the integrated systems to transmit messages to the guest using TV systems, multimedia devices, guest’s app, etc.

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:NN:SS)
User	Only MD5 authentication	string	user	User of MD5 authentication.
Authentication	Only MD5 or fixed authentication	string	usertoken	Password/token according to the method chosen – fixed or MD5.
Message	Yes	string	message	MESSAGE
Action	Yes	string	action	TEXT
Hotel	Only in case of multi – hotel	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.
Room	Yes	string	room	Room name occupied by the booking.
ID	No	string	uid	Message unique ID
Message	Yes	string	text	Text message

JSON Example

pmslink Request

{
    "datetime": "2015-01-01T10:11:12",
      
    "user": "user1",
    "usertoken": "61a7c7371170a94aefa578840025",

    "message": "MESSAGE", 
    "action": "TEXT",
    "property": "myhotel",
    "booking_uid": "qwertyu-1234",
    "room": "100",
    "uid": "12345",
    "text": "Welcome to the hotel"
}

Integrated system Response

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

---

Integrated System > PMS

Data request message

Since in this API the integrated system assumes the role of server, the sending of data and actions will be carried out using PULL technology.

In this way, pmslink requests data and actions to be carried out that are transmitted from the integrated system.

For this purpose, the integrated system must maintain a queue of messages and data pending to be sent.

pmslink, through the DATA_REQUEST message, requests data from the queue maintained by the integrated system, which returns them as a response to the http request and removes them from the queue of data pending to be sent.

In the case of having messages to be processed, the integrated system will provide (maximum) 100 messages per request and will delete them from its queue list.

In the case of having and empty list, it will confirm the processing using the code HTTP 200 (OK) without including data into the reply.

The data and actions returned by the embedded system can be of different types:

•  Activate / deactivate Do Not Disturb
• Request room cleaning
• Activate / deactivate reminder (alarm clock)
• Send message to the hotel

This implies that the data structure will be specific for each type of action and a single response will include the pending data as an array, identifying its type as a parameter of the structure of each data type.

Request

Data	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:NN:SS)
User	Only MD5 authentication	string	user	User of MD5 authentication.
Authentication	Only MD5 or fixed authentication	string	usertoken	Password/token according to the method chosen – fixed or MD5.
Message	Yes	string	message	DATA_REQUEST
Hotel	No	string	property	Hotel’s ID for each installation to return data. In case of multi- hotel environment, NULL value will return pending messages from all hotels.

Reply

Data	Mandatory	Type	Name	Value
Data list identifier	Yes	string	DATA_LIST	Identifier of array containing list of objects

Data and structure will depend on each type of action or data sent

JSON Example

pmslink Request

{
    "datetime": "2015-01-01T10:11:12",
      
    "user": "user1",
    "usertoken": "61a7c7371170a94aefa578840025",

    "message": "DATA_REQUEST", 
    "property": "myhotel",
}

Integrated system Response

{
    "code": 0,
    "description": "Success"

    "DATA_LIST": 

    [ array of data and actions ]
}

DND message

Do Not Disturb (DND) action sent by the integrated system in response to DATA_REQUEST.

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:NN:SS)
Message	Yes	string	message	DND
Hotel	Only in case of multi – hotel	string	property	Hotel’s ID.
Room	Yes	string	room	Room name occupied by the booking.
Action	Yes	boolean	state	true = Activatefalse = Deactivate

JSON Example

DND object contained in the array DATA_LIST

{
    "datetime": "2015-01-01T10:11:12",
    "message": "DND",
    "property": "myhotel",
    "room": "100",
    "state": true
}

Make Up Room message

Room cleaning request sent by the integrated system in response to DATA_REQUEST.

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:NN:SS)
Message	Yes	string	message	HOUSEKEEPING
Action	Yes	string	action	MUR
Hotel	Only in case of multi – hotel	string	property	Hotel’s ID.
Room	Yes	string	room	Room name occupied by the booking.

JSON Example

MUR object contained in the array DATA_LIST

{
    "datetime": "2015-01-01T10:11:12",
    "message": "HOUSEKEEPING",
    "action": "MUR",
    "property": "myhotel",
    "room": "100"
}

Wake Up message

Reminder schedule/cancellation request sent by the integrated system in response to DATA_REQUEST. Actions to be performed on PBX systems, TV, reception, etc.

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:MM:SS)
Message	Yes	string	message	WAKEUP
Action	Yes	string	action	SET: Set reminder (alarm clock) Cancel: Cancel reminder
Hotel	Only in case of multi – hotel	string	property	Hotel’s ID.
Room	Yes	string	room	Room name occupied by the booking.
Wake time	Only in case of SET action	Date-time	wake_time	Date and Time of the reminder (YYYY-MM-DDTHH:MM:SS)

JSON Example

WAKE UP object contained in the array DATA_LIST

{
    "datetime": "2015-01-01T10:11:12",
    "message": "WAKEUP",
    "action": "SET",
    "property": "myhotel",
    "room": "100",
    "wake_time": "2015-01-02T08:00:00"
}

Guest message

Guest message sent by the integrated system in response to DATA_REQUEST.

DATA	Mandatory	Type	Name	Value
Date – Time	Yes	Date-Time	datetime	Date-Time message (YYYY-MM-DDTHH:MM:SS)
Message	Yes	string	message	MESSAGE
Action	Yes	string	action	TEXT
Hotel	Only in case of multi – hotel	string	property	Hotel’s ID.
Room	Yes	string	room	Room name occupied by the guest.
Message	Yes	string	text	Text of the message

JSON Example

GUEST MESSAGE object contained in the array DATA_LIST

{
    "datetime": "2015-01-01T10:11:12",
    "message": "MESSAGE",
    "action": "TEXT",
    "property": "myhotel",
    "room": "100",
    "text": " I need help with my luggage"
}