How can we help?
< All Topics
Print

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:

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
DataRequiredTypeNameValue
Date -TimeYESStringdatetimeDate-Time requirement (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Required according to the type of authentication.
Authentication(YES)StringusertokenToken. Required according to the type of authentication.
ActionYESStringGET_REQUESTObject containing action data
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Response
CodeYESNumberCodeAccording to specified response codes
DescriptionStringDescriptionDescription of the returned code value.
Record ListYESStringACTION_LISTActions and Data Array
ActionsObjectAccording 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": "2015-01-01T10:11:12",
    "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.

DataRequiredTypeNameValue
Date – TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionBOOKING 
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UIDYESStringbooking_uidInternal booking UID, it may or may not match with (public) locator. Mandatory on multi – hotel scenarios
LocatorStringlocatorPublic locator of the booking, if it does not exist, the same value as the ‘id’ field will be sent.
StatusYESStringstatus“expected”, “cancel”, “noshow”,”checkin”, ”checkout”
Room(YES)StringroomRoom name occupied by the booking. Required for the “checkin”, “checkout” status. In case of room move, new room assigned.
Account(YES)StringaccountAccount 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.
ArrivalYESStringarrivalArrival Date-Time in format YYYY-MM-DDTHH:NN:SS.
The Time will be the estimated time.
DepartureYESStringdepartureDeparture Date-Time in format YYYY-MM-DDTHH:NN:SS.
The Time will be the estimated time.
Level(YES)StringlevelGeneric 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)Stringcos_pbxClass 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)Stringcos_tvTV 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)Stringcos_inetInternet profile Access.
Example: A= profile without limit; B=   profile with limitations.Mandatory in case of Internet profile at booking level.
PAXNumberpaxTotal number of occupants
IDENTIFICADOR LISTA DE OCUPANTES.
GUEST_LIST.
GUEST OBJECT.
Guest UIDYESStringuidInternal guest UID
Main guestBooleanmain‘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 stageBooleanadulttrue = adultfalse = children
Account(YES)StringaccountAccount associated with the guest.Mandatory in cases of multi-occupancy.
TitleStringtitleGuest treatment.Recommended for systems that display personalised information. 
NameYESStringnameGuest’s Name
SurnameYESStringsurnameGuest’s Surname
GenderStringgenderGuest’s Gender
Level(YES)StringlevelGuest’s VIP level.Mandatory in case of integration with equipment managing profiles based on VIP level.
LanguageYESStringlanguageGuest’s Language (ISO 639-1)
e-mail(YES)StringemailGuest’s e-mail address.
Mandatory for Mobile Key.
Mobile phone(YES)StringmobileGuest’s mobile phone number. Mandatory for Mobile Key.
Allows contact(YES)Booleanacontacttrue = Allows contactfalse = NOT allow contact. Mandatory for Mobile Key.
Passport(YES)StringpassportGuest’s Passport. Mandatory for equipment requiring user login
Identity card(YES)StringidcardIdentity card. Mandatory for equipment requiring user login
COS PBX(YES)Stringcos_pbxPBX 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 TVStringcos_tvTV 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 INTERNETStringcos_inetInternet 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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionRS
Hotel(YESX)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
StateYESStringstatusAccording 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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionMUR
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
MUR stateYESBooleanactiveEnabled / 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.
DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionCOS
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
RoomYESStringroomRoom’s ID. 
PBX Service Level


