API/INTERFACES
GenericPOS

25min
﻿
POS Interface
Security
Transmission
All the communication with our endpoints has to be HTTPS encrypted - we do not allow the transmission of any unencrypted data.
Authentication
Once approved, you receive a company code for us which is unique and identifies you as a vendor - keep it secret at all times. In order to authenticate on our system, you are expected to send an HTTP header named x-company-code with every request, with the value being your company code.
In case you can not send individual HTTP headers with your programming language or web service framework, you also have the option of transmitting the company code as an element inside the XML. If you prefer to use this option, please contact us before the implementation starts. In this case, please do add a companyCode attribute to your Request element (see company code in the XML﻿ )
URL
Live
https://api.hotelsoftware.io/rest/pos/{{ hotelId }}/v1.0/xml/{{ method_slug }}
Test
https://api-staging.hotelmeister.io/rest/pos/{{ hotelId }}/v1.0/xml/{{ method_slug }}
Methods
Ping
Slug: ping
HTTP Method: POST
Request
Request
<?xml version="1.0" encoding="utf-8" ?>
<Request />
<?xml version="1.0" encoding="utf-8" ?>
<Request />
﻿
Response
Response - Okay
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
    <Message>Hello</Message>
</Response>
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
    <Message>Hello</Message>
</Response>
﻿
Response - Error
<?xml version="1.0" encoding="utf-8" ?>
<Response status="fail">
    <Error code="100" msg="Invalid Company Code"/>
</Response>
<?xml version="1.0" encoding="utf-8" ?>
<Response status="fail">
    <Error code="100" msg="Invalid Company Code"/>
</Response>
﻿
RoomsGetList
Slug: rooms
HTTP Method: POST
Request
XML
<?xml version="1.0" encoding="utf-8" ?>
<Request status="CheckedIn">
</Request>
<?xml version="1.0" encoding="utf-8" ?>
<Request status="CheckedIn">
</Request>
﻿
Request (by room number)
XML
<?xml version="1.0" encoding="utf-8" ?>
<Request roomNumber="35">
</Request>
<?xml version="1.0" encoding="utf-8" ?>
<Request roomNumber="35">
</Request>
﻿
This request can be used to only request a certain room number instead of all rooms - this might be beneficial when the POS is used in a larger hotel with 100+ rooms.
Response
XML
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
    <Rooms>
        <Room guestName="Max Mustermann" roomNumber="35" roomName="Appartement Seegasse" parentId="res::2345" arrivalDate="2018-03-20" departureDate="2018-03-24" guestId="guest::345"/>
        <Room guestName="Marianne Mustermann" roomNumber="35" roomName="Appartement Seegasse" parentId="res::2345" arrivalDate="2018-03-20" departureDate="2018-03-24" guestId="guest::346"/>
        <Room guestName="John Doe" roomNumber="112" parentId="res::2380" arrivalDate="2018-03-21" departureDate="2018-03-29" guestId="guest::398"/>
        <Room guestName="Jane Doe" parentId="res::2388" arrivalDate="2018-03-17" departureDate="2018-03-22" guestId="guest::763"/> 
    </Rooms>
</Response>
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
    <Rooms>
        <Room guestName="Max Mustermann" roomNumber="35" roomName="Appartement Seegasse" parentId="res::2345" arrivalDate="2018-03-20" departureDate="2018-03-24" guestId="guest::345"/>
        <Room guestName="Marianne Mustermann" roomNumber="35" roomName="Appartement Seegasse" parentId="res::2345" arrivalDate="2018-03-20" departureDate="2018-03-24" guestId="guest::346"/>
        <Room guestName="John Doe" roomNumber="112" parentId="res::2380" arrivalDate="2018-03-21" departureDate="2018-03-29" guestId="guest::398"/>
        <Room guestName="Jane Doe" parentId="res::2388" arrivalDate="2018-03-17" departureDate="2018-03-22" guestId="guest::763"/> 
    </Rooms>
