How can we help?
< All Topics
Print

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:

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

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:

DATAMandatoryTypeNameValue
Result CodeYesintegercode0 : OK.100 – 199 : Errors requiring retry.200 – 299 : Errors that do NOT require a retry.
DescriptionstringdescriptionResult 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).

DATAMandatoryTypeNameValue
Date –TimeYesDate/timedatetimeDate-Time requirement (YYYY-MM-DDTHH:NN:SS)
UserOnly MD5 authenticationstringuserUser of MD5 authentication.
AuthenticationOnly MD5 or fixed authentication stringusertokenPassword/token according to the method chosen – fixed or MD5.
MessageYesstringmessageType of message
ActionYesstringactionActions 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.
HotelOnly in case of multi – hotelstringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UIDYesstringbooking_uidInternal booking UID, it may or may not match with (public) locator.
LocatorNostringlocatorPublic locator of the booking, if it does not exist, the same value as the ‘id’ field will be sent.
StateYesstringstateBooking status:

Expected: On hold / Stand-by.
Cancel: Booking cancelled.
No_show: Guest not presented.
Checkin: Hosted guest.
Checout: Departure of guest and end of occupancy.
RoomYesstringroomRoom 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 RoomOnly in case of action ‘MOVE’stringorigin_roomPrevious room of the reservation.In case of booking in ‘EXPECTED’ status it can be NULL if no room was assigned.
AccountOnly in case of multi – occupancystringaccountAccount associated to the booking. If the PMS treats them at occupant level, it is the account of the main guest.
ArrivalYesDate/timearrivalArrival Date-Time in format YYYY-MM-DDTHH:NN:SS.
The time will be the estimated time.
DepartureYesDate/timedepartureDeparture Date-Time in format YYYY-MM-DDTHH:NN:SS.
The Time will be the estimated time.
LevelNostringlevelGeneric VIP level of the booking. If the PMS treats them at occupant level, it must be used the VIP level of the main guest.
PaxOnly in case of multi-occupant PMS interfacesintegerpaxNumber of occupants of the booking.



Identifier of occupants.
Guest list.
Guest object array indicator.
Guest UIDYesstringuidInternal guest UID
Main guestNobooleanmain‘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 stageNobooleanadult‘true’ = adult‘false’ = children
AccountMandatory in cases of multi-occupancystringaccountAccount associated with the guest.
TitleNostringtitleGuest treatment.
NameYesstringnameGuest’s Name
SurnameYesstringsurnameGuest’s Surname
GenderNostringgenderGuest’s Gender. Data received from PMS and transferred to value coordinated with the integrated system.
LevelNostringlevelGuest’s VIP level.
LanguageYesstringlanguageGuest’s Language (ISO 639-1)
e-mailNostringemailGuest’s e-mail address.
Mobile phoneNostringmobileGuest’s mobile phone number. 
Allows contactNobooleanacontacttrue = Allows contactfalse = NOT allow contact. 
PassportNostringpassportGuest’s Passport. 
Identity cardNostringidcardIdentity card. 
NationalityNostringnationalityNationality (ISO 3)
Birth dateNoDatebirth_dateBirth date in format YYYY-MM-DD
OccupationNostringoccupationOccupation
Permanent AddressNostringpaddressPermanent address
Postal codeNostringpcodePostal code
CityNostringrcityCity of residence
StateNostringrstateState of residence
CountryNostringrcountryCountry 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.

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:NN:SS)
UserOnly MD5 authenticationstringuserUser of MD5 authentication.
AuthenticationOnly MD5 or fixed authentication stringusertokenPassword/token according to the method chosen – fixed or MD5.
MessageYesstringmessageHOUSEKEEPING
ActionYesstringactionCLEAN
HotelOnly in case of multi – hotelstringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UIDYesstringbooking_uidInternal booking UID, it may or may not match with (public) locator.
RoomYesstringroomRoom 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.).

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:NN:SS)
UserOnly MD5 authenticationstringuserUser of MD5 authentication.
AuthenticationOnly MD5 or fixed authentication stringusertokenPassword/token according to the method chosen – fixed or MD5.
MessageYesstringmessageMESSAGE
ActionYesstringactionWAIT
HotelOnly in case of multi – hotelstringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UIDYesstringbooking_uidInternal booking UID, it may or may not match with (public) locator.
RoomYesstringroomRoom 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.

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:NN:SS)
UserOnly MD5 authenticationstringuserUser of MD5 authentication.
AuthenticationOnly MD5 or fixed authentication stringusertokenPassword/token according to the method chosen – fixed or MD5.
MessageYesstringmessageMESSAGE
ActionYesstringactionTEXT
HotelOnly in case of multi – hotelstringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UIDYesstringbooking_uidInternal booking UID, it may or may not match with (public) locator.
RoomYesstringroomRoom name occupied by the booking. 
IDNostringuidMessage unique ID
MessageYesstringtextText 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
DataMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:NN:SS)
UserOnly MD5 authenticationstringuserUser of MD5 authentication.
AuthenticationOnly MD5 or fixed authentication stringusertokenPassword/token according to the method chosen – fixed or MD5.
MessageYesstringmessageDATA_REQUEST
HotelNostringpropertyHotel’s ID for each installation to return data.
In case of multi- hotel environment, NULL value will return pending messages from all hotels.
Reply
DataMandatoryTypeNameValue
Data list identifierYesstringDATA_LISTIdentifier 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.

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:NN:SS)
MessageYesstringmessageDND
HotelOnly in case of multi – hotelstringpropertyHotel’s ID.
RoomYesstringroomRoom name occupied by the booking. 
ActionYesbooleanstatetrue = 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.

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:NN:SS)
MessageYesstringmessageHOUSEKEEPING
ActionYesstringactionMUR
HotelOnly in case of multi – hotelstringpropertyHotel’s ID.
RoomYesstringroomRoom 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.

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:MM:SS)
MessageYesstringmessageWAKEUP
ActionYesstringactionSET: Set reminder (alarm clock)
Cancel: Cancel reminder
HotelOnly in case of multi – hotelstringpropertyHotel’s ID.
RoomYesstringroomRoom name occupied by the booking. 
Wake timeOnly in case of SET actionDate-timewake_timeDate 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.

DATAMandatoryTypeNameValue
Date – TimeYesDate-TimedatetimeDate-Time message (YYYY-MM-DDTHH:MM:SS)
MessageYesstringmessageMESSAGE
ActionYesstringactionTEXT
HotelOnly in case of multi – hotelstringpropertyHotel’s ID.
RoomYesstringroomRoom name occupied by the guest. 
Message YesstringtextText 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"
}
Previous 2. char pmslink HTTPCNX API FOR PBX
Next 4. char pmslink HTTPPMS EQUIPMENT BASIC API
Table of Contents