Web API · Addendum
Web API · Addendum
Ergänzende historische API-Dokumentation.
http://pos.prelive.qnips.com/api/pos/v3Grundlagen & vollständige Einführung
Dieses Dokument dient als Diskussionsgrundlage für eine Erweiterung der menio Web API v3. Die hier beschriebenen Erweiterungen (wie neue Resourcen, Properties, usw.) müssen noch nicht implementiert worden sein, weswegen Requests gegen unsere API fehlschlagen oder eine unerwartete Response ausliefern können.
Warenkorb-Handling
Positionen vom Warenkorb
Den Positionen vom Warenkorb wurden zwei neue Properties hinzugefügt.
Mengen und Einheiten
Mit der Unit Property kann die Einheit definiert werden, die via Amount referenziert wird. Aktuell unterstützen wir die folgenden Einheiten.
| Wert | Einheit |
|---|---|
| 0 | Stückzahl |
| 1 | Kilogramm |
Im gleichen Schritt unterstützt Amount nun Fließkommazahlen, sodass z.B. eine Gramm-genaue Eingabe erfolgen kann.
Positionsgenaue IDs
Jeder Position kann mittels PositionId eine (möglichst eindeutige) ID zugeordnet werden. Sollte der Warenkorb im Folgenden einen Coupon auslösen, wird die auslösende Position in der Response über die RewardTriggeringPositionId notiert werden.
Setzen/Ändern von Warenkorb-Information beim Grant
In dem Body des POST basket-grant requests können nun bestimmte Informationen vom Warenkorb erneut übergeben werden. Im genauen sind das BillNumber und Timestamp.
Zahlungsarten für digitalen Bon
In der POST basket sowie der POST basket-grant Resource besteht zukünftig die Möglichkeit, die für diese Transaktion genutzten Zahlungsarten an menio zu übermittelt, damit der Nutzer diese in seinem digitalen Kassenbon in der App einsehen kann.
Der Body des jeweiligen Requests wird dafür um ein neues Feld PaymentMethods erweitert:
{ … "PaymentMethods": [ { "Name": "Bar", "Amount": 13.64 } ] … }
Sollte dieses Feld gesetzt und der digitale Bon in der App aktiviert sein, werden diese Informationen dem Nutzer der App angezeigt.
Freitext und QR-Code für Kassenbon
Der Response der POST basket-grant Resource werden zwei neue Felder ReceiptText (string, optional) sowie QrCodeContent (string, optional) hinzugefügt.
ReceiptText
Sollte dieses Feld gesetzt und nicht leer sein, enthält es einen Backend-generierten Freitext der beim Druck des Kassenbons respektiert werden soll. Steuerzeichen für NewLine und bold?
QrCodeContent
Sollte dieses Feld gesetzt und nicht leer sein, enthält es eine URL die als QR-Code auf dem Kassenbon gedruckt werden soll. In der aktuellen Version wird dieses Feld dann gesetzt sein, wenn bei dem Grant des Baskets kein ConsumerIdentToken mit diesem Basket verknüpft ist.
Da die QR-Codes auf den Kassenbons für die Nutzer gedacht sind, die nicht direkt an der Kasse mit einer Karte oder Smartphone ihren Token übermittelt haben, brauchen wir eine Möglichkeit auch Warenkörbe ohne Token an das menio Backend übermittelt zu bekommen. Hierfür könnte man eine Konfigurationseinstellung vorsehen, die – sofern gesetzt – bei Abschluss einer Transaktion ohne menio-Token an der Kasse einen POST basket mit dem aktuellen Warenkorb und direkt folgend einen POST basket-grant aufruft. Dadurch wird das neue Feld QrCodeContent im Response gesetzt sein, wodurch der QR-Code auf den Kassenbon gedruckt werden kann.
Infos zu Tokens abrufen
Es wird eine neue Methode GET tokens/info/{tokenId} angelegt, die verschiedene Informationen zu dem angefragten Token zurück gibt.
Guthabenverwendung
Dem Nutzer einer Guthabenkarte soll eine Möglichkeit geboten werden, mit der er die Verwendung des Guthabens einstellen kann. Wenn er z.B. seine Guthabenkarte lediglich für das Sammeln von Treuepunkten verwenden will, soll er nicht immer wieder mit der Guthabenfunktion angesprochen werden.
Hierfür haben wir ein neues Feld BalanceType definiert, das genau diese Informationen tragen kann. Die Kasse soll dieses Feld bei der Abrechnung eines Warenkorbes respektieren.
PIN-Erfassung
Es wird eine Möglichkeit geschaffen, mit der definiert werden kann, ob aus Sicherheitsgründen eine PIN-Eingabe durch den Nutzer bei der nächsten Zahlung mit der Guthabenkarte (BalanceWithdraw) notwendig ist. Je nach Wunsch des Kunden kann dies z.B. bei der erstmaligen Nutzung der Guthabenkarte oder bei jeder Nutzung geschehen.
Info-URL
Die neue Property InfoUrl kann eine (optionale) URL enthalten, die von der Kasse aufgerufen werden soll. Hinter dieser URL können weitere Informationen liegen, die auf dem Kassendisplay angezeigt werden sollen.
Zur Diskussion: Größe der Embedded Webview?
Tag-System auf Tokens
Jeder Token kann mit beliebig vielen Tags markiert werden. Über diese Tags kann z.B. eine bestimmte Preisebene ausgewählt werden.
Beispiel
{ "Name": "Mitarbeiter", "Groups": [ "priceLevel" ] }
Sollte dieser Tag in der Response enthalten sein, wurde diesem Token ein Tag mit dem Namen Mitarbeiter zugewiesen. Da dieser Tag selbst der Gruppe priceLevel angehört, definiert dieser Tag, dass ab jetzt – wenn möglich – die Preisebene mit dem Namen Mitarbeiter verwendet werden soll.
Zahlungsvorgänge mit Guthaben
Die bestehenden Resourcen zum Aufladen (addBalance) und Abheben (withdrawBalance) von Guthaben werden um weitere, optionale Query-Parameter erweitert um eine nachträgliche Zuordnung der Zahlungsvorgänge und Warenkörbe zu erleichtern.
Noch offen: Stornos, Refund, Entladen einer Karte
Aufladen von Guthaben
| Query | Beschreibung |
|---|---|
merchantReference |
Interne Referenz/Vorgangsnummer in der Kasse |
type |
Entweder payin oder refund |
payinType |
Bei type = payin kann hier die Zahlungsart definiert werden |
referenceBasketId |
Wenn die Aufladung während eines Einkaufs erfolgt kann hier die zugehörige BasketId übermittelt werden |
description |
Feld für weitere Freitext-Ergänzungen zur Protokollierung |
Verfügbare Zahlungsarten
| Wert | Zahlungsart |
|---|---|
| 0 | nicht erfasst |
| 1 | Bar |
| 2 | ec-Karte / Girocard |
| 3 | Mastercard |
| 4 | Visa Card |
| 5 | American Express |
| 6 | andere Kreditkarte |
| 7 | Rechnung |
| 8 | Bankeinzug |
| 9 | Geldkarte |
| 10 | Girogo |
| 11 | Paypass MasterCard |
| 12 | Vpass Visa |
Hinweis: Diese Liste von Zahlungsarten ist nicht final und kann bei Bedarf erweitert werden.
Abheben von Guthaben
| Query | Beschreibung |
|---|---|
merchantReference |
Interne Referenz/Vorgangsnummer in der Kasse |
type |
Entweder basket oder payout (reserved) |
referenceBasketId |
Wenn das Abheben während eines Einkaufs erfolgt kann hier die zugehörige BasketId übermittelt werden |
description |
Feld für weitere Freitext-Ergänzungen zur Protokollierung |
pin |
PIN der Karte, falls für das Abheben eine PIN-Eingabe notwendig ist (vgl. RequiresPin) |