Web API v3 · Entwurf

API-ReferenzWeb API v3 · Entwurf

API-REFERENZ

Web API v3 · Entwurf

Historischer Entwurf der Web API v3.

Entwurfv319 Endpunkte

Blueprint

Entwurf; für neue Integrationen die aktuelle POS API v3 verwenden.

BASE URLhttp://pos.dev.qnips.com/api/pos/v3

merchants

GETmerchants/{qnipsUserName}/brands/merchants/{qnipsUserName}/brands

trackingUnits

GETtrackingUnits/trackingUnits?qnipsUserName={string}&brandId={brandId}&instanceName={string}&city={string}&street={string}&postalIndex={string}POSTtrackingUnits/trackingUnits

baskets

POSTbaskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2}/baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2}POSTbaskets/{basketId}/grant?redeemedInPos={redeemedInPos}/baskets/{basketId}/grant?redeemedInPos={redeemedInPos}

sortiments

GETsortiments?thirdPartySortimentIdentifier={string1}&name={string2}/sortiments?thirdPartySortimentIdentifier={string1}&name={string2}POSTsortiments/{qnipsSortimentId}/group}/sortiments/{qnipsSortimentId}/group/{Id}PUTsortiments/{qnipsSortimentId}/group}/sortiments/{qnipsSortimentId}/group/{Id}DELETEsortiments/{qnipsSortimentId}/group/{Id}}/sortiments/{qnipsSortimentId}/group/{Id}POSTsortiments/{qnipsSortimentId}/article}/sortiments/{qnipsSortimentId}/article/{PLU}PUTsortiments/{qnipsSortimentId}/article}/sortiments/{qnipsSortimentId}/article/{PLU}DELETEsortiments/{qnipsSortimentId}/article/{PLU}?groupId={groupId}/sortiments/{qnipsSortimentId}/article/{PLU}POSTsortiments/{qnipsSortimentId}/bulkUpload?changedArticlesOnly={boolean}}/sortiments/{qnipsSortimentId}/bulkUpload?changedArticlesOnly={boolean}

tokens

POSTtokens/{id}?tokenType={tokenType}/tokens/{id}?tokenType={tokenType}POSTtokens/{id}/lock/tokens/{id}/lockPOSTtokens/{id}/dispose/tokens/{id}/disposeGETtokens/{id}/balance/tokens/{id}/balancePOSTtokens/{id}/addBalance?balanceToAdd={balanceToAdd}/tokens/{id}/addBalance?balanceToAdd={balanceToAdd}POSTtokens/{id}/withdrawBalance?balanceToWithdraw={balanceToWithdraw}/tokens/{id}/withdrawBalance?balanceToWithdraw={balanceToWithdraw}

Grundlagen & vollständige Einführung

Diese Seite beschreibt, wie Sie das menio-Funktionen in Ihre Software einbinden können. Diese Funktionen lassen sich größtenteils unabhängig voneinander nutzen, sodass auch eine Teil-Implementierung dieser Schnittstelle durchaus Sinn macht. Schauen Sie sich zunächst die verfügbaren Funktionsblöcke an und entscheiden Sie selbst, welche Teile davon Sie oder Ihr Kunde implementiert sehen möchte.