</Response>
﻿
We can have multiple Room elements with different guest names (i.e. if there are multiple guests in the same room)
In the future, Room elements with the same roomNumber might have different parentIds (i.e. if two people are sharing a room, but paying separate)
The attribute guestId is optional, and it can be configured whether it should be provided or not
All fields are of type String (even the roomNumber and do not have length limitations)
A Room element without a roomNumber attribute means, the guest does not yet have a room number assigned to his reservation (i.e. he is waiting at the bar/restaurant for his room to get ready)
InvoiceToRoom
Slug: charge
HTTP Method: POST
Request
XML
<?xml version="1.0" encoding="utf-8" ?>
<Request>
    <RoomNumber>123</RoomNumber>
    <ParentId>hotel::4::res::541</ParentId>
    <GuestName>Max Mustermann</GuestName> <!-- recommended -->
    <GuestId>guest::345</GuestId> <!-- recommended -->
    <Charge currency="EUR" dateTime="2018-03-23 01:45:17" id="893240" businessDate="2018-03-22"> 
        <Categories>
            <Category amount="11.10" id="1" name="Alkoholische Getränke" netAmount="9.25" vatRate="20.00" />
            <Category amount="33.80" id="2" name="Speisen" netAmount="30.73" vatRate="10.00" />
            <Category amount="2.80" id="3" name="Getränke" netAmount="2.33" vatRate="20.00" />
        </Categories>
        <Items>
            <Item amount="3.70" id="3" name="Stiegl 0,5l" netAmount="3.08" vatRate="20.00" categoryId="1" categoryName="Alkoholische Getränke" count="3.00"/>
            <Item amount="2.80" id="9" name="Soda Zitron 0,5l" netAmount="2.33" vatRate="20.00" categoryId="3" categoryName="Getränke" count="1.00"/>
            <Item amount="16.90" id="27" name="Wiener Schnitzel (Kalb)" netAmount="15.36" vatRate="10.00" categoryId="2" categoryName="Speisen" count="2.00"/>
        </Items>
        <Tip amount="1.30" />
        <Table>23</Table>
        <Note>Reserved for future use</Note>
        <Waiter id="123" name="Hans Maier" />
    </Charge>
</Request>
<?xml version="1.0" encoding="utf-8" ?>
<Request>
    <RoomNumber>123</RoomNumber>
    <ParentId>hotel::4::res::541</ParentId>
    <GuestName>Max Mustermann</GuestName> <!-- recommended -->
    <GuestId>guest::345</GuestId> <!-- recommended -->
    <Charge currency="EUR" dateTime="2018-03-23 01:45:17" id="893240" businessDate="2018-03-22"> 
        <Categories>
            <Category amount="11.10" id="1" name="Alkoholische Getränke" netAmount="9.25" vatRate="20.00" />
            <Category amount="33.80" id="2" name="Speisen" netAmount="30.73" vatRate="10.00" />
            <Category amount="2.80" id="3" name="Getränke" netAmount="2.33" vatRate="20.00" />
        </Categories>
        <Items>
            <Item amount="3.70" id="3" name="Stiegl 0,5l" netAmount="3.08" vatRate="20.00" categoryId="1" categoryName="Alkoholische Getränke" count="3.00"/>
            <Item amount="2.80" id="9" name="Soda Zitron 0,5l" netAmount="2.33" vatRate="20.00" categoryId="3" categoryName="Getränke" count="1.00"/>
            <Item amount="16.90" id="27" name="Wiener Schnitzel (Kalb)" netAmount="15.36" vatRate="10.00" categoryId="2" categoryName="Speisen" count="2.00"/>
        </Items>
        <Tip amount="1.30" />
        <Table>23</Table>
        <Note>Reserved for future use</Note>
        <Waiter id="123" name="Hans Maier" />
    </Charge>
