Web API v3 · Deutsch

Diese Seite beschreibt, wie Sie die menio-Funktionen in Ihre Software einbinden können. Die API ist grob in 5 Bereiche unterteilt, die unabhängig voneinander implementiert werden können, sodass auch eine Teilimplementierung der menio-Funktionalität möglich ist.

Bereich	Beschreibung
Registrierung neuer API-Clients	Hier wird beschrieben, wie ein neuer Client sich an der API registriert und automatisch in die virtuelle Organisationsstruktur eines Händlers einordnet.
Warenkorb-Handling	Echtzeit-Berechnung und Reporting von Rabattaktionen und Treue-Kampagnen auf Grundlage eines Warenkorbs sind Themen in diesem Bereich.
Sortimentspflege	Hiermit lassen sich Produktdaten ins menio-System einspielen, was folgende Funktionsbereiche ermöglicht: Produkt- und Warengruppenbasierende Treue-Kampagnen und individualisierbare Sofortrabatte, digitale Speisepläne und Speisekarten, Bestellfunktionalität.
Kunden-/Guthaben-/Geschenk-Karten	Um die Vorteile der menio-Funktionen nicht ausschließlich den Smartphone-Nutzern vorenthalten zu müssen, können diese auch mit einer beliebig gearteten Kundenkarte (Magnetkarte, NFC-/RFID-Transponder, Barcode-/QR-Code-Karten etc.) als Mittel zur Identifizierung eines Kunden-Profils und Bereitstellung der menio-Angebote umgesetzt werden. Kundenkarten können in unserem System mit Guthaben aufgeladen werden, welches dann als Zahlungsmittel genutzt werden kann.
Mobile Payment	menio erlaubt bequeme mobile Zahlungen an Ihrem POS über diverse etablierte Zahlungsdienste.

Let's get started!

Grundlegendes

Unsere API ist als REST-API realisiert. Nutzen Sie daher eine HTTP-Client-Bibliothek, um die entsprechenden GET, POST, PUT und DELETE Operationen auf einzelnen Ressourcen unserer API auszuführen. Die verfügbaren Ressourcen lassen sich über eindeutige URLs aufrufen.

Beispiel: GET https://{pos.prelive.qnips.com}/api/{v3}/{brands}/{123}

Werte in geschweiften Klammern haben jeweils folgende Bedeutung:

Code	Beschreibung
`{pos.prelive.qnips.com}`	Das ist die Haupt-Domain unserer API. Tauschen Sie diesen Wert auf produktiv eingesetzten Systemen gegen `pos.api.qnips.com` aus
`{v3}`	Version der Schnittstelle. Aktuell ist 'v3' zu nutzen.
`{brands}`	Name der aufzurufenden Ressource, auf welche Sie zugreifen wollen. Folgende Ressourcen sind vorhanden: merchants, trackingUnits, baskets, sortiments, products, tokens
`{123}`	`id` des durch den Ressourcen-Namen spezifizierten Objekts, welches ausgeliefert werden soll.

Requests

Jede Ressource unserer API ist mit zwei speziellen obligatorischen HTTP-Headern geschützt:

Header-Name	Beschreibung
`DevKey`	Hier ist Ihr DeveloperKey einzutragen, den Sie bei uns beziehen können.
`trackingUnitId`	Jeder einzelne Client, der die menio API aufrufen möchte, muss sich zunächst am menio System registrieren (siehe Client-Registrierung), wodurch er in den Besitz einer eindeutigen `trackingUnitId` kommt, die hier bei jedem weiteren Call anzugeben ist.

Optionale Header

Weiterhin gibt es einige optionale Header, mit denen z.B. das Wunschformat (JSON oder XML) für den Datenaustausch angegeben werden kann.