Dienst-Name	Beschreibung
Direktes Feedback zum Einkauf	Die Konsumenten können zu jedem einzelnen erworbenen Artikel nach einer Bewertung und einer Meinung gefragt werden. Ebenso ist mit dieser Funktion die Bewertung des Einkaufserlebnisses inkl. Bediener-Bewertung sowie weitere individuelle Fragen des Händlers möglich.
Clearing von Coupon- und Treue-Kampagnen	Ihre Software bekommt hier die genaue Auskunft über die im menio-System eingestellten, vielfältigen, für jede einzelne Transaktion individuell errechneten Coupon- und Treue-Aktionen, um diese direkt in Ihrer Software abspeichern und ggf. auf der Endabrechnung für den Konsumenten verrechnen zu können.
Digitaler Kassenbon	Da die Transaktionsdaten eines Konsumenten-Kaufs die Grundlage für unsere Funktionen darstellen, können wir jedem Konsumenten das Feature des Digitalen Bons anbieten. Damit hat er die Rechnungen jederzeit nur ein paar Klicks entfernt und kann mit diesen auch Rückgaben und Artikelumtausch abwickeln.
Mobile Payment	menio erlaubt bequeme mobile Zahlungen an Ihrem POS über diverse etablierte Zahlungsdienste.
Kundenkarten	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-/QRCode-Karten etc.) als Mittel zur Identifizierung eines Kunden-Profils und Bereitstellung der menio-Angebote umgesetzt werden.
(Kunden)-Karten mit Auflade und Zahl-Funktion	Damit können Sie Ihrer Zielgruppe (z.B. in der Gemenschaftsverpflegung) eine bequeme Zahl- bzw. Geschenkkarten-Funktion anbieten, die keine besondere Aufwerter-Hardware braucht.

Let's get started!

Grundlegendes

Art der Schnittstelle

Unsere API ist als REST-API realisiert. Die Clients müssen also u.U. eine Bibliothek zum Verarbeiten von HTTP-Calls (GET, POST, PUT, DELETE) einbinden. Die Bibliothek muss in der Lage sein, dem Request spezifische Header hinzuzufügen.

URL

URL Struktur ist folgende https://{domain}/api/v3/{resource}/{id}[/{action}][?paramName={paramValue}]

Code	Beschreibung
{domain}	Für produktiven Betrieb setzen Sie hier pos.api.qnips.com. Zur Entwicklungszeit verwenden Sie bitte pos.dev.qnips.com.
/api/v3/	Das ist ein fixer Part, der die Version der Schnittstelle angibt. Sollten in Zukunft aktuellere Versionen entstehen, werden Sie gesondert dazu benachrichtigt.
{resource}	Dies spezifiziert den Typ der Datenobjekte, auf welche Sie zugreifen wollen. Unterstützte Typen sind u.a. trackingUnits, baskets, sortiments, products, purchases, tokens
{id}	id spezifiziert die ID des speziellen Objekts, auf welchen zugegriffen werden soll.
{action}	Auf manchen Datenobjekten sind besondere Operationen möglich, die als {action} angegeben werden können
{paramValue}	Optional sind bei manchen Calls zusätzliche URL-Parameter erforderlich, um die Aktion genauer zu spezifizieren

Beispiel: http://pos.dev.qnips.com/api/v3/trackingUnits/123/purchase?customerIdentToken=abc&basketId=1001 wird einen Kauf mit der Rechnungsnummer 1001 (basketId=1001) mit einem Konsumenten verknüpfen, der sich am POS mit einer Kundenkarte (token=abc) identifiziert hat.

XML/JSON als Datenformat

Als Formate sind XML und JSON wählbar. Dies kann über die Header 'Accept' und 'ContentType' gesteuert werden. Ohne explizite Angaben zum gewünschten Datenformat über die besagten Header wird XML als Default-Format genommen.

Encoding

Encoding der Parameter

Da in der URL keine Leerzeichen, Zeilenumbrüche, Umlaute, Nicht-lateinische-Zeichen und bestimmte Sonderzeichen erlaubt sind, müssen die Werte für bestimmte Parameter zuvor URL-escaped werden.

Beispiel: Der String “Kölner Treff” müsste vor dem Call zu “K%C3%B6lner%20Treff” umgewandelt werden.

Encoding im Body

Bitte platzieren Sie im Body von Requests stets ein in utf-8 kodiertes XML/JSON.

Encoding im XML

Bitte beachten Sie dass im XML bestimmte Zeichen ebenfalls nicht als Werte für XML-Tags erlaubt sind, sodass auch hier ggf. ein URL-Escaping statt finden soll

Beispiel: <name>Drinks&Food</name> müsste mindestens zu <name>Drinks%26Food</name> umgewandelt werden.

