ibelsaDocumentation
cashAPI
Documentation v. 2.2
---
created: 2021-02-10T00:00
updated: 2024-09-12T09:35
author: Simon Triem
title: Documentation v. 2.2
---
# Documentation v. 2.2
## Overview
This API enables external Cash Register / POS systems to exchange data with ibelsa.rooms.
It describes the way of reading data (e.g. get a list of inhouse rooms with guests) or writing data (e.g. charge the restaurant bill to a room).
## Security
The API is provided via encrypted HTTPS protocol with valid certificates. Authentication is ensured through two API-keys, one for the connected system (called system-key) and one for every individual client (called client-key).
## Versions
New integrations should use the latest version of the Cash-API, which is 2.2 at the time of writing.
Cash-API 1.0 is severely limited in its functionality and although it has technically not yet been deprecated it should be considered as such.
## Requests
### Request endpoint
Every request for version 2.2 must call the URL
[https://rooms.ibelsa.com/api/cash/2.2/xml/](https://rooms.ibelsa.com/api/cash/2.0/xml/)
Every request for version 2.0 must call the URL
[https://rooms.ibelsa.com/api/cash/2.0/xml/](https://rooms.ibelsa.com/api/cash/2.0/xml/)
Older versions use the URL
[https://rooms.ibelsa.com/api/cash/1.0/xml/](https://rooms.ibelsa.com/api/cash/1.0/xml/)
Features of the 2.x API that are not covered by version 1.0 are tagged as such in the detailed documentation.
### Request flow
All data is wrapped in XML and sent using POST. The server responds with XML data too.
XML declaration *`<?xml version="1.0" encoding="utf-8" ?>`* is omitted in the following examples for the sake of clarity.
The endpoints expects XML data encoded as UTF-8.
## Responses
The server’s response can be either of status "ok", "ok_with_errors" or "fail", containing further information or error code / msg.
"fail" means the request failed completely and no data is transferred.
"ok_with_errors" means some but not all data is transferred. See err tag for further details.
Examples:
```xml
<response status="ok">
<msg>Hello World</msg>
</response>
<response status="fail">
<err code="100" msg="Invalid system key"/>
</response>
```
## Authentification
Authentication is done through three parameters:
1. `<name>` : Arbitrary value (e.g. “Checkout Pro"), helps identifying your calls within log
files. Should be configurable by the end user to allow settings like “Checkout Pro /
Counter" and “Checkout Pro/ Service".
2. `<systemkey>` : This mandatory key identifies the caller. The caller can obtain a key
from PMS system and needs to integrate it into the software. The key must be kept
secret.
3. `<clientkey>` : This mandatory key identifies the end user (hotelier). He’ll find it in the
PMS settings options (after activating the API) and has to transfer it to the callers
software (e.g. by entering it in the options of the external cash system). This key too
must be kept secret.
## Technical Details
- Decimal separator: Point (e.g. price="5.50")
- Date format: "yyyy-mm-dd hh:mm:ss" (e.g.** **2012-12-12 12:12:12)
- System- and ClientKey: classic GUID (with hyphen/uppercase) e.g. 936DA01F-9ABD- 4D9D-80C7-02AF85C822A8
- Currency: 3-digit ISO-Code (e.g. EUR / USD / CHF)
- Max length of all strings is 255
- Max integer value is 2147483647
- All special characters must be escaped in the XML parameters (eg. & -> `&`) We highly recommend using an established XML library for this purpose
## Contact
- Technical Support
- dev-team@ibelsa.com
- Ralf Rußhardt
- Simon Triem
- Partner Support
- support@ibelsa.com
- Nancy Viergutz
- Karen Siebrecht
## Onboarding
At least 2 meetings are required to integrate a new POS in ibelsa:
- Kick-off
- Generation of API-Keys
- Preparation of testing environment
- Technical approval
- Check of interface communication
## API Methods
### Method: Ping
Description: Used to ping the server for test purpose
Request:
```xml
<method name="Ping">
<authentication clientkey="z" name="x" systemkey="y" />
</method>
```
Response (ok):
```xml
<response status="ok">
</response>
```
Response (fail):
```xml
<response status="fail">
<err code="100" msg="Invalid system key"/>
</response>
```
### Method: GetVersion
The API method GetVersion present for compatibility with a partner POS. API version is mainly determined by endpoint.
The POS will send the following request to the server:
```xml
<method name="GetVersion">
<authentication clientkey="z" name="x" systemkey="y"/>
</method>
```
In response to the GetVersion method the server should either reply with an error code 100:
```xml
<response status="fail">
<err code="100" msg="Invalid system key"/>
</response>
```
or the server should provide the API version the server supports and the server-information (unique name of the PMS product the POS connects to, in this case ibelsa.cooms):
Response for endpoint **https://rooms.ibelsa.com/api/cash/1.0/xml/**
```xml
<response status="ok">
<version number="1.0"/>
<server product="ibelsa.rooms"/>
</response>
```
Response for endpoint **https://rooms.ibelsa.com/api/cash/2.0/xml/**
```xml
<response status="ok">
<version number="2.0"/>
<server product="ibelsa.rooms"/>
</response>
```
Response for endpoint **https://rooms.ibelsa.com/api/cash/2.2/xml/**
```xml
<response status="ok">
<version number="2.2"/>
<server product="ibelsa.rooms"/>
</response>
```
### Method: RoomsGetList
Gives back a room list with numbers and names.Typical use case: before charging the restaurant bill to a room, the waiter does a plausibility check.
Response: List of rooms with ID/number from the room and name of guest. As of version 2.x, the Reservation-ID (resid) is also required in the response.
Examples:
```xml
<method name="RoomsGetList" status="CheckedIn" pattern="123">
<authentication clientkey="z" name="x" systemkey="y"/>
</method>
```
Calling parameters:
| | | |
| ------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status | string | can be used to determine the desired rooms (at the moment just "CheckedIn" for checked-in rooms, in a later version we might also use for instance "All" or "Available". This will be specified with a new API-document) |
| pattern | string | optional: Specifies a search string. Only in API >= 2. |
The following fields are searched if pattern is specified to filter the List
- name of the room (not available for paymaster invoices)
- firstname and lastname of guest
- phone number of guest
- address of guest
- email address of guest
Response for version 2.0
```xml
<response status="ok">
<rooms>
<room guestname="Herr Andreas Kuster" id="10370771" name="0021"
resid="10370771"/>
<room guestname="John Doe" id="PM_12345" name="PAYMASTER"
resid="PM_12345" />
<room guestname="Jane Doe" id="1234567" name="Suite"
resid="1234567" />
</rooms>
</response>
```
Response for version 2.2
```xml
<response status="ok">
<rooms>
<room guestname="Herr Andreas Kuster" id="10370771"
name="0021" resid="10370771" pmid="" arrival="2022-11-01"
departure="2022-11-03" rate="Rack Rate"
roomcategory="Doppelzimmer" pax="2"/>
<room guestname="John Doe" id="PM_12345" name="PAYMASTER"
resid="" pmid="12345" />
</rooms>
</response>
```
Response Values for version 2.0:
||||
| :-------- | :----- | :---------------------------------------------------------------------------------- |
| rooms | array | array of rooms |
| room | | room object |
| guestname | string | name of guest or paymaster invoice recipient |
| id | string | unique id of room / reservation / paymaster with prefix |
| resid | string | alias of id for partner compatibility |
| name | string | number / name of the room (e.g. "5" or "MasterSuite" as it is used.) or "PAYMASTER" |
Response Values for version 2.2:
||||
| :----------- | :------ | :---------------------------------------------------------------------------------- |
| rooms | array | array of rooms |
| room | | room object |
| guestname | string | name of guest or paymaster invoice recipient |
| id | string | unique id of room / reservation / paymaster with prefix |
| resid | integer | id of roomreservation |
| pmid | integer | id of paymaster |
| name | string | number / name of the room (e.g. "5" or "MasterSuite" as it is used.) or "PAYMASTER" |
| arrival | string | starting date of reservation formatted asyyyy-mm-dd |
| departure | string | ending date of reservation formatted asyyyy-mm-dd |
| rate | string | rate name |
| roomcategory | string | room category name |
| pax | integer | number of persons for the reservation |
### Method: RoomsLookupList
This method is an alias for RoomsGetList. This is part of this API for partner compatibility and only in API >= 2.0.
### Method: VatGetList
Gives back a tax class / vat list with names, vat value and ID in ibelsa.rooms. This can be used to determine a particular tax class in ibelsa for the import of a group (ImportData method) if multiple tax classes with the same vat value are present.
This method is introduced with version 2.2
Examples:
```xml
<method name="VatGetList">
<authentication clientkey="z" name="x" systemkey="y"/>
</method>
```
Response:
```xml
<response status="ok">
<vatlist>
<vatitem name="Tax class #1" id="1" vat="19" />
<vatitem name="Tax class #2" id="2" vat="7" />
<vatitem name="16%" id="4346" vat="16" />
<vatitem name="zero" id="7110" vat="0" />
</vatlist>
</response>
```
Response Values for version 2.0:
||||
| :------ | :------ | :---------------------------------- |
| vatlist | array | array of vat items |
| vatitem | | tax class object |
| name | string | name of tax class |
| id | integer | unique id tax class in ibelsa.rooms |
| vat | float | vat value |
### Method: AccountsGetList
Gives back the financial account list with names, account number in ibelsa.rooms. This can be used to determine a particular account in ibelsa for the import of a group or payment via ImportData method.
This method is introduced with version 2.2
Examples:
```xml
<method name="AccountsGetList">
<authentication clientkey="z" name="x" systemkey="y"/>
</method>
```
Response:
```xml
<response status="ok">
<accounts>
<account number="1000" name="Revenue 19%" />
<account number="1100" name="Revenue 7%" />
<account number="1600" name="Cash" />
<account number="10000" name="Debits" />
</accounts>
</response>
```
Response Values for version 2.0:
||||
| :------- | :------ | :------------------- |
| accounts | array | Array of accounts |
| account | | Contains one account |
| number | integer | number of account |
| name | string | name of account |
### Method: InvoiceToRoom
Used to charge a bill to a room. Typical use case: after eating in the hotel restaurant, the guest wants the bill to be charged to his room.
Apart from the room ID, all details of the bill must be included.
Schema:
```xml
<method name="InvoiceToRoom">
<authentication clientkey="z" name="x" systemkey="y"/>
<roomid></roomid>
<resid></resid>
<pmid></pmid>
<invoice>
<currency></currency>
<datetime></datetime>
<invoicenumber></invoicenumber>
<external>0</external>
<items>
<item amount="" count="" groupid="" groupname=""
ident="" name="" price="" vatrate=""/>
</items>
<processnumber></processnumber>
<serviceid> </serviceid>
<table></table>
<total></total>
<waiterid></waiterid>
<note/>
</invoice>
</method>
```
Example:
```xml
<method name="InvoiceToRoom">
<authentication clientkey="z" name="x" systemkey="y"/>
<roomid>31726596</roomid>
<resid>31726596</resid>
<invoice>
<currency>EUR</currency>
<datetime>2016-04-11 14:43:38</datetime>
<invoicenumber>23</invoicenumber>
<external>0</external>
<items>
<item amount="6.5" count="1" groupid="1" groupname="Drinks"
ident="111202" name="Cognac drinks" price="6.5"
vatrate="19"/>
</items>
<outlet>4177</outlet>
<processnumber>3</processnumber>
<serviceid>Julius Gerber</serviceid>
<table>12/1</table>
<total>6.5</total>
<waiterid>42</waiterid>
<note/>
</invoice>
</method>
```
Response:
```xml
<response status="ok">
</response>
```
Calling parameters:
The following is a description from the available Calling parameters or the method "InvoiceToRoom". If the parameter description starts with "(Version 2.0)", the parameter is only Available in API Version 2.0.
||||
| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| roomid | string | unique ID of the room / reservation the bill will be charged to. Or ID of paymaster invoice with prefix. Can be obtained using the RoomsGetList function |
| resid | integer | Unique ID of the roomreservation. Can be obtained using the RoomsGetList function |
| pmid | integer | (Version 2.2) Unique ID of the paymaster invoice (without prefix). Can be obtained using the RoomsGetList function |
| invoice | | The bill / invoice |
| currency | string | 3-digit ISO-Code (e.g. EUR / USD / CHF) |
| datetime | string | Date & Time, formatted asyyyy-mm-dd hh:mm:ss |
| invoicenumber | integer | Unique invoice-number within the cash system |
| processnumber | integer | alias of invoicenumber for partner compatibility |
| external | integer | For To-Go (“Außer Haus”) Selling - 0 if false, 1 if true |
| items | array | List of all items |
| item | | One Item |
| amount | double | Total price (=count * price) |
| count | integer | Quantity of the item (positive integer) |
| groupid | integer | (Version 2.0) ID of the article group to which the article belongs. |
| groupname | string | (Version 2.0) Name of the article group the article belongs to. |
| ident | integer | Unique identifier used within the cash system to reference the item |
| name | string | Name (e.g. "Roast Beef") |
| price | double | Unit price |
| vatrate | double | VAT rate |
| serviceid | string | Optional: Information about place where POS system is located or person using POS (e.g. "bar" or "waiter 42") |
| table | string | Optional: table number/ table name |
| total | double | Total sum |
| note | string | Optional: comment |
#### Cancellation/reversal:
In order to cancel an item we need a counter booking with negative price and negative amount, but positive count.
### Method: InvoicesClosedTransfer
This Method is only available in API version >= 2.0.
This Request will transmit a list of tables paid without the tables already transferred to the PMS through the InvoiceToRoom - Method (so tables/invoices paid with a different payment method than PMS/Hotel/To-Room).
This Request can be called multiple times per day (e.g. every time when an invoice was paid or every hour) or can be called at the end of a business day (with all invoices of that particular business day except these transferred with InvoiceToRoom method).
The invoices are checked for correctness. If this check fails, e.g. because the sum of items dont match the sum of payments, the particular invoice is rejected.
**Note:** To communicate the end of a business day you need to call "CloseBusinessDay" method.
Example:
```xml
<method name="InvoicesClosedTransfer">
<authentication clientkey="z" name="x" systemkey="y"/>
<invoices>
<invoice>
<currency>EUR</currency>
<datetime>2016-04-05 12:41:25</datetime>
<invoicenumber>10</invoicenumber>
<external>0</external>
<items>
<item amount="4.5" count="1" ident="8523" name="Ice Cream"
price="4.5" vatrate="19" groupname="Dessert" groupid="1"/>
<item amount="0" count="1" ident="111184" name="Vanilla"
price="0" vatrate="19" groupname="Dessert" groupid="1"/>
<item amount="5" count="1" ident="391" name="Cheese Plate"
price="5" vatrate="19" groupname="Dessert" groupid="1"/>
<item amount="0" count="1" ident="111187" name="Chocolate"
price="0" vatrate="19" groupname="Dessert" groupid="1"/>
<item amount="0" count="1" ident="111188" name="Lemon"
price="0" vatrate="19" groupname="Dessert" groupid="1"/>
</items>
<note/>
<outlet>4711</outlet>
<payments>
<payment amount="5.5" amountbasecurrency="5.5" ident="250"
name="Cash"/>
<payment amount="4" amountbasecurrency="4" ident="180"
name="Credit Card"/>
</payments>
<processnumber>1</processnumber>
<table>42/1</table>
<total>9.5</total>
<serviceid>42</serviceid>
</invoice>
</invoices>
</method>
```
Response without errors:
```xml
<response status="ok">
</response>
```
Response with errors:
```xml
<response status="ok_with_errors">
<err code=”391” invoicenumber=”10” msg=”invalid invoice data”>
</response>
```
Calling parameters:
The following is a description from the available Calling parameters.
||||
| ------------------------------------------ | ------- | ------------------------------------------------------------------------- |
| invoices | array | Contains all invoices |
| invoice | array | The bill / invoice |
| currency | string | 3-digit ISO-Code (e.g. EUR / USD / CHF) |
| datetime | string | Date & Time, formatted asyyyy-mm-dd hh:mm:ss |
| invoicenumber | string | Unique invoice-number within the cash system |
| processnumber | string | alias of invoice number for partner compatibility |
| external | integer | For To-Go (“Außer Haus”) Selling - 0 if false, 1 if true |
| items | array | List of all items |
| item | | One Item |
| amount | double | Total price (= count * price) |
| count | integer | Quantity of the item (no fractions) |
| groupid | integer | (Version 2.x) ID of the article group to which the article belongs. |
| groupname | string | (Version 2.x) Name of the article group the article belongs to. |
| ident | integer | Unique identifier used within the cash system to reference the item |
| name | string | Name (e.g. "Roast Beef") |
| price | double | Unit price |
| vatrate | double | VAT rate |
| serviceid | string | Optional: Information about place or person (e.g. "bar" or "Jane Doe") |
| table | string | Optional: table number/ table name |
| total | double | Total sum |
| note | string | Optional: comment |
| payments | array | (Version 2.0) Contains the used payment methods. |
| payment | | Contains information on one payment method |
| amount | double | amount of the payment |
| amountbasecurrency | string | amount of the payment in the base currency (if another currency was used) |
| name | string | Name of the payment method |
#### Cancellation/reversal:
In order to cancel an invoice with items we need counter bookings with negative price and negative amount, but positive count.
### Method: InvoicesShiftClose
This method is an alias for InvoicesClosedTransfer. This is part of this API for partner compatibility and only in API >= 2.0.
### Method: CloseBusinessDay
Used to mark the end of a business day in POS system. Only available in API >= 2.0.
```xml
<method name="CloseBusinessDay" day="2017-06-14">
<authentication clientkey="z" name="x" systemkey="y"/>
</method>
```
Calling parameters:
||||
| :------------ | -------------- | ------------------------------------------------------- |
| day | date | the date of business day in YYYY-MM-DD format |
### Method: ImportData
Used to import existing payment methods and commodity groups from POS into ibelsa.rooms.
If a group with an existing identifier ("ident") is transmitted, the group in our system will be updated with the newly provided data.
This method is introduced with version 2.2
```xml
<method name="ImportData">
<authentication clientkey="z" name="x" systemkey="y"/>
<groups>
<group ident="714275" parent="root" name="Food (Speisen)" vat="7"
vatid="9836" account="12345"/>
<group ident="714276" parent="714275" name="Breakfast" vat="19"
vatid="678" account="12346"/>
<group ident="714277" parent="714275" name="Lunch" vat="19"
vatid="678" account="12347"/>
<group ident="987654" parent="root" name="Beverage (Getränke)" vat="7"
vatid="9836" account="23456"/>
<group ident="987655" parent="987654" name="Beer" vat="19"
vatid="4711" account="23457"/>
<group ident="987656" parent="987654" name="Wine" vat="19"
vatid="4711" account="23458"/>
</groups>
<payments>
<payment ident="250" name="Cash" account="23488"/>
<payment ident="180" name="Credit Card" account="23489"/>
<payment ident="ec" name="EC-Karte" account="10001"/>
</payments>
</method>
```
Response examples:
```xml
<response status="ok">
<msg>9 datasets imported</msg>
</response>
```
```xml
<response status="fail">
<err code=”202” line=”5” msg=”name missing”>
</response>
```
In case of errors nothing will be imported and the errors in the datasets will be in the response message.
Calling parameters:
The following is a description from the available Calling parameters.
||||
| :------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| groups | array | Contains all commodity groups |
| group | | Contains information on one commodity group |
| ident | string | unique identifier of group in POS |
| parent | string | identifier of parent group in tree, if this group is upper level, this must be “root” |
| name | string | Name of the group |
| vat | double | VAT rate of group (if vatid is empty) |
| vatid | integer | ID of tax class in ibelsa.rooms in order to create the relation between group and tax class.Can be obtained using the VatGetList function |
| account | integer | Number of financial accounting account. This account must exist in ibelsa.rooms in order to create the relation between group and account.Can be obtained using the AccountsGetList function |
| payments | array | Contains all payment methods. |
| payment | | Contains information on one payment method |
| ident | string | unique identifier of payment method in POS |
| name | string | Name of the payment method |
| account | integer | Number of financial accounting account. This account must exist in ibelsa.rooms in order to create the relation between payment method and account.Can be obtained using the AccountsGetList function |
## Hints and advice
* The amount must be a positive integer. To cancel an already sent product it must be sent with the same amount and negative price
* Tips are handled as product
* Vouchers are handled as product
* Discounts must be calculated before the products are sent to the interface. All products must be sent with the final gross amount to ibelsa Cash API.
* The sum of all product amounts must correspond with the sum of all payments in method InvoicesClosedTransfer
## Error Codes
Codes starting at 100 are common errors that may occur for all functions. Codes starting with 300 are semantic errors. PMS needs to provide these error codes in the answers to a POS request / method:
| Code | Error |
| ---- | --------------------------------------------------- |
| 100 | Invalid system key |
| 101 | Invalid client key |
| 102 | Inactive client key |
| 103 | Internal authentication error |
| 105 | Service currently unavailable |
| 111 | Cashmaster not active |
| 112 | Method not found |
| 113 | Invalid method attribute |
| 200 | Invalid date |
| 201 | Invalid argument |
| 202 | Missing argument |
| 203 | Malformed |
| 204 | Maximum XML file size exceeded |
| 210 | Invoice already exists |
| 211 | Paymaster Invoice is closed |
| 390 | Invalid room |
| 391 | Invalid invoice data |
| 392 | Missing invoice data |
| 393 | Invalid currency |
| 394 | Invalid payments |
| 395 | Invalid tax vat for KassenSichV |
| 396 | Items sum not equal total sum |
| 666 | Internal ibelsa.rooms error, please contact support |
Author:
This page was generated from a Markdown file.
Would you like to view the content in your favourite Markdown reader? Raw Markdown
Would you like to view the content in your favourite Markdown reader? Raw Markdown