Header-Name	Beschreibung
`Accept`	Hiermit geben Sie an, ob Sie die Ergebnisse eines Calls im XML- oder JSON-Format erwarten. Erlaubt sind `application/xml` und `application/json`. Default ist `application/xml`.
`Content-Type`	Hierüber geben Sie an, ob der Content im Body Ihrer POST- und PUT-Requests XML oder JSON ist. Erlaubt sind `application/xml` und `application/json`. Default ist `application/xml`.
`Accept-Encoding`	Zur Reduzierung des Traffics und zur Beschleunigung der Interaktion mit der qnipsAPI unterstützt diese die gezippte Übertragung der Inhalte. Wird dieser Header im Request mit 'gzip' gesetzt, so ist der Content im Response gezippt.
`Content-Encoding`	Bei manchen POST-Calls ist es sinnvoll, auch den Inhalt des Request-Bodys gezippt zu übertragen. Setzen Sie in diesem Fall diesen Header mit 'gzip'. Dadurch merkt das Backend, dass der Request gezippt ist und entzippt es vor der Verarbeitung
`SecurityToken`	Manche Ressourcen sind zusätzlich mit einem dynamisch zu berechnenden Security-Token geschützt, um besonders sensible Teile der API zu schützen. Aus welchen Teilen des Requests ein solcher Token zu bilden ist, ist direkt bei der Spezifikation der Ressource beschrieben. Der Berechnungsalgorithmus ist stets derselbe und ist hier beschrieben.

Bitte platzieren Sie im Body von Requests stets ein in utf-8 kodiertes XML/JSON. Beachten Sie auch dass im XML bestimmte Zeichen ebenfalls nicht als Werte für XML-Tags erlaubt sind, sodass ggf. ein URL-Escaping der Werte statt finden soll Beispiel: <name>Drinks&Food</name> müsste mindestens zu <name>Drinks%26Food</name> umgewandelt werden.

Responses

API-Responses sind dabei normale HTTP-Responses mit einem HTTP-Statuscode, Response-Headern und ggf. Response-Body

Es werden folgende HTTP-Statuscodes verwendet:

Code	Beschreibung
`200`	Success - Markiert die erfolgreiche Ausführung.
`400`	Bad Request - Request kann aufgrund von fehlgeschlagenen Validierungen bzw. unerfüllten Vorbedingungen nicht durchgeführt werden. Bitte verarbeiten Sie bei solchen Fehlern die ErrorId im Response-Body, da in manchen Fällen eine Wiederholung des Requests Sinn macht.
`401`	Unauthorized - DevKey, trackingUnitId oder Security-Token ist/sind gar nicht bzw. falsch angegeben.
`500`	Server error - Während der Verarbeitung ist etwas schief gelaufen. Im Body stehen idR mehr Details zum Fehler, die für Logs und Entwickler gedacht sind, sich jedoch nicht zur Ausgabe am UI eignen.

Im Erfolgsfall wird im Response-Body gegebenenfalls ein als XML oder JSON (abhängig vom gesetzten Content-Type-Header) serialisiertes Objekt ausgeliefert

Security-Token

Da bei Calls der menio-WebAPI-Ressourcen die Parameter im Klartext übertragen werden, können auch bei hinreichender SSL-Verschlüsselung die Man-in-the-Middle-Angriffe nicht vollständig ausgeschlossen werden. Daher wird menio die Übertragung von sicherheitsrelevanten Parametern über einen sog. SecurityToken schützen, der vor dem Request dynamisch zu berechnen und dem Request als Header beizufügen ist und im menio-Backend vor der Verarbeitung des Requests validiert wird. Dieser SecurityToken ist gesichert durch:

einen, den dritten unbekannten, Berechnungsalgorithmus
einen je trackingUnit individuellen Geheimschlüssel (checksumSecret), der bei der Registrierung der trackingUnit zugewiesen wird (siehe GET trackingUnits)

Jede, mit einem SecurityToken geschützte Ressource definiert, für welche Bestandteile der Eingabeparameter ein SecurityToken zu bilden ist. Die Methode zur Berechnung des SecurityTokens nimmt also einen String an und liefert den Token ebenfalls als String zurück. Hier der Algorithmus für diese Methode:

einen String mit input + „qPnsS14“ + checksumSecret“ bilden, mit:
- input: der Wert, für den die Prüfsumme berechnet werden soll
- „qPnsS14“: ein konstanter String
- checksumSecret: Schlüssel, welcher dertrackingUnit bei der Registrierung zugewiesen wurde
Beispiel mit input=„123456“ und checksumSecret=„af87b1“: „123456qPnsS14af87b1“
Für das Ergebnis aus dem ersten Schritt einen MD5-Hash bilden. Für den Wert aus dem oben gezeigten Beispiel, würde der MD5-Hash folgender sein: „1283ff82ae8e9ace636449a519d99fa9“
Dieser Hash ist der SecurityToken. Packen Sie ihn nun in den SecurityToken-Header des Requests, damit der Request an unserem Backend verarbeitet werden kann.

Begriffsdefinition

Diese API-Beschreibung nutzt einige Begriffe, die wie folgt zu verstehen sind:

merchant (Händler) - ein Händler ist ein durch seinen eindeutigen menio-Usernamen (z.B. 'max@mustermann.de') differenzierbarer Träger von einem oder mehreren Verkaufsstandorte (outlet). Die outlets können ihrerseits in einer oder mehreren Handelsmarke (brand) eingeordnet sein.
brand (Handelsmarke) - eine Handelsmarke ist in der Regel ein Verbund mehrerer Standorte (outlet), die unter einer einheitlichen Marke bzw. Corporate Identity betrieben werden (z.B. 'Pizza Hut'). Ein merchant kann dabei Besitzer von mehreren solchen brands sein und sie als eigenständige Einheiten in menio verwalten.
outlet (Verkaufsstandort) - ein Verkaufsstandort ist in der Regel eine Filiale, die durch ihre eindeutige Adresse von anderen Filialen (bzw. Verkaufsstandorten) unterschieden wird.
trackingUnit (POS-Terminal) - gibt es in einem outlet mehrere Orte, an denen Rechnungen mit eigenständigen Rechnungsnummernkreisen abgewickelt werden können, so ist jeder solche Ort als sog. trackingUnit in unserem System eigenständig zu registrieren. Wird die Rechnungsstellung auch bei mehreren Terminals zentral abgewickelt, so reicht es nur die zentrale Einheit als trackingUnit zu registrieren.
sortiment (Produktstamm) - Ein Produktstamm ist eine Organisationseinheit für die vom merchant als Reward-fähig markierte Verkaufsartikel, die am POS in einen basket gebucht werden können. Solche Artikel müssen dem menio-System durch einen Upload bekannt gemacht werden, damit der merchant einen Reward auf diese Artikel definieren kann.
basket (Warenkorb) - das ist ein Objekt, welches die Daten über die vom Konsumenten gekauften Positionen beinhaltet, so wie sie im Kontext einer Rechnung in einer trackingUnit erfasst wurden
consumer (Konsument) - damit ist ein Endkunde gemeint, der in einem store eines merchants einen basket erwirbt und dieses Kauf-Ereignis ( purchase ) entweder über einen Scan des QR-Codes oder über Identifikation am POS mit seinem Konsumenten-Profil im menio-System verknüpft
consumerIdentToken - damit ist ein auf einem beliebigen Trägermedium gespeicherter, beliebig gearteter Token gemeint, der eindeutig mit einem consumer-Profil verknüpft ist und somit dafür geeignet ist, den Konsumenten eindeutig zu identifizieren. Dieser Token kann z.B. in einer Kundenkarte gespeichert sein, oder in Form eines gedruckten oder virtuellen Barcodes oder QR-Codes existieren, der vom POS-System entweder eingescannt oder über ein anderes Trägermedium eingelesen werden kann.

Client-Registrierung