Status Codes

Die Responses werden immer einen der folgenden HTTP-Statuscodes enthalten.

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.

HTTP-Header

Jede Resource unserer API ist mit zwei speziellen obligatorischen Headern geschützt, anhand derer einerseits der Aufrufer und andererseits der Hersteller des aufrufenden Clients identifiziert werden.

Obligatorische Header

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 Resourcen 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 Reource beschrieben. Der Berechnungsalgorythmus ist stets derselbe und ist hier beschrieben.

Secutiry-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 Resource 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 Algorythmus 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 esten 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.

QR-Code-Aufbau

Ein QR-Code hat in unserem System die Aufgabe, einen Einkauf mit einem Konsumenten zu verknüpfen. Dies wird dadurch erreicht, dass zwei Identifier in den QR-Code gepackt werden, anhand derer einerseits die ausgebende POS-Instanz und andererseits der vom Konsumenten gekaufte Warenkorb ( basket ) identifiziert werden können.

Daher hat der QR-Code immer die folgende Struktur:
“http:\app.qnips.com\t1\{trackingUnitId}\{basketId}”, wobei:

• {trackingUnitId} - der Identifier der POS-Instanz, an welcher der gegebene Warenkorb erstellt und erworben wurde (siehe GET trackingUnits)

• {basketId} - der Identifier des Warenkorbs, unter welchem die Warenkorbdaten an unser System übermittelt worden sind (siehe POST baskets/{basketId})

Begriffsdefinition

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

• merchant (Händler) - ein Händler ist ein durch seinen eindeutigen Namen ( merchantName, z.B. 'Restaurant Vier Jahreszeiten') differenzierbarer Träger von einem oder mehreren Verkaufsstandorten (Filialen), in welchen wiederum mehrere trackingUnits (i.d.R. POS-Terminals) existieren können

• trackingUnit (POS-Terminal) - jeder POS-Terminal, welcher eine Rechnung in Ihrem POS-System erzeugen und abrechnen kann, sollte sich als eigenständige trackingUnit in unserem System registrieren, damit wir jede Aktion bis auf diese trackingUnit nachverfolgen und ggf. asynchron auftretende Ereignisse (z.B. Zahlungsbestätigung beim Mobile Payment) an genau die trackingUnit zurückmelden können

• store (Filiale) - in der Regel wird ein merchant die meisten Vorgänge auf Filialebene nachvollziehen wollen. Daher stellen die stores eine sinnvolle Gruppierungsebene für trackingUnits. Darüber hinaus werden die stores für Konsumenten als nach Entfernung zum eigenen Standort sortierte Filialen in der menio-App dargestellt, sofern uns die Adress-Daten der stores vorliegen. Die Zuweisung der trackingUnits zu stores, sowie die Pflege der Adressdaten der stores können sowohl automatisiert aus Ihrem System heraus, als auch vom merchant händisch über unser Web-Portal erfolgen

• 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

• purchase (Kauf-Ereignis) - hiermit ist eine Verlinkung eines baskets mit einem Konsumenten-Profil gemeint, die auf einem der folgenden zwei Wege zustande kommen kann:

  • über QrCode - die trackingUnit druckt einen QrCode auf der Rechnung ab, der vom Konsumenten abgescannt werden muss. Dadurch wird der basket mit dem Konsumenten-Profil des Scanners verknüpft.
  • über Konsumenten-Identifikation am POS - diese kann auf vielerlei Wegen erfolgen, die letztendlich mit jedem Händler individuell abzustimmen sind, z.B. über das Einlesen einer Kundenkarte, oder durch das Abscannen eines Identification-QrCodes vom Bildschirm des Smartphones, oder durch die Übermittlung des Identifiers vom Smartphone über NFC etc.

• cosumer (Kosument) - damit ist ein Endkunde gemeint, der in einem store eines merchants einen basket erwirbt und dieses Kauf-Ereignis ( purchase ) entweder über einen Scan des QrCodes 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 QrCodes existieren, der vom POS-System entweder eingescannt oder über ein anderes Trägermedium eingelesen werden kann.

