KxEPOS Endpoints
- Alex Cirket (Deactivated)
KxEPOS Web Service Version 2012.0.2.0
Introduction
Kx Guest Accounts
Unlike most PMS systems, Kx does not store the guest account on the room, rather it is held directly against the guest, therefore the charge will always be attributed to the guest wherever they are allocated.
When posting charges to a guest account a via a room, a room search must be performed. This search will return the PERSONID and EVENTMODULEID needed to apply the charge to the account.
Functions
CheckRoomOccupant
Purpose
This function allows external systems to obtain the PERSONID and EVENTMODULEID for a guest staying in a specified room.
Each guest will have a flag against them which denotes if they are allowed to have a bar posting transaction or not. If they are not then the charge should not be posted or their account enabled prior to posting the charge.
Parameters
Name | Type |
| Example |
RoomNumber | string | 101 | |
SiteID | int | 1 (optional, specify 0 for all sites or single site system) | |
AreaID | int | 1 (optional, specify 0 for all areas of a site or single site system) |
Results
The results will contain an Error code/message and an array of BedroomOccupants.
Possible Error Codes
Number Code Text
0 NO_ERROR
1000 CONNECTION_ERROR There has been an error connecting to the database
3001 NO_OCCUPANTS No occupants found for this room
:Error
Purpose
To provide a mechanism of returning to the calling system the success or failure of the system call.
Data members
Name Type Use Example
ErrorNumber int To provide a numerical error code 0, 2000, 2001
ErrorCode enum To provide an enumerated error return NO_ERROR, CONNECTION_ERROR
ErrorText String To provide a textual message of the error There has been a problem connecting to the Kx database”
:BedroomOccupant
Purpose
To provide the details of the occupant of a specified room necessary for posting charges to them.
Data members
Name | Type | Use | Example |
PersonID | Int | To provide the unique ID for the person to which the charge will be applied. This is used in conjunction with the EventModuleID to get a unique stay record. | 1032, 5948 |
EventModuleID | Int | To provide the unique event reference that Kx uses to apply the charge to the individual account. This is used in conjunction with the PersonID to get a unique stay record. | 3948, 3984 |
ArrivalDate | DateTime | To provide the date when the guest was due to arrive. | 2003-09-10T00:00:00.00 |
DepartureDate | DateTime | To provide the date when the guest is due to depart | 2003-09-12T00:00:00.00 |
PersonName | String | To provide the display name of the guest in the room requested. | Mr John Smith |
AllowBarPosting | Bool | To indicate if posting through this interface has been enabled. If this is false then the account must be enabled prior to posting any charges. | True, false |
RoomName | String | To provide the system name of the bedroom | C304 |
FindDelegateByName
Purpose
This function allows a delegate account to be located based upon the name of the delegate only. This will only display delegates who have checked into Kx and have not yet departed. This function will search for people who’s forename or surname starts with the name provided. This function will not handle multiple names (e.g. J Smith), but it will search both names (e.g. Jones will be searched like FN:Jones* or SN:Jones*).
Parameters
Name |
| Type |
| Example |
Name | string | Smith. (this should be a single name only) | ||
SiteID | int | 1 (optional, specify 0 for all sites or single site system) | ||
AreaID | int | 1 (optional, specify 0 for all areas of a site or single site system) |
Results
The results will contain an Error code/message and an array of BedroomOccupants.
Possible Error Codes
Number Code Text
0 | NO_ERROR |
1000 | CONNECTION_ERROR There has been an error connecting to the database |
3002 | NO_DELEGATESFOUND No delegates with this name have been found |
EnableBarPosting
This function allows the remote system to enable the posting of bar charges through the interface. By default guests when they check in do not have the ability to have a bar account charges posted. A room search returns
Parameters
Name | Type |
| Example |
PersonID | int | 101 | |
EventModuleID | int | 2345 |
Results
The results returned will be an Error message as described above in :Error.
Possible Error Codes
Text
0 NO_ERROR
1000 CONNECTION_ERROR There has been an error connecting to the database
2000 INVALID_ROOM_ACCOUNT No valid account found for this ID pair
AddRoomCharge
Purpose
To apply a charge to the guest account following validation of the room account and the ability to receive bar charges. If you want to charge an item to an event, then set the PersonID parameter to 0 and the EventModuleID to the appropriate value.
Parameters
Name | Type | Example |
| Notes |
PersonID | int | 101 | This should be the validated personid | |
EventModuleID | int | 2345 | This should be the validated eventmoduleid | |
ChargeID | string | 10 | This should be a charge code from the calling system. This is then mapped within Kx to a valid Kx charge code. | |
ChargeDescription | string | Pint beer | This is the description which will be displayed on the guests bill. | |
ChargeAmount | double | 1.75 | This is the amount that should be placed upon the guests bill. This is normally including VAT, Kx will then remove the VAT upon posting the charge. This is dependant upon the setup within Kx. | |
ChargeDate | datetime | 25/05/2003 | This is the date that the charge should be |
related to. This is normally the current date.
Results
The return of this function will be an Error message as described above in :Error
Possible Error Codes
Number Code Text
0 NO_ERROR
1000 CONNECTION_ERROR There has been an error connecting to the database
2000 INVALID_ROOM_ACCOUNT No valid account found for this ID pair
2001 INVALID_EVENT No valid event found for this ID
3000 CANNOT_POST_FROM_BAR Posting not allowed by account
4000 INVALID_CHARGETO There has been an error with the charge routing
INVALID_CHARGE There has not been a valid charge mapping found for the supplied code
Actions to take on errors
Number Possible reason for error Action to take
0 No error has occurred Continue with the transaction
1000 The web service has lost connection to the Check connection to database and retry transaction. database, or the database is not currently This is a fatal error which will stop all transactions running. being processed.
2000 An invalid set of ID’s has been passed to Obtain correct id pair for room and repost transaction. the function. This is one or both of the PersonID and or EventModuleID.
2001 An invalid EventModuleID has been Obtain a correct EventModuleID from the room query supplied to the transaction. function.
3000 A posting has been attempted against an Either have the account enabled from the front office account where bar posted has been system or enable the account through the interface. prohibited
4000 The charge routing on the individuals Store transaction for posting once the routing has been account is setup incorrectly. This is a Kx corrected. internal issue and should never occur.
4001 A charge code passed to the posting routine Correct the mapping via the EPOS mapping utility does not have the corresponding mapping within Kx and repost transaction. setup within Kx.
GetCurrentEvents
Purpose
To list all of the events for an (optional) site and area to allow an epos system to display a list to the user.
Parameters
Name Type Example Notes
SiteID int 101 Optional site to be searched
AreaID int 2345 Optional area within a site to be searched
Results
The results will contain an Error code/message and an array of Event Bookings.
Possible Error Codes
Number Code Text
0 NO_ERROR
1000 CONNECTION_ERROR There has been an error connecting to the database
3001 NO_OCCUPANTS No events found for this site/area
GetCurrentOccupants
Purpose
To list all of the current bedroom occupants for an (optional) site and area to allow an epos system to display a list to the user.
Parameters
Name Type Example Notes
SiteID int 101 Optional site to be searched
AreaID int 2345 Optional area within a site to be searched
Results
The results will contain an Error code/message and an array of BedroomOccupants.
Possible Error Codes
Number Code Text
0 NO_ERROR
1000 CONNECTION_ERROR There has been an error connecting to the database
3001 NO_OCCUPANTS No events found for this site/area
Config_ChargeItems
Purpose
To list the currently configured charge items. These are required for the AddRoomCharge endpoint.
Results
Field Name | Data Type | Description | Example |
ChargeID | string | Unique identifier | 10, FOOD |
Description | string | Description of the charge | Miscellaneous Food |
| ChargeTypeID | integer | Unique Kx identifier for a charge type, see Config_ChargeTypes | 3962 |
| ChargeType | string | Charge type description | Catering, standard VAT (gross) |
Config_ChargeTypes
Purpose
To list the Kx charge types, configured in the KxConfiguration application. These are required for the Config_UpdateChargeItem endpoint.
Results
Field Name | Data Type | Description | Example |
ChargeTypeID | integer | Unique Kx identifier for the charge type | 3962 |
Description | string | Description of the charge type | Catering, standard VAT (gross) |
| AnalysisCode | string | Analysis category for the charge type | Catering |
Config_UpdateChargeItem
Purpose
To create or update a charge item. If the ChargeID exists, the item is updated. Otherwise, as long as the ChargeTypeID exists (i.e. is returned by the endpoint Config_ChargeTypes), a new item is created. No error is returned if the supplied ChargeTypeID is invalid.
Parameters
Parameter Name | Data Type | Description | Example |
ChargeID | string | Unique identifier | MISCFOOD |
Description | string | Description for the charge | Miscellaneous Food |
| ChargeTypeID | integer | Unique Kx identifier for a charge type, see Config_ChargeTypes | 3962 |
Results
Field Name | Data Type | Description | Example |
ChargeID | string | Unique identifier, blank if the item was not created and does not exist | MISCFOOD |
Description | string | Description of the charge, blank if the item was not created and does not exist | Miscellaneous Food |
| ChargeTypeID | integer | Unique Kx identifier for a charge type, see Config_ChargeTypes, or 0 if the item was not created and does not exist | 3962 |
| ChargeType | string | Description of the charge type, blank if the item was not created and does not exist |
Config_DeleteChargeItem
Purpose
To delete a charge item. If the ChargeID exists, the item is updated. No error is returned if the supplied ChargeID is invalid.
Parameters
Parameter Name | Data Type | Description | Example |
ChargeID | string | Unique identifier | MISCFOOD |
Results
Field Name | Data Type | Description | Example |
ChargeID | string | Supplied parameter | MISCFOOD |
Description | string | Description of the deleted item, blank if the item did not exist | Miscellaneous Food |
| ChargeTypeID | integer | ChargeTypeID of the deleted item, 0 if the item did not exist | 3962 |
| ChargeType | string | Charge type description of the deleted item, blank if the item did not exist |
Web Service Test System
Details
There is a test environment setup on the internet to test the interface against. The location of this is at the following URL…
http://www.kxonline.co.uk/KxEpos/
From here the WSDL definition can be obtained:
http://www.kxonline.co.uk/KxEpos/KxEPOS.asmx?WSDL
Test Data
There are a number of rooms which can be tested against for charging:
The valid charge codes are as follows
10 Labelled as Bar Charges
20 Labelled as Catering
These do not relate to any specific charge templates and are used for testing purposes only.
The charge codes which are setup relate to the connecting systems charge codes. These are then mapped to Kx charge templates through a mapping mechanism. Prior to implementation of the interface, Kx should be configured to map all of the codes which are currently setup.
Changes
1.01 • Added FindDelegateByName function to allow a delegate account to be located by the name of the person.
• Added RoomName to the BedroomOccupant structure which is returned in the CheckRoomOccupant and FindDelegateByName functions
1.3 • Added GetCurrentEvents and GetCurrentOccupants functions to allow the EPOS system to display a current list of occupants and a current list of events for a specified site/area
2012.0.2.0 • Added configuration endpoints to remove the need for the EPOSConfig application. The items can instead be configured by the 3rd party EPOS system.
Related articles