</Request>
﻿
Either RoomNumber or ParentId has to be provided
The elements Tip, Table, Note and Waiter are optional
If there is no tip, the Tip element can be omitted
If the Waiter element is present, at least one of the attributes (id or name) should be passed along
The businessDate is optional and only required if the business date is different to the hotel local date (i.e. if the daily closing happens after midnight - often at the end of a shift)
The GuestID is an optional element and if supplied posts to a specific guest
Cancellation
XML
<?xml version="1.0" encoding="utf-8" ?>
<Request>
    <RoomNumber>123</RoomNumber>
    <ParentId>hotel::4::res::541</ParentId>
    <GuestName>Max Mustermann</GuestName> <!-- recommended -->
    <GuestId>guest::345</GuestId> <!-- recommended -->
    <Cancellation currency="EUR" dateTime="2018-03-23 01:45:17" id="893240" businessDate="2018-03-22"> 
        <Categories>
            <Category amount="11.10" id="1" name="Alkoholische Getränke" netAmount="9.25" vatRate="20.00" />
            <Category amount="33.80" id="2" name="Speisen" netAmount="30.73" vatRate="10.00" />
            <Category amount="2.80" id="3" name="Getränke" netAmount="2.33" vatRate="20.00" />
        </Categories>
        <Items>
            <Item amount="3.70" id="3" name="Stiegl 0,5l" netAmount="3.08" vatRate="20.00" categoryId="1" categoryName="Alkoholische Getränke" count="-3.00"/>
            <Item amount="2.80" id="9" name="Soda Zitron 0,5l" netAmount="2.33" vatRate="20.00" categoryId="3" categoryName="Getränke" count="-1.00"/>
            <Item amount="16.90" id="27" name="Wiener Schnitzel (Kalb)" netAmount="15.36" vatRate="10.00" categoryId="2" categoryName="Speisen" count="-2.00"/>
        </Items>
        <Tip amount="1.30" />
        <Table>23</Table>
        <Note>Reserved for future use</Note>
        <Waiter id="123" name="Hans Maier" />
    </Cancellation>
</Request>
<?xml version="1.0" encoding="utf-8" ?>
<Request>
    <RoomNumber>123</RoomNumber>
    <ParentId>hotel::4::res::541</ParentId>
    <GuestName>Max Mustermann</GuestName> <!-- recommended -->
    <GuestId>guest::345</GuestId> <!-- recommended -->
    <Cancellation currency="EUR" dateTime="2018-03-23 01:45:17" id="893240" businessDate="2018-03-22"> 
        <Categories>
            <Category amount="11.10" id="1" name="Alkoholische Getränke" netAmount="9.25" vatRate="20.00" />
            <Category amount="33.80" id="2" name="Speisen" netAmount="30.73" vatRate="10.00" />
            <Category amount="2.80" id="3" name="Getränke" netAmount="2.33" vatRate="20.00" />
        </Categories>
        <Items>
            <Item amount="3.70" id="3" name="Stiegl 0,5l" netAmount="3.08" vatRate="20.00" categoryId="1" categoryName="Alkoholische Getränke" count="-3.00"/>
            <Item amount="2.80" id="9" name="Soda Zitron 0,5l" netAmount="2.33" vatRate="20.00" categoryId="3" categoryName="Getränke" count="-1.00"/>
            <Item amount="16.90" id="27" name="Wiener Schnitzel (Kalb)" netAmount="15.36" vatRate="10.00" categoryId="2" categoryName="Speisen" count="-2.00"/>
        </Items>
        <Tip amount="1.30" />
        <Table>23</Table>
        <Note>Reserved for future use</Note>
        <Waiter id="123" name="Hans Maier" />
    </Cancellation>
</Request>
﻿
The id attribute of the Cancellation element has to be the same value as the id attribute of the original Charge element, you want to cancel
The count attribute of the Item element has to be negated (meaning if the original count was positive it has to be negative now)
The amount and netAmount attributes of the Item and Category elements have to be the same as in the original transaction (meaning if the original value was positive, this needs to be positive as well and contain the same value)
If the transaction has the same total amount as the original transaction, the original transaction will be cancelled
If the transaction has a different total amount (i.e. partial cancellation) then we will post a separate cancellation transaction, leaving both the original and the cancellation transaction visible on the customers folio
Request (minimal Version)
XML
<Request>
    <ParentId>hotel::4::res::541</ParentId>
    <Charge> 
        <Categories>
            <Category amount="11.10" name="Alkoholische Getränke" vatRate="20.00" />
            <Category amount="33.80" name="Speisen" vatRate="10.00" />
            <Category amount="2.80" name="Getränke" vatRate="20.00" />
        </Categories>
    </Charge>
