PMS API Guide

Property Management System or PMS is a software application used in the hospitality industry to automate some hotel functions such as guest booking, guest details, etc…

Grandstream UCM6XXX series have integrated multiple PMS platforms (i.e. HSC, Mitel, HMobile) providing following hospitality features: Changing Display Name, Permission, Call forwarding, DND and more.

PMS API is supported to offer Hotel action with the UCM62xx & UCM6510 & UCM63xx/A via HTTPS API (or HTTP only for UCM62xx/UCM6510). The API format is defined by Grandstream and this guide will help users configure and authenticate in order to use PMSAPI

This guide will focus on the PMS API old configuration and for more details about the new supported API, please refer to the following link:

https://www.grandstream.com/sites/default/files/Resources/UCM_API_Guide.pdf

CONNECTION AND AUTHENTICATION

PMSAPI works on HTTPS (or HTTP only for UCM62xx/UCM6510), the URL format syntax is as follows:

HTTPS://[UCMIP]:[Port]/pmsapi?token=[token]&data=[value]&format=xml

From this URL we can see three needed parameters: Token, Data and Format where:

Token:	Token is used for PMSAPI Authentication when doing actions such as check-in, check-out.., Refer to [Authentication Token]
Format:	Format that is used to mark which format the data is, such as xml;
Data:	Data the action data that will be used. Refer to [DATA FORMAT ]

For example:

https://192.168.124.63:8443/pmsapi?token=63E780C3F321D13109C71BF81805476E&format=xml&data=<pms_data_request><checkin><address>1100</address><name>jjkkl</name><extension>1100</extension><datein>20180202</datein><dateout>20180203</dateout></checkin></pms_data_request>

Authentication

The PMSAPI needs two authentication steps, one, which is used to connect, and the other for data.

Step1:

Under UCM’s WebGUI go to Value-added Feature 🡪 API Configuration 🡪 HTTPS API Settings(Old) 🡪 Basic Settings, check Enable option under Basic Settings, then Enable PMSAPI as well, users may also change and configure other fields such as Username and password please check below screenshot.

Step 2:

Under the UCM’s WebGUI go to Value-added Feature 🡪 PMS 🡪 Basic Settings , choose PMS Module as PMSAPI and configure the username and password, we can also go to Room Status to create rooms or go to Wakeup Service, Mini Bar, Maid to configure them as well depending on the users requirement. Then save and apply the changes.

Connection

To authenticate the connection, we should use the username and password on the API Configuration Page, in order to do Digest authentication.

Authentication Token

This token is used on the URL, and created with the username and password configured on the PMS page, use md5 to encrypt username and password.

Token = MD5(username+password) 

Example:

And then using any MD5 generator we can generate the authentication token as showing in below figure

DATA FORMAT

Below is data format of all supported PMSAPI actions, this can be updated in future firmware.

Responses

The response of PMSAPI includes a code and description. For example:

If an action is successful, it will get the response message “[0] SUCCESS !”.

Other codes and descriptions can be found on below table.

Code	Description
26	First name or last name too long !
25	First name or last name too long !
24	Dest address already checked in !
23	Dest address not exist !
22	Cleaning or repairing, cannot check in or be mov to !
21	PMSAPI not enable !
20	Not checked in !
19	Already checked in !
18	Address error !
17	Address and room not match !
16	Auth error !
15	In data error !
14	Format error !
13	No support action !
12	XML data error !
0	Success !
-100	Success, but language error, not set !
-9	Action error !

API COMMANDS AND EXAMPLES

In this chapter, we will show different actions as well as related examples and description:

Check-in

Check-in action is used to notify the arrival a Guest, below table shows the data and values to be configured.

Data	Description
Address	Room or extension, identifier recognized by destination
Room	Room number. It may be equal, or not, to the address value
Account	Guest account number
firstname	Guest firstname
Lastname	Guest lastname
Language	Guest language
Vipcode	Guest VIP code
Datein	Arrival date, format YYYY/MM/DD hh:mm
Dateout	Departure date, format YYYYMMDD hh:mm
Credit	Guest credit money.
Cos	Call permission 1 < 2 < 3 < 4
Cidnumber	Cid number

• Example

<pms_data_request>
<checkin>
 <address>1100</address>
 <room>1100</room>
 <account>1100</account>
 <firstname>John</firstname>
 <lastname>Doe</lastname>
 <language>EN</language>
 <vipcode>2</vipcode>
 <datein>2010/01/01 11:00</datein>
 <dateout>2010/01/07 13:00</dateout>
 <credit>9999900</credit>
 <cidnumber>11001100</cidnumber>
 <cos>3</cos>
</checkin>
</pms_data_request>

Check-out

Check-out action is used to notify the departure a Guest, below table shows the data and values to be configured

Data	Description
Address	Source address, Room or extension, identifier recognized by destination
Room	Source room, Room number, It may be equal, or not, to the address value

• Example

<pms_data_request>
<checkout>
 <address>1100</address>
 <room>1100</room>
</checkout>
</pms_data_request>

Update

Update action is used to update data of a Guest, below table shows the data and values to be configured

Data	Description
Address	Room or extension, identifier recognized by destination
Room	Room number, It may be equal, or not, to the address value
Account	Guest account number
firstname	Guest firstname
Lastname	Guest lastname
Language	Guest language
Vipcode	Guest VIP code
Datein	Arrival date, format YYYY/MM/DD hh:mm
Dateout	Departure date, format YYYYMMDD hh:mm
Credit	Guest credit money.
Cos	call permission 1 < 2 < 3 < 4
Cidnumber	Cid number

• Example

<pms_data_request>
<update>
 <address>1100</address>
 <room>1100</room>
 <account>1100</account>
 <firstname>John</firstname>
 <lastname>Doe</lastname>
 <language>EN</language>
 <vipcode>2</vipcode>
 <datein>20100101</datein>                                                
 <dateout>20100107</dateout>
 <credit>9999900</credit>
 <cidnumber>11001100</cidnumber>
 <cos>3</cos>
</update>
</pms_data_request>

Mov

Mov action is used to notify the room change of a Guest, below table shows the data and values to be configured.

Data	Description
address	Source address, Room or extension, identifier recognized by destination
room	Source room, Room number, It may be equal, or not, to the address value
d_address	Destination address, Room or extension, identifier recognized by destination
d_room	Destination room, Room number, It may be equal, or not, to the address value

• Example

<pms_data_request>
<mov>
 <address>1046</address>
 <room>1046</room>
 <d_address>1100</d_address>
 <d_room>1100</d_room>
</mov>
</pms_data_request>

Wakeup

Wakeup action is used to notify the guest for wakeup call, below table shows the data and values to be configured

Data	Description
address	Room or extension, identifier recognized by destination
room	Room number, It may be equal, or not, to the address value
w_action	Action ID,1 = set. 0 = cancel
w_mode	Mode: 1 = single (default). 2 = daily.
w_date	wakeup date format YYYYMMDD
w_time	wakeup time format HHMM

• Example

<pms_data_request>
<wakeup> 
 <address>1100</address>
 <room>1100</room> 
 <w_action>1</w_action> 
 <w_mode>1</w_mode> 
 <w_date>20140101</w_date>
</wakeup> 
</pms_data_request>

SUPPORTED DEVICES

The following table shows devices supporting PMS API feature:

Model	Supported	Firmware
UCM6200	Yes	1.0.9.10 or higher
UCM6510	Yes	1.0.9.10 or higher
UCM63xx	Yes	1.0.2.25 or higher
UCM63xxA	Yes	1.0.7.9 or higher