--- created: 2012-08-08T00:00 updated: 2024-04-25T14:39 author: Ralf Rußhardt title: Documentation v. 1.0 --- # Documentation v. 1.0 ## Überblick Mittels dieser API erhalten externe Systeme Zugriff auf Daten von ibelsa. Dabei kann es um das Lesen von Daten (z.B. die Anzeige einer Liste aller belegten Zimmer) und das Schreiben von Daten (z.B. die Buchung einer Rechnung auf ein Zimmer) gehen. ## Sicherheit Alle Aufrufe laufen ausschließlich und komplett über SSL. Für weitere Sicherheit sorgt die Authentifizierung durch zwei API-Keys. Da das SSL-Protokoll immanente Schwächen hat (Stichwort Man-in-the-middle-Angriff), behält sich ibelsa die Implementierung weiterer Sicherheitsmechanismen vor. Die Gültigkeit des SSL-Zertifikats sollte vom Caller unbedingt überprüft werden. ## Aufruf Endpunkt aller Aufrufe: https://rooms.ibelsa.com/api/cash/1.0/xml/ ## Ablauf Für den Aufruf einer Funktion werden sämtliche Parameter in XML gepackt und mittels POST übermittelt. Die Antwort des Servers kommt wiederum als XML zurück. Allen XML-Daten muss `<?xml version="1.0" encoding="utf-8" ?>` vorangestellt werden. Das wird nachfolgend aus Gründen der Übersichtlichkeit weggelassen. ## Rückantwort Die Response des Servers kann den Status OK oder FAIL haben und enthält dann entweder weitere Infos oder Errorcode/msg. Beispiel: ```xml <response status="ok"> <msg>Hallo</msg> </response> <response status="fail"> <err code="100" msg="Invalid system key" /> </response> ``` Errorcodes ab 100 gelten für alle Funktionen. Codes kleiner 100 gehören zur jeweiligen Funktion. ## Authentifizierung Die Authentifizierung erfolgt bei jedem Aufruf über 3 Parameter: 1. `<name>` : Vom Caller frei wählbar (zB. „Kasse Pro“), dient der Identifizierung zB. innerhalb von Log-Files. Sollte vom Anwender des Kassensystems konfigurierbar sein, damit auch Werte wie „Kasse Pro / Theke“ und „Kasse Pro / Service“ möglich sind. 2. `<systemkey>` : Dieser obligatorische Key identifiziert den Caller. Der Caller erhält den Key von ibelsa und muss ihn in seine Software integrieren. Dieser Schlüssel ist geheim zu halten. 3. `<clientkey>` : Dieser obligatorische Key identifiziert den Endkunden (Hotelier). Er findet ihn innerhalb der ibelsa-Optionen (nach dem Freischalten der entsprechenden API) und muss ihn in das externe System des Callers übertragen (zB. indem der Key innerhalb des Kassensystems in den Optionen eingetragen wird). Auch dieser Schlüssel ist geheim zu halten. ## Einführungsbeispiel Funktion: Ping Beschreibung: Erlaubt das Anpingen des Servers für Testzwecke Hin: ```xml <method name="Ping"> <authentication name="x" systemkey="y" clientkey="z" /> </method> ``` Zurück (ok): ```xml <response status="ok"> </response> ``` Zurück (fail): ```xml <response status="fail"> <err code="100" msg="Invalid system key" /> </response> ``` ## Funktion: RoomsGetList Gibt eine Zimmerliste mit Nummern und Namen zurück. Typischer Kontext: vor dem Buchen einer Rechnung aufs Zimmer möchte der Kellner eine Plausibilitätskontrolle durchführen. Aufrufparameter: Im Status-Attribut kann die Art der gewünschten Zimmer angegeben werden (bisher nur „CheckedIn“ für eingecheckte Zimmer, später zB. auch „All“ oder „Available“.) Rückgabe: Liste der Zimmer mit ID/Nummer und Name des Gastes. Beispiel: ```xml <method name="RoomsGetList" status="CheckedIn"> <authentication name="x" systemkey="y" clientkey="z" /> </method> <response status="ok"> <rooms> <room id="3" name="3" guestname="Max Mustermann" /> <room id="9" name="Suite" guestname="Klara Musterfrau" /> </rooms> </response> ``` Rückgabewerte: rooms array Array der Zimmer room Ein Zimmer id integer Eindeutige ID des Zimmers name string Nummer bzw. Name des Zimmers (z.B. „9“ oder „Wellness Suite“), wie sie auch vom Gast verwendet wird guestname string Name des Gastes ## Funktion: InvoiceToRoom Ermöglicht die Übergabe einer Rechnung auf ein Zimmer. Typischer Kontext: im Hotel- Restaurant lässt der Gast seine Rechnung auf sein Zimmer buchen. Neben der Zimmernummer müssen sämtliche Details der Rechnung übergeben werden. Ein Printout der Rechnung kann angehängt werden. Schema: ```xml <method name="InvoiceToRoom"> <authentication name="" systemkey="" clientkey="" /> <roomid></roomid> <invoice> <datetime>yyyy-mm-dd hh:mm:ss</datetime> <processnumber></processnumber> <serviceid></serviceid> <note></note> <table></table> <currency></currency> <total></total> <items> <item name="" ident="" count="" price="" amount="" vatrate="" /> </items> <printout>[base64:invoice.pdf]</printout> </invoice> </method> ``` Beispiel: ```xml <method name="InvoiceToRoom"> <authentication name="x" systemkey="y" clientkey="z" /> <roomid>13</roomid> <invoice> <datetime>2012-12-12 12:12:12</datetime> <processnumber>RN1234567890</processnumber> <serviceid>Frau Freundlich</serviceid> <note></note> <table>4</table> <currency>EUR</currency> <total>15</total> <items> <item name="Cafe" ident="1234" count="2" price="5.5" amount="11" vatrate="7" /> <item name="Kuchen" ident="5678" count="1" price="4" amount="4" vatrate="19" /> </items> <printout>[base64:invoice.pdf]</printout> </invoice> </method> <response status="ok"> </response> ``` Aufrufparameter: roomid integer Eindeutige ID des Zimmers, auf das die Rechnung gebucht werden soll. Kann vorher über die Funktion RoomsGetList ermittelt werden. invoice Die Rechnung datetime string Datum & Zeit im Format yyyy-mm-dd hh:mm:ss processnumber string Rechnungsnummer, anhand derer die Rechnung mit dem Kassensystem abgeglichen werden kann. serviceid string Optional: Hinweis auf den Ort (z.B. „Theke“) oder das Personal (z.B. „Frau Freundlich“) note string Optional: Bemerkung table string Optional: Tischnummer currency string 3-stelliger ISO-Code (z.B. EUR / USD / CHF) total double Summe der Rechnung (Brutto) items array Liste aller Einzelposten item Einzelposten name string Bezeichnung (z.B. “Schnitzel”) ident string Der vom Kassen system intern verwendete, eindeutige Bezeichner zur Referenzierung des Produkts (z.B. "cola_small" oder "12345"). Maximale Feldlänge: 200 Zeichen count integer Anzahl price double Stückpreis amount double Gesamtpreis (=count * price) vatrate double Steuerrate (z.B. „7“ oder „19“) printout string (base64, beliebige Länge) ``` Optional: die komplette Rechnung als PDF, die dann als zusätzliches Dokument der Zimmerrechnung angehängt wird. Hinweis: wird noch nicht weiterverarbeitet, Bestandteil späterer Planung. ``` Zusätzliche Errorcodes: 90: Invalid room 91: Invalid invoice data 92: Missing invoice data 93: Invalid currency ## Sandbox ibelsa stellt für Testzwecke ein virtuelles Test-Hotel zur Verfügung, das die API-Aufrufe entgegennimmt. Nachdem der Caller von ibelsa seinen SystemKey erhalten hat, kann dieses Testhotel über ClientKey=test angesprochen werden. ## Errorcodes Codes ab 100 gelten generell für alle Funktionen. 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 ## Technische Details - Dezimaltrenner: Punkt (zB. price="5.50" ) - Datumsformat: „yyyy-mm-dd hh:mm:ss“ (zB. `<datetime>`2012-12-12 12:12:12`</datetime>` ) - System- und ClientKey: klassiche GUID (mit Bindestrichen/Großbuchstaben) zB. 936DA01F-9ABD-4D9D-80C7-02AF85C822A - Currency: 3-stelliger ISO-Code (zB. EUR / USD / CHF) - Wo nicht anders angegeben, haben Strings eine maximale Feldlänge von 255 Zeichen.

Author:

This page was generated from a Markdown file.

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