• 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.

Client-Registrierung

Jedes POS-Terminal, das eigenständig mit dem menio-System kommuniziert und vor allem eigenständig eine Rechnung in Ihrem POS-System erzeugen und abrechnen kann, muss eine eindeutige trackingUnitId vom menio-System erfragen. Somit stellen wir sicher, dass der merchant in der Lage ist, alle Vorgänge auf der Ebene eines einzelnen Kassenplatzes nachzuverfolgen. Dazu ist, sofern der Client noch nicht über eine trackingUnitId verfügt, einmalig ein GET trackingUnits-Call auszuführen und das Ergebnis des Calls im Client dauerhaft zu persistieren.

Standort-Bezug einer TrackingUnit herstellen (optional)

Mittelfristig wird der merchant gewillt sein, die einzelnen trackingUnits in einer, seiner Organisation entsprechender Filialstruktur zu platzieren. Dazu gibt es zwei Wege:

• Über die API - Verfügt Ihre Software über die korrekten Adressdaten zum eigenen Standort, sollte Ihre Software diese Daten an menio melden, sodass menio ggf. automatisch eine Filial-Einheit für den Merchant anlegen und die trackingUnit dort einordnen kann. Dazu bitte einen POST trackingUnit-Call ausführen

• Über das menio-Portal - in diesem Fall werden neu angelegte trackingUnits mit dem Flag notCategorized angelegt und der Merchant aufgefordert, die trackingUnit manuell über das menio-Portal in eine Filiale einzuordnen

Wird die Kasse irgendwann an einen anderen Standort verbracht, sollte diese Standortänderung entweder über einen weiteren POST trackingUnit-Call (sofern die Adressdaten in der Kasse aktualisiert werden) oder durch den manuellen Eingriff des merchants im menio Dasboard bewerkstelligt werden. Bis zur Meldung dieses Umzugs würden die von dieser Kasse im menio-System erzeugten Daten noch unter der alten Filiale zusammenlaufen.

Einkaufsbewertung

Unter Einkaufsbewertung verstehen wir:

• artikelgenaues Produktfeedback

• Bediener-Bewertung

• Beantwortung beliebiger, vom merchant hinterlegter Fragen im Kauf-Kontext.

Die Bewertung erfolgt über einen Fragebogen, der aus einem basket-Datensatz generiert und dem consumer angezeigt wird, sobald er sich als Käufer des jeweiligen baskets legitimiert.

1. Identifiziert sich der Konsument direkt am POS (z.B. indem das POS einen QrCode vom Bildschirm seines Smartphones abliest), fügen Sie dem Upload des basket-Datensatzes (siehe POST baskets/{basketId}) den optionalen consumerIdentToken-Parameter hinzu.

   Dies wird eine Push-Nachricht ans Smartphone des Konsumenten generieren,mit der Bitte, den Fragebogen auszufüllen.

2. Gibt es keine direkte Konsumenten-Identifikation am POS, so kann der Konsument den vom POS-System auf der Rechnung gedruckten QRCode abscannen und bekommt den Fragebogen eben nach dem Scan serviert.

Drucken Sie daher auf jedem Rechnungsbeleg einen QRCode mit folgendem Inhalt auf, nachdem Sie POST baskets/{basketId} ausgeführt haben:

“http:\app.qnips.com\t1\{trackingUnitId}\{basketId}”

Rewards

menio bietet fogende Rewardtypen 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

Die auf einen basket anrechenbaren Rewards werden immer sofort nach dem Upload des basket-Datensatzes in Echtzeit errechnet und an Ihre Software zurückgeliefert. 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 ( token1 )

   Je nach Wunsch eines Händlers kann die Identifizierung eines Konsumenten individuell geartet sein. So ist z.B. das Einlesen eines consumerIdentTokens von einer Kundenkarte, vom Display des Smartphones des Konsumenten oder z.B. über einen NFC-Reader möglich. Allen ist jedoch gemein, dass am Ende am POS ein sogenannter consumerIdentToken vorliegt, der im menio-System eindeutig einem Konsumenten-Profil zugeordnet ist

3. Erfassen Sie ggf. vorgezeigte Geschenk-/Guthabenkarte ( token2 )

4. Rufen Sie POST baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2} auf

   Der Response auf diesen POST könnte wie folgt aussehen:

    {
        "Rewards":[
            {
                "RewardType":1,
                "ProductId":"123",
                "NetRewardValue":10.0,
                "ApplicableTaxInPercent":19.0
            }],
        "Balances":[
            {
                "TokenId":"member123",
                "Balance":50.0,
                "CurrencyISO":"EUR"
            },
            {
                "TokenId":"giftCardABC",
                "Balance":25.0,
                "CurrencyISO":"EUR"
            }]
    }
   

5. Verarbeiten Sie Rewards im Response

   Sie können die Rewards direkt in die Rechnung einarbeiten und den Rechnungsbetrag entsprechend reduzieren. Bitte beachten Sie, dass die nicht auf ein Einzelprodukt bezogenen Rewards in Ihrer Software ggf. auf die einzelnen Rechnungspositionen umgelegt werden müssen, um die korrekte Mehrwertsteuer auf den Reward-Betrag ermitteln zu können. Solche Rewards erkennen Sie am RewardType=2.

   Werden die Rewards nicht von Ihrer Software direkt verrechnet, kann die Auszahlung der Rewards über das menio-Cashback-System erfolgen - die Rewards werden vom menio-System dem Konto des Händlers belastet und dem vituellen consumer-Konto gutgeschrieben, von welchem der Konsument die Auszahlung seiner gesammelten Rewards jederzeit über die menio-App oder den consumer-Webclient beantragen kann.

   Die Auszahlung als Cashback kommt immer dann zum Tragen, wenn der Konsument sich nicht während des Kaufs am POS identifizieren kann und sich erst im Nachgang über den Scan des QrCodes auf der Rechnung als Käufer des baskets und somit auch als legitimer Empfänger der im basket eventuell enthaltener Rewards ausweist.

6. Verarbeiten Sie Balances im Response

   Wurde beim Einreichen des baskets (Schritt 4) ein consumerIdentToken und/oder eine Geschenkkarten-ID angegeben, wird der Response ggf. die Information über mögliche Guthaben enthalten. Diese Guthaben können nach Ihrem Ermessen bzw. nach dem Wunsch des Händlers mit dem Rechnungsbetrag verrechnet werden. Fangen Sie bei der Anrechnung bitte immer mit dem Guthaben der Geschenkkarte an.

   Wurden die im Response ausgewiesenen Guthaben ganz oder anteilig mit dem Rechnungsbetrag verrechnet, müssen diese in unserem System um den entsprechenden Betrag reduziert werden. Führen Sie dazu POST token/{id}/withdrawBalance} aus

7. basket 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. Somit lässt sich eine nachträgliche Stornierung oder Nacherfassung von Positionen in einem basket abbilden. 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.

   Führen Sie dazu POST baskets/{basketId}/grant?redeemedInPos={boolean} aus und geben Sie im redeemedInPos-Parameter an, ob der POS-Client auf Direktverrechnung der menio-Rewards eingestellt ist oder nicht (siehe Schritt 5)

ACHTUNG: Mit der Implementierung des oben beschriebenen Prozesses lassen sich alle umsatzbasierten Rewards nutzen. Damit ein Händler auch produktbasierte Rewards erstellen kann, muss unser System zumindest die Produkte kennen, für welche der Händler Rewards definieren möchte. Dazu muss Ihre Software zusätzlich das Kapitel Sortimentspflege implementieren.

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 QrCode-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 QrCode einer Papierkarte

• in einem RFID-Transponder

• als virueller 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 herunterladenStand der Dokumentation