YES
Stringcos_pbxPBX Class of Service allowed to the booking.
Example: 0= Deny calls; 1= Allow outgoing calls.
TV Service LevelYESStringcos_tvTV profile service allowed to the Guest.Example: A = Adult profile; 0= Restrict purchases; 1= Allow purchases.
HOTSPOT Service LevelYESStringcos_inetInternet 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.).

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionWMSG
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
Message Waiting state.YESBooleanactiveEnabled / 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)

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionWAKE 
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID.
Action typeYESStringmodeS: Setting up
C: Cancellation
Identifier(YES)StringuidReminder’s unique identifier.
Reminder TimeYESStringwaketimeReminder 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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionDND
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
DND stateYESBooleanactiveEnabled / 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).

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
ActionYESStringactionMSGTXT
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
RoomYESStringroomRoom’s ID
IdentifierStringuidMessage Identifier
MessageYESStringtextMessage 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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only required if MD5 authentication is used.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
ActionYESStringactionPOST
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
Booking UIDStringbooking_uidInternal UID of the associated booking. If not sent, the charge will be made on the account or room indicated.
RoomYESStringroomRoom’s ID
AccountString accountUser 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 chargeYESStringpost_typeP: PBX (Alternative to CALL request)
M: Minibar
T: TV / Video
N: Internet
(-): Others to be defined
ArticleYESStringarticleArticle Code
DescriptionStringdescriptionCharge description
UnitsYESNumericunitsArticle Units
Article price(YES)NumericpricePrice (taxes included) per article unit, required in case total amount is not sent.
Total charge Amount(YES)NumericamountTotal charge amount, taxes included.
Type of TAXStringtaxType of tax’s code that it is included in the charge according PMS codification.

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionRS
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
StateYESStringstatusAccording to values by the PMS, normally combining cleaning status / availability.
WorkerStringmaidWorker’s ID that makes the change.

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionMUR
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
MUR stateYESBooleanactiveEnabled / Disabled (true / false)

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionDND
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID
DND stateYESBooleanactiveEnabled / Disabled (true / false).

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "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:
DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionBILL_REQUEST
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
Booking UIDStringbooking_uidInternal UID of the associated booking. If the data is not sent, it will correspond to the account / room indicated.
RoomYESStringroomRoom’s ID
AccountString accountUser account on which the payment will be made. If the data is not sent, it will correspond to the booking / room indicated.
Response:
DataRequiredTypeNameValue
ITEM LIST IDENTIFIER INVOICEITEM_LISTIdentifier of the array containing the items of the invoice.
BILL ITEM OBJECT
Date – TimeYESStringdatetimeDate-Time of item (YYYY-MM-DDTHH:NN:SS)
ArticleStringarticleArticle code
DescriptionYESStringdescriptionArticle description
Net amountRealnetNet amount of the article
TaxesRealtaxesTaxes charged on the article
TotalYESRealtotalTotal charge including taxes
BILL DATA
Total FacturaRealbill_totalTotal bill including taxes
NotesStringnotesGeneral bill notes

JSON Example

Request
{
    "datetime": "2015-01-01T10:11:12",
    "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
DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionCHECKOUT
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
Booking UIDStringbooking_uidInternal UID of the associated booking. If the data is not sent, it will correspond to the account / room indicated.
RoomYESStringroomRoom’s ID
AccountString accountUser account on which the payment will be made. If the data is not sent, it will correspond to the booking / room indicated.
Response
DataRequiredTypeNameValue
Message to guestStringnotesMessage to the Guest according to the acceptance or rejection of the request.

JSON Example

Request
{
    "datetime": "2015-01-01T10:11:12",
    "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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionCALL
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
RoomYESStringroomRoom’s ID
Type of callYESStringcall_typeO: Outbound call
I: Incoming call (optional)
L: Internal call (optional)
LineStringlineLine’s link used
Number YESStringnumberDestination / origin number
Answer TimeNumericresponseResponse time (seconds)
Call DurationYESNumericdurationCall duration (0 = not answered)
Call Accounting UnitsNumericunitsCall Accounting units (Outbound calls)
Phone call costRealpricePhone 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": "2015-01-01T10:11:12",
    "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).

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionWAKE 
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios
RoomYESStringroomRoom’s ID.
Action typeYESStringmodeS: 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
IdentifierStringuidReminder’s unique identifier. 
Reminder TimeYESStringwaketimeReminder Date-Time (YYYY-MM-DDTHH:NN;SS)

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "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.

DataRequiredTypeNameValue
Date-TimeYESStringdatetimeDate-Time of the action (YYYY-MM-DDTHH:NN:SS)
User(YES)StringuserUser. Only mandatory if MD5 authentication is used and sent to PMS.
Authentication(YES)StringusertokenAccording to the method chosen – fixed or MD5.
Only required in case to be sent to the PMS.
ActionYESStringactionMSGTXT
Hotel(YES)StringpropertyHotel’s ID for each installation. Mandatory on multi – hotel scenarios.
RoomYESStringroomRoom’s ID
IdentifierStringuidMessage Identifier
MessageYESStringtextMessage Text

JSON Example

{
    "datetime": "2015-01-01T10:11:12",
    "user": "user1",
    "usertoken": "61e7c7371170a948eaf63fa578840025",
    "action": "MSGTXT",
    "property": "myhotel",
    "room": "101",
    "uid": 12345,
    "text": "I need help with my luggage"
}

Previous 3. char pmslink HTTPCNX API FOR GUEST APP
Next 5. char pmslink KEYCARD API
Table of Contents