GenericPOS

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 genericpos /#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 /> response response okay \<?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> roomsgetlist slug rooms http method post request \<?xml version="1 0" encoding="utf 8" ?> \<request status="checkedin"> \</request> request (by room number) \<?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 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 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 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) \<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) \<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 version="1 0" encoding="utf 8" ?> \<response status="ok"> \</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>