PMS API Guide

  • Updated on September 15, 2022

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>

This is supported by UCM63xx/A starting firmware 1.0.9.10. This guide will be focusing on the PMS API old configuration.

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.

Figure 1: HTTPS API Settings(Old)

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.

Figure 2: PMS Basic Settings

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:

Figure 3: PMS Basic Settings

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

Figure 4: Generating Auth Token

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.

CodeDescription

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 !

Table 1: Data format

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.

DataDescription

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

Table 2: Check-in
  • Example
</pms_data_request>
<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>

Check-out

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

DataDescription

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

Table 3: Check-out
  • Example
</pms_data_request>
<pms_data_request>
<checkout>
 <address>1100</address>
 <room>1100</room>
</checkout>

Update

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

DataDescription

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

Table 4: Update
  • 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.

DataDescription

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

Table 5: Mov
  • 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

DataDescription

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

Table 6: Wakeup
  • 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:

ModelSupportedFirmware

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

Table 7: Supported Devices

Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Comment

We use cookies in order to give you the best possible experience on our website. By continuing to use this site, you agree to our use of cookies.
Accept