Jede Instanz in Ihrem System, die eigenständig eine Rechnung erzeugen und abschließen kann, muss eine eindeutige trackingUnitId vom menio-System erfragen. Dazu ist, sofern der Client noch nicht über eine trackingUnitId verfügt, einmalig ein GET trackingUnits-Call auszuführen und das Ergebnis des Calls in der aufrugenden Instanz dauerhaft zu persistieren.

Dabei ist es wichtig, für jede zu registrierende trackingUnit einen Bezug zum outlet herzustellen. Dazu muss muss beim GET trackingUnits-Call eine outletId angegeben werden. Diese kann auf zweierlei Wegen geholt werden:

GET merchants-Info - Rufen Sie mit diesem Call die für einen merchant in unserem System verfügbaren outlets ab und lassen Sie das gewünschte outlet auf dem UI auswählen
POST outlet - Verfügt Ihr System über die Adresse des Standorts, in welchem es eingesetzt wird, kann ein outlet auch aus Ihrem System heraus über einen API-Call neu angelegt werden. Im Response auf diesen Call finden Sie die benötigte outletId

Wird die Kasse irgendwann an einen anderen Standort verbracht, sollte die neue outletId unserem System über Standortänderung entweder über einen POST trackingUnits-Call mitgeteilt werden.

Warenkorb-Handling

Mit Warenkorb-Handling ist eine Echtzeitberechnung von möglichen im menio-System definierten Rabatten und Treuepunkten auf einen bestimmten Warenkorb gemeint. Dieser Prozess setzt sich aus Calls auf zwei Ressourcen unserer API zusammen:

POST basket - damit wird der Warenkorb unter Nutzung einer eindeutigen ID eingereicht, mögliche Rabatte und Treuepunkte berechnet und im Response an die Kasse zurückgegeben. Ein Warenkorb kann mehrfach neu eingereicht werden, wobei jede Neueinreichung die Berechnung der Rabatte und Treuepunkte neu in Gang setzen würde.
POST basket-grant - damit wird ein Warenkorb als abgeschlossen markiert. So markierte Warenkörbe lassen sich nicht neu berechnen.

menio bietet folgende Reward-Typen an:

Umsatzbasierte Coupons (z.B. ab 20€ Umsatz 10% Rabatt)
Produktbasierte Coupons (z.B. 20% auf alle Herrenstiefel)
Coupons auf Produktkombinationen (z.B. Schnürsenkel zum Herrenschuh zum halben Preis)
Mengencoupons (z.B. 3 zum Preis von 2)
Umsatz- und/oder produktbasierte Punkte-Sammelsysteme mit flexibel gestaltbaren Rabatten

Der vollständige Prozess der Reward-Anrechnung sieht wie folgt aus:

