---
title: GenericPOS
slug: genericpos
createdAt: 2020-12-18T01:16:23.000Z
---



# 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](docId\:uzAbKPf1RPiMBiHy8cZuS) )

## URL

**Live**

:::BlockQuote
https\://api.hotelsoftware.io/rest/pos/\{\{ hotelId }}/v1.0/xml/\{\{ method\_slug }}
:::

**Test**

:::BlockQuote
https\://api-staging.hotelmeister.io/rest/pos/\{\{ hotelId }}/v1.0/xml/\{\{ method\_slug }}
:::

## Methods

### Ping

Slug: ping

HTTP Method: POST

### Request

:::CodeblockTabs
Request

```xml
<?xml version="1.0" encoding="utf-8" ?>
<Request />
```
:::

### Response

:::CodeblockTabs
Response - Okay

```xml
<?xml version="1.0" encoding="utf-8" ?>
<Response status="ok">
    <Message>Hello</Message>
</Response>
```
:::

:::CodeblockTabs
Response - Error

```xml
<?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>
```

### Request (by room number)

```xml
<?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>
```

- 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>
```

- 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>
```

- 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 (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>
```

### Response

```xml
<?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>
```

## 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

:::CodeblockTabs
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>
```
:::