</Request>
<Request>
    <ParentId>hotel::4::res::541</ParentId>
    <Charge> 
        <Categories>
            <Category amount="11.10" name="Alkoholische Getränke" vatRate="20.00" />
            <Category amount="33.80" name="Speisen" vatRate="10.00" />
            <Category amount="2.80" name="Getränke" vatRate="20.00" />
        </Categories>
    </Charge>
</Request>
﻿
Request (minimal Version with Items)
XML
<Request>
    <ParentId>hotel::4::res::541</ParentId>
    <Charge> 
        <Items>
            <Item amount="3.70" vatRate="20.00" count="3.00"/>
            <Item amount="2.80" vatRate="20.00" count="1.00"/>
            <Item amount="16.90" vatRate="10.00" count="2.00"/>
        </Items>
    </Charge>
</Request>
<Request>
    <ParentId>hotel::4::res::541</ParentId>
    <Charge> 
        <Items>
            <Item amount="3.70" vatRate="20.00" count="3.00"/>
            <Item amount="2.80" vatRate="20.00" count="1.00"/>
            <Item amount="16.90" vatRate="10.00" count="2.00"/>
        </Items>
    </Charge>
</Request>
﻿
Response
XML
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
</Response>
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
</Response>
﻿
XML
<?xml version="1.0" encoding="utf-8" ?>
<Response status="fail">
    <Error code="102" msg="Invalid XML or missing required attributes"/>
</Response>
<?xml version="1.0" encoding="utf-8" ?>
<Response status="fail">
    <Error code="102" msg="Invalid XML or missing required attributes"/>
</Response>
﻿
Error Codes
Any error response has a HTTP status code of 4xx or 5xx
Any success response will have a HTTP status code of 2xx
Error CodeMessage
﻿
100
Invalid Company Code
101
Invalid Hotel ID
102
Invalid XML or missing required attributes
103
ID / Room not found or not checked in
104
Could not uniquely identify reservation
105
Missing or incomplete configuration
999
Internal Server Error
Technical Details
Character Encoding / Charset
All our messages are UTF-8 encoded, and we do expect the same to apply for all incoming requests.
Decimal Separator
We are using . (point) as a decimal separator, and do expect 2 digits after the comma.
Date Time Format
We are using the date format yyyy-mm-dd (i.e. 2018-03-21).
We are using the date-time format yyyy-mm-dd hh:mm:ss (i.e. 2018-03-21 23:59:32).
All dates and times are expected to be in hotel local time.
Currency Code
Currency code is expected to be in ISO 4217 3 character notation (i.e. EUR, CHF, USD)
Invoice vs. Delivery Note
Please let us know whether you are creating an invoice (dt. Rechnung) or a delivery note (dt. Lieferschein) for room bookings in your POS. In case you are creating an invoice, we have to add it with 0% VAT on the hotel invoice, to avoid double taxation. In case you are creating a delivery note, we have to show the actual VAT on the hotel invoice.
Company Code in the XML
XML
<?xml version="1.0" encoding="utf-8" ?>
<Request companyCode="YOUR_COMPANY_CODE">
  <!-- everything else is the same and the XML content goes in here -->
</Request>
<?xml version="1.0" encoding="utf-8" ?>
<Request companyCode="YOUR_COMPANY_CODE">
  <!-- everything else is the same and the XML content goes in here -->
</Request>
﻿
﻿
Error CodeMessage
100	Invalid Company Code
101	Invalid Hotel ID
102	Invalid XML or missing required attributes
103	ID / Room not found or not checked in
104	Could not uniquely identify reservation
105	Missing or incomplete configuration
999	Internal Server Error
Room Type Widget
Reservation Import