1. Erfassen Sie den Warenkorb
2. Führen Sie ggf. eine Konsumenten-Identifizierung durch
Lesen Sie dazu von einer am POS vom Konsumenten vorgelegten Kundenkarte oder Smartphone über ein geeignetes Lesegerät (z.B. Imager, Magnetkartenleser, NFC/RFID-Leser etc. den darin gespeicherten Kundenidentifier aus und speichern Sie diesen als sogenannten consumerIdentToken zwiscen.

3. Rufen Sie POST basket auf
Der Response auf diesen POST könnte wie folgt aussehen:

  {
      "Rewards":[
          {
              "ProductId": "20019",
              "Name": "30% auf Großes Kaffeegetränk und einen Donut",
              "GrossRewardValue": 0.72,
              "CouponId": 683,
              "RewardTriggeringPositionId": 1,
              "RewardType": 1
          },
          {
              "ProductId": "151",
              "Name": "30% auf Großes Kaffeegetränk und einen Donut",
              "GrossRewardValue": 0.53,
              "CouponId": 683,
              "RewardTriggeringPositionId": 2,
              "RewardType": 1
          }
      ],
      "LoyaltyInfo": [
          {
              "Name": "Ein Punkt für jedes Heißgetränk",
              "LoyaltyId": 171,
              "Details": [
                  {
                      "PreviousPoints": 7,
                      "NewPoints": 2,
                      "PointsInScheme": 10,
                      "GrossRewardValue": 0,
                      "RewardTriggeringPositionId": 1
                  }
              ]
          }
      ]
  }

4. Verarbeiten Sie Rewards im Response
Sie können nun die Rewards direkt in die Rechnung einarbeiten und den Rechnungsbetrag entsprechend reduzieren.
5. Warenkorb als abgeschlossen markieren
Solange ein basket nicht abgeschlossen (granted) ist, kann er beliebig oft neu eingereicht werden. Mit jeder Neueinreichung würden die Rewards neu berechnet werden und die alten ersetzen. Ist jedoch aus der Sicht des Konsumenten ein finaler Stand erreicht und der Rechnungsbetrag beglichen, muss der basket in unserem System als granted markiert werden. Erst dadurch wird unser System eine Notification über einen getätigkten Kauf an den Konsumenten verschicken (per Email oder per Push, wenn der Konsument ein menio-App-Nutzer ist). Rufen Sie dazu POST basket-grant auf

Sortimentspflege

Unter Sortimentspflege verstehen wir den initialen Upload sowie das Updaten der Produkt-/Artikel-Daten in unserem System. Die Sortimentspflege ist eine Voraussetzung für folgende menio-Features:

produktbezogene Rewards

Für produktbezogene Rewards ist es ausreichend, nur solche Produkte (bzw. Produktgruppen) an das menio-System zu übermitteln, für die der merchant einen Reward einrichten will. Hierbei reicht es, wenn die Artikel in Ihrer Minimalform (nur PLU und Name, sowie ggf. eine Warengruppenzuordnung) eingereicht werden.
Menükarten-Anzeige in der App inkl. Allergen-/Nährwert-/Zusatzstoffe-Angaben

Speziell für Gastronomie und Gemeinschaftsverpflegung im Speziellen bieten wir die Funktion eines umfangreichen, LMIV-konformen Speiseplans mit eigenem Allergen-/Zusatzstoff-Management auf Artikelebene. Verfügt Ihr System über solche Angaben, können sie ebenfalls an unserem System hochgeladen werden, sodass das Allergen-/Zusatzstoff-Management weiterhin in Ihrer Software verbleibt und lediglich die Zusammenstellung des Speiseplans über uns erfolgen kann

HINWEIS: Implementieren Sie das Feature bitte so, dass der merchant letztendlich entscheiden kann, in welchem Umfang ein Sortiment an menio hochgeladen wird, indem Sie in Ihrem System z.B. eine Möglichkeit schaffen, die an menio zu übertragenen Artikel als solche zu markieren.

Sortimente

Artikeldaten sind im menio-System in so genannten sortimenten organisiert. Ein sortiment kann von mehreren trackingUnits an einem oder auch an unterschiedlichen Standorten gemeinsam verwendet werden. Das einzige Unterscheidungsmerkmal, ob ein Artikel von mehreren trackingUnits im selben Sortiment gepflegt werden kann, ist die Eindeutigkeit seiner PLU → ist unter der selben PLU auf zwei trackingUnits ein unterschiedlicher Artikelname erfasst, so müssen diese Artikel in unterschiedliche Sortimente geladen werden.

Rufen Sie dazu GET sortiments?thirdPartySortimentIdentifier={string1}&name={string2} auf.

Upload

Die Artikeldaten lassen sich sowohl einzeln als auch per BulkUpload hochladen bzw. updaten:

POST / PUT / DELETE sortiments/{qnipsSortimentId}/group
POST / PUT / DELETE sortiments/{qnipsSortimentId}/article
POST sortiments/{qnipsSortimentId}/bulkUpload?changedArticlesOnly={boolean}

Kundenkarten

Kundenkarten sind neben QR-Code-Scans eine weitere Möglichkeit, einen basket mit einem bestimmten Konsumenten-Profil zu verknüpfen. Das Verfahren dabei ist recht einfach: am POS wird ein beliebig gearteter Identifier von irgendeinem vom Konsumenten am POS vorgezeigten Identifier-Träger ausgelesen und als consumerIdentToken zusammen mit einem basket an unserem System eingeschickt.

Daher ist es für uns unwichtig, ob dieser Token

auf einem Magnetstreifen oder NFC-Chip einer Plastikkarte
im Barcode oder QR-Code einer Papierkarte
in einem RFID-Transponder
als virtueller Token auf dem Smartphone des Konsumenten
oder sonstiges

gespeichert ist. Genauso unwichtig ist es, von wem ein solcher Token generiert worden ist, solange er unveränderbar und eindeutig genug ist, um seinen Halter von anderen Konsumenten unterscheiden zu können.

Kundenkarte registrieren

Eine Kundenkarte lässt sich daher einfach realisieren, indem der in der Karte gespeicherte Karten-Identifier als sogenannter token in unserem System bekannt gemacht wird. Lesen Sie dazu den Identifier von einer Karte aus, die Sie an den Konsumenten als Kundenkarte aushändigen wollen und führen Sie POST tokens/{id} unter Angabe dieses Identifiert als {id} aus.

Kundenkarte sperren

Sperrung von Kundenkarten kann vom Merchant entweder direkt im Webportal vorgenommen werden, oder, wenn Ihre Software die führende Verwaltungsstelle für Kundenkarten darstellt, über einen API-Call uns mitgeteilt werden. Führen Sie dazu eine der beiden Aktionen aus:

POST tokens/{id}/lock

Diese Aktion macht eine Karte komplett unbrauchbar.
bzw. POST tokens/{id}/dispose

Entbindet die Karte lediglich von einem Konsumenten-Profil, die Karte selbst steht jedoch für eine neue Registrierung und eine Verwendung durch einen anderen Konsumenten weiterhin zur Verfügung

Karte mit Guthaben aufladen

Kundenkarten können mit einem Guthaben aufgeladen werden. Die Aufladung kann einerseits vom Konsumenten über unser Konsumenten-Portal aufgeladen werden (z.B. mittels einer Überweisung oder via PayPal). Andererseits wäre es sinnvoll, eine Auflademöglichkeit auch am POS zu schaffen. Stellen Sie dazu einem Konsumenten eine Rechnung aus, ziehen Sie das Geld ein und buchen Sie das Guthaben auf seine Kundenkarte, indem Sie den token seiner Kundenkarte erfassen und den folgenen Call durchführen:

POST tokens/{id}/addBalance?balanceToAdd={balanceToAdd}

Guthaben abheben

Liegt auf einer Kundenkarte ein Guthaben und wird von Ihrem System ein basket mit dem token dieser Kundenkarte eingeschickt, so wird der Response zum POST basket/{basketId}?consumerIdentToken={token1} die Höhe dieses Guthabens enthalten.

Wird der Anteil dieses Guthabens mit dem Rechnungsbetrag verrechnet, so rufen Sie POST tokens/{id}/withdrawBalance?balanceToWithdraw={balanceToWithdraw} auf.

Geschenkkarten

Eine Geschenkkarte wird in unserem System komplett wie eine Kundenkarte behandelt, mit dem einzigen Unterschied, dass der Halter einer Geschenkkarte im Unterschied zum Halter einer Kundenkarte keinen öffentlichen Zugang über das Konsumenten-Portal zu den Aktivitäten (Auflade- und Entlade-Vorgänge, mit der Karte gekaufte und ggf. bezahlte baskets etc.) erhält.

Implementierungstechnisch ist eine Geschenkkarte jedoch komplett zur Kundenkarte identisch

API Blueprint herunterladen Stand der Dokumentation