--- created: 2017-06-14T00:00 updated: 2024-04-25T14:39 author: Ralf Rußhardt title: Documentation v. 2.0 --- # Documentation v. 2.0 ## 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 Every call uses the HTTPS protocol with SSL encryption.Authentication is ensured through two API-keys, one for the connected system (called system-key) and one for every individual client (called client-key). ## Request endpoint Every request for version 2.0 must call the URL **https://rooms.ibelsa.com/api/cash/2.0/xml/** Older versions use the URL **https://rooms.ibelsa.com/api/cash/1.0/xml/** Features of the 2.0 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. ## Response The server’s response can be either of status “ **ok** ” or “ **fail** ”, containing further information or error code / msg. 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. ## 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> ``` ### 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.1, 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> ``` Callingparameters: 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 - firstname and lastname of guest - phone number of guest - address of guest - email address of guest ```xml <rooms> <room guestname="Herr Andreas Kuster" id="10370771" name="0021" resid="10370771"/> <room guestname="John Doe" id="12345" name="Suite" resid="12345" /> </rooms> </response> ``` Response Values: rooms array array of rooms room room object guestname string name of guest id integer unique id of room / reservation resid integer alias of id for partner compatibility name string number / name of the room (e.g. “5” or “MasterSuite” as it is used.) ### 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: 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> <invoice> <currency></currency> <datetime></datetime> <invoicenumber></invoicenumber> <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> <items> <item amount="6.5" count="1" groupid="1" groupname="Drinks" ident="111202" name="Cognac drinks" price="6.5" vatid="1" 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 integer unique ID of the room / reservation the bill will be charged to. Can be obtained using the RoomsGetList function resid integer alias of roomid for partner compatibility invoice The bill / invoice currency string 3-digit ISO-Code (e.g. EUR / USD / CHF) datetime string Date & Time, formatted as yyyy-mm-dd hh:mm:ss invoicenumber integer Unique invoice-number within the cash system processnumber integer alias of invoicenumber for partner compatibility items array List of all items item One Item amount double Total price (=count * price) count integer Quantity of the item 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 ## 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 transfered 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. everytime 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). **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> <items> <item amount="4.5" count="1" ident="8523" name="Ice Cream" price="4.5" vatrate="19" groupid="1"/> <item amount="0" count="1" ident="111184" name="Vanilla" price="0" vatrate="19" groupid="1"/> <item amount="5" count="1" ident="391" name="Cheese Plate" price="5" vatrate="19" groupid="1"/> <item amount="0" count="1" ident="111187" name="Chocolate" price="0" vatrate="19" groupid="1"/> <item amount="0" count="1" ident="111188" name="Lemon" price="0" vatrate="19" 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: ```xml <response status="ok"> </response> ``` Callingparameters: The following is a description from the available Calling parameters. invoices array Contains all invoices invoice The bill / invoice currency string 3-digit ISO-Code (e.g. EUR / USD / CHF) datetime string Date & Time, formatted as yyyy-mm-dd hh:mm:ss invoicenumber integer Unique invoice-number within the cash system processnumber integer alias of invoicenumber for partner compatibility items array List of all items item One Item amount double Total price (=count * price) count integer Quantity of the item 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 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 ## 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> ``` Callingparameters: day date the date of business day in YYYY-MM-DD format ## Error Codes Codes starting at 100 are valid for all functions. PMS needs to provide these error codes in the answers to a POS request / method: 100: Invalid system key 101: Invalid client key 105: Service currently unavailable 112: Method not found 113: Invalid method attribute 200: Invalid date 201: Invalid argument 202: Missing argument 203: Malformed 204: Argument out of range ## 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-02AF85C822A - Currency: 3-digit ISO-Code (e.g. EUR / USD / CHF) - Max length of all strings is 255 - Max integer value is 2147483647

Author:

This page was generated from a Markdown file.

Would you like to view the content in your favourite Markdown reader? Raw Markdown