POST baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2} · Web API v3 · Entwurf

POST baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2}

Web API v3 · Entwurf v3baskets

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

POST/baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2}

Ein basket ist der Inhalt einer Rechnung und stellt die Grundlage für die meisten menio-Funktionen dar. Das Ergebnis dieses Calls beinhaltet immer die möglichen Rewards, für die im basket enthaltenen Produkte. Diese errechneten Rewards stellen ein vorläufiges Ergebnis fest und müssen von Ihrer Software als granted markiert werden, sobald der Rechnungsbetrag voll beglichen ist, damit die Rewards wirksam werden und dem consumer als eingelöst gemeldet werden können (siehe POST baskets/{basketId}/grant)

Wurden beim Call ein consumerIdentToken oder eine giftCardId angegeben, so kann der Response auch die Information über potentiell vorhandene Guthaben entweder auf dem Konsumenten-Profil oder auf der Geschenk-Karte enthalten.

Solange ein basket nicht granted ist, kann er über den erneuten Call auf diese Resource beliebig oft geupdated werden, z.B. weil kurzerhand noch eine Position nachgebucht oder gestrichen wurde (ein häufiger Fall in der Gastronomie). Jeder neue Call wird dabei eine erneute Berechnung der Rewards anstoßen und ausliefern.

Parameter im Request-Body

Da die Bedeutung der meisten Properties über den Namen klar sein sollte, hier nur einige wenige Erklärungen zu den erklärungsbedürftigen Properties.

Name	Beschreibung
`Timestamp`	DateTime : required - hier sollte der Zeitpunkt der Rechnungsstellung im ISO8601-Format inkl. Zeitzone angegeben werden. Beispiel: 2015-04-30T08:45:15+02:00 für 08:45:15 Uhr am 30. April 2015 in Berlin (MESZ – Sommerzeit)
`HasDiscounts`	bool : required - wird hier true angegeben, findet für diesen basket keine Reward-Berechnung im menio-System statt
`CurrencyISO`	string : optional - Geben Sie die Währung, in der abgerechnet wird, als 3-stellige Abkürzung nach ISO 4217
`WaiterName`	string : optional - hier sollte der Name des Bedieners/Kassierers stehen, der den Kunden maßgeblich bedient/beraten hat
`BillPdf`	Byte-Array : optional - Um das Features des Digitalen Bons auch den Konsumenten ohne Smartphone anbieten zu können, kann Ihre Software die Kopie der Rechnung als eine PDF-Datei an uns schicken, damit wir diese einerseits im menio Consumer Portal anzeigen, aber auch direkt per Email an den Konsumenten verschicken können. Schicken Sie hier dazu den Inhalt der PDF-Datei als base64-kodierter Byte-Array
`RegularGrossPrice`	double : optional - hier sollte der normale Verkaufspreis für den Artikel angegeben werden
`CurrentGrossPrice`	double : optional - hier sollte der Preis stehen, unter welchem dieser Artikel in dieser Rechnung verkauft wird, z.B. wenn irgendwelche Discounts (Aktionen, Mitarbeiterrabatte etc.) auf diesen Artikel angewendet wurden.
`ProductId`	string : optional - geben Sie hier die PLU des Produkts, unter welcher das Produkt an unser System eingereicht wurde, damit wir dieses korrekt für die Berechnung der produktbasierten Rewards erkennen können. Haben Sie in Ihrer Software keine Unterstützung für produktbasierte Rewards implementiert, können Sie dieses Feld auslassen
`OrderTime`	DateTime : optional - in der Gastronomie ist häufig anzutreffen, dass eine Rechnung längere Zeit offen steht und Positionen nach und nach gebucht werden. Ist dies bei Ihnen auch der Fall, geben Sie hier den genauen Buchungszeitpunkt der jeweiligen Position im ISO8601-Format (inkl. Zeitzone) an. Dies wird uns erlauben, sog. “Happy Hour”-Rewards auf eine Position genau berechnen zu können. Beispiel: 2015-04-30T08:45:15+02:00 für 08:45:15 Uhr am 30. April 2015 in Berlin (MESZ – Sommerzeit)
`ProductProps`	dictionary[string, string] : optional - Haben Ihre Produkte besondere Eigenschaften, die auf dem Digitalen Kassenbon strukturiert angezeigt werden sollen, so ist diese Liste der Key-Value-Pairs genau der richtige Ort für diese Eigenschaften

Response

Der Response-Body enthält eine Liste der auf den eingereichten basket anwendbaren Rewards sowie ggf. Guthaben auf einer Kunden- bzw. Geschenkkarte, sofern deren IDs als URL-Parameter beim Call angegeben wurden. Die Rewards-Liste wird leer sein, wenn kein Reward anwendbar ist. Anderenfalls ist es eine Liste mit Objekten, die jeweils einen Reward pro einzelnen Artikel darstellen oder sich auf den Gesamt-Rechnungsbetrag beziehen. Jedes Objekt hat dabei folgende Properties:

Name	Beschreibung
`RewardType`	int: 1 = Reward auf Produkt. 2 = Reward auf Gesamt-Rechnungsbetrag. Bei 1 wird die `ProductId` mit der PLU des Produktes belegt, für welchen dieser Reward ermittelt wurde. Bei 2 bleibt das Feld `ProductId` leer.
`ProductId`	string: die PLU des im basket-Datensatz übermittelten Artikels, auf welchen ein Reward ermittelt werden konnte.
`NetRewardValue`	decimal: das ist der errechnete Netto-Wert (ohne MwSt) des Rewards. Bitte beachten Sie, dass dieser Betrag bei `RewardType`=2 in Ihrer Software auf die einzelnen Positionen umgelegt werden sollte, wenn in Ihrer Software eine Direktverrechnung der Rewards mit dem Rechnungsbetrag erfolgt.
`ApplicableTaxInPercent`	decimal: dies ist der Mehrwertsteuersatz als Dezimalzahl (z.B. 19.0) für den Reward. Er bleibt leer, wenn `RewardType`=2, da der Reward sich auf den Gesamt-Rechnungsbetrag mit u.U. unterschiedlichen MwSt-Anteilen bezieht. Bei `RewardType`=1 wird er hingegen aus dem Feld `VatInPercent` der Rechnungsposition des ursprünglichen basket-Datensatzes abgeleitet, für welche der Reward ermittelt wurde.

Und hier die Erklärung der Properties eines Balance-Objekts:

Name	Beschreibung
`TokenId`	string: das ist die `giftCardId` bzw. der `consumerIdentToken` des Kunden-Profils, wie im Request angegeben
`Balance`	decimal: das ist die Höhe des Guthabens auf der Karte
`Currency`	string: die Währung, in der das Guthaben vorliegt, als 3-stellige Abkürzung nach ISO 4217

Parameter

basketIdstringErforderlich

Ein frei von Ihrem Client erzeugbarer String, welcher den basket eindeutig identifiziert. Sie können hier z.B. die Rechnungsnummer als basketId verwenden.

Beispiel: 'ab12345'

token1string

Hat sich der Konsument bereits am POS z.B. durch Vorzeigen einer Kundenkarte identifiziert, in welcher der mit seinem Konsumenten-Profil verlinkte token gespeichert ist, sollte dieser token hier angegeben werden.

Beispiel: 'member123'

token2string

Hatte der Konsument beim Kauf eine Geschenkkarte vorgezeigt und wurde diese von Ihrem System erfasst, sollte hier die in der Karte gespeicherte ID angegeben werden

Beispiel: 'giftCardABC'

Request-Header

Content-Type

application/json

DevKey

{Ihr Key}

TrackingUnitId

{trackingUnitId}

Originaler Blueprint-Ausschnitt

API Blueprint

### POST baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2} [POST]
Ein basket ist der Inhalt einer Rechnung und stellt die Grundlage für die meisten Qnips-Funktionen dar. 
Das Ergebnis dieses Calls beinhaltet immer die möglichen `Rewards`, für die im basket enthaltenen Produkte. 
Diese errechneten `Rewards` stellen ein vorläufiges Ergebnis fest und müssen von Ihrer Software als `granted` markiert werden, 
sobald der Rechnungsbetrag voll beglichen ist, damit die Rewards wirksam werden und dem consumer als eingelöst gemeldet 
werden können (siehe *[POST baskets/{basketId}/grant](#reference/baskets/rewards-als-granted-markieren/post-baskets%2F%7Bbasketid%7D%2Fgrant%3Fredeemedinpos%3D%7Bredeemedinpos%7D)*)

Wurden beim Call ein *consumerIdentToken* oder eine *giftCardId* angegeben, so kann der Response auch die Information über 
potentiell vorhandene Guthaben entweder auf dem Konsumenten-Profil oder auf der  Geschenk-Karte enthalten.

Solange ein basket nicht `granted` ist, kann er über den erneuten Call auf diese Resource beliebig oft geupdated werden, 
z.B. weil kurzerhand noch eine Position nachgebucht oder gestrichen wurde (ein häufiger Fall in der Gastronomie). 
Jeder neue Call wird dabei eine erneute Berechnung der Rewards anstoßen und ausliefern. 

#### Parameter im Request-Body
Da die Bedeutung der meisten Properties über den Namen klar sein sollte, hier nur einige wenige Erklärungen zu den erklärungsbedürftigen Properties.

| Name | Beschreibung |
| ---    | --- |
|`Timestamp`|**DateTime : required** - hier sollte der Zeitpunkt der Rechnungsstellung im *[ISO8601-Format](http://de.wikipedia.org/wiki/ISO_8601)* inkl. Zeitzone angegeben werden. Beispiel: 2015-04-30T08:45:15+02:00 für 08:45:15 Uhr am 30. April 2015 in Berlin (MESZ – Sommerzeit)|
|`HasDiscounts`|**bool : required** - wird hier true angegeben, findet für diesen basket keine Reward-Berechnung im Qnips-System statt|
|`CurrencyISO`|**string : optional** - Geben Sie die Währung, in der abgerechnet wird, als 3-stellige Abkürzung nach *[ISO 4217](http://de.wikipedia.org/wiki/ISO_4217)*|
|`WaiterName`|**string : optional** - hier sollte der Name des Bedieners/Kassierers stehen, der den Kunden maßgeblich bedient/beraten hat|
|`BillPdf`|**Byte-Array : optional** - Um das Features des Digitalen Bons auch den Konsumenten ohne Smartphone anbieten zu können, kann Ihre Software die Kopie der Rechnung als eine PDF-Datei an uns schicken, damit wir diese einerseits im Qnips Consumer Portal anzeigen, aber auch direkt per Email an den Konsumenten verschicken können. Schicken Sie hier dazu den Inhalt der PDF-Datei als base64-kodierter Byte-Array|
|`RegularGrossPrice`|**double : optional** - hier sollte der normale Verkaufspreis für den Artikel angegeben werden|
|`CurrentGrossPrice`|**double : optional** - hier sollte der Preis stehen, unter welchem dieser Artikel in dieser Rechnung verkauft wird, z.B. wenn irgendwelche Discounts (Aktionen, Mitarbeiterrabatte etc.) auf diesen Artikel angewendet wurden.|
|`ProductId`|**string : optional** - geben Sie hier die PLU des Produkts, unter welcher das Produkt an unser System eingereicht wurde, damit wir dieses korrekt für die Berechnung der produktbasierten Rewards erkennen können. Haben Sie in Ihrer Software keine Unterstützung für produktbasierte Rewards implementiert, können Sie dieses Feld auslassen|
|`OrderTime`|**DateTime : optional** - in der Gastronomie ist häufig anzutreffen, dass eine Rechnung längere Zeit offen steht und Positionen nach und nach gebucht werden. Ist dies bei Ihnen auch der Fall, geben Sie hier den genauen Buchungszeitpunkt der jeweiligen Position im *[ISO8601-Format](http://de.wikipedia.org/wiki/ISO_8601)* (inkl. Zeitzone) an. Dies wird uns erlauben, sog. “Happy Hour”-Rewards auf eine Position genau berechnen zu können. Beispiel: 2015-04-30T08:45:15+02:00 für 08:45:15 Uhr am 30. April 2015 in Berlin (MESZ – Sommerzeit)|
|`ProductProps`|**dictionary[string, string] : optional** - Haben Ihre Produkte besondere Eigenschaften, die auf dem Digitalen Kassenbon strukturiert angezeigt werden sollen, so ist diese Liste der Key-Value-Pairs genau der richtige Ort für diese Eigenschaften|

#### Response
Der Response-Body enthält eine Liste der auf den eingereichten basket anwendbaren Rewards sowie ggf. Guthaben auf einer Kunden- bzw. Geschenkkarte, sofern deren IDs als URL-Parameter beim Call angegeben wurden. Die Rewards-Liste wird leer sein, 
wenn kein Reward anwendbar ist. Anderenfalls ist es eine Liste mit Objekten, die jeweils einen Reward pro einzelnen Artikel darstellen oder sich auf den Gesamt-Rechnungsbetrag beziehen. 
Jedes Objekt hat dabei folgende Properties:

| Name | Beschreibung |
| ---    | --- |
|`RewardType`|**int**: 1 = Reward auf Produkt. 2 = Reward auf Gesamt-Rechnungsbetrag. Bei 1 wird die `ProductId` mit der PLU des Produktes belegt, für welchen dieser Reward ermittelt wurde. Bei 2 bleibt das Feld `ProductId` leer.|
|`ProductId`|**string**: die PLU des im basket-Datensatz übermittelten Artikels, auf welchen ein Reward ermittelt werden konnte.|
|`NetRewardValue`|**decimal**: das ist der errechnete Netto-Wert (ohne MwSt) des Rewards. Bitte beachten Sie, dass dieser Betrag bei `RewardType`=2 in Ihrer Software auf die einzelnen Positionen umgelegt werden sollte, wenn in Ihrer Software eine Direktverrechnung der Rewards mit dem Rechnungsbetrag erfolgt. |
|`ApplicableTaxInPercent`|**decimal**: dies ist der Mehrwertsteuersatz als Dezimalzahl (z.B. 19.0) für den Reward. Er bleibt leer, wenn `RewardType`=2, da der Reward sich auf den Gesamt-Rechnungsbetrag mit u.U. unterschiedlichen MwSt-Anteilen bezieht. Bei `RewardType`=1 wird er hingegen aus dem Feld `VatInPercent` der Rechnungsposition des ursprünglichen basket-Datensatzes abgeleitet, für welche der Reward ermittelt wurde.|

Und hier die Erklärung der Properties eines Balance-Objekts:

| Name | Beschreibung |
| ---    | --- |
|`TokenId`|**string**: das ist die `giftCardId` bzw. der `consumerIdentToken` des Kunden-Profils, wie im Request angegeben|
|`Balance`|**decimal**: das ist die Höhe des Guthabens auf der Karte|
|`Currency`|**string**: die Währung, in der das Guthaben vorliegt, als 3-stellige Abkürzung nach *[ISO 4217](http://de.wikipedia.org/wiki/ISO_4217)*|

+ Parameters
    + basketId (string, `'ab12345'`) ... Ein frei von Ihrem Client erzeugbarer String, welcher den basket eindeutig identifiziert. Sie können hier z.B. die Rechnungsnummer als `basketId` verwenden.
    + token1 (optional, string, `'member123'`) ... Hat sich der Konsument bereits am POS z.B. durch Vorzeigen einer Kundenkarte identifiziert, in welcher der mit seinem Konsumenten-Profil verlinkte `token` gespeichert ist, sollte dieser `token` hier angegeben werden.
    + token2 (optional, string, `'giftCardABC'`) ... Hatte der Konsument beim Kauf eine Geschenkkarte vorgezeigt und wurde diese von Ihrem System erfasst, sollte hier die in der Karte gespeicherte ID angegeben werden

+ Request

    + Headers

            Content-Type: application/json
            DevKey: {Ihr Key}
            TrackingUnitId: {trackingUnitId}

    + Body

            {
               "BillNumber":"1234",
               "Timestamp":"2015-04-21T08:15:45.000+02:00",
               "TotalValue":159.90,
               "HasDiscounts":false,
               "TableId":"123",
               "WaiterName":"Max Mustermann",
               "CurrencyISO":"EUR",
               "Positions":[
                  {
                    "ProductId":"123",
                    "ProductName":"Adidas Sneaker 123",
                    "Amount":2,
                    "HasDiscounts":false,
                    "CurrentGrossPrice":79.95,
                    "RegularGrossPrice":79.95,
                    "VatInPercent":19.0,
                    "OrderTime":"2015-04-21T08:15:45.000+02:00",
                    "ImageUrl":"http://abc.de/xyz",
                    "ProductProps":{
                        "Größe":"43",
                        "Farbe":"black"
                    }
                  }
               ],   
               "BillPdf":"98761238467129803470987809123489798172435980728347578091873645786..."
            }

+ Response 200

    + Headers

            Content-Type: application/json

    + Body

            {
                "Rewards":[
                {
                    "RewardType":1,
                    "ProductId":"123",
                    "NetRewardValue":10.50,
                    "ApplicableTaxInPercent":19.0
                },
                {
                    "RewardType":2,
                    "ProductId":null,
                    "NetRewardValue":10.50,
                    "ApplicableTaxInPercent":null
                }],
                "Balances":[
                    {
                        "TokenId":"member123",
                        "Balance":50.0,
                        "CurrencyISO":"EUR"
                    },
                    {
                        "TokenId":"giftCardABC",
                        "Balance":25.0,
                        "CurrencyISO":"EUR"
                    }]
            }
            
+ Response 500

        // HTTP-InternalServerError: Ein unbekannten Problem bei der Verarbeitung aufgetreten

+ Response 401 

        // HTTP-Unauthorized: DevKey oder trackingUnitId nicht angegeben oder nicht vorhanden

+ Response 403 

        // HTTP-Forbidden: trackingUnitId ist noch nicht vom Merchant aktiviert
            
+ Response 400

        {
            "ErrorId":123,
            "ErrorText":"Details zum Fehler"
        }
        
        // hier alle möglichen ErrorCodes inkl. Texte für diese Resource
        // 1000: Body enthält syntaktische Fehler und kann nicht deserialisiert werden            
        // 11004: consumerIdentToken nicht gefunden. Wiederholen Sie ggf. ohne diesen Token
        // 11005: consumerIdentToken gesperrt. Wiederholen Sie ggf. ohne diesen Token
        // 11006: consumerIdentToken abgelaufen. Wiederholen Sie ggf. ohne diesen Token
        // 11007: giftCardId nicht gefunden. Wiederholen Sie ggf. ohne diesen Token
        // 11008: giftCardId gesperrt. Wiederholen Sie ggf. ohne diesen Token
        // 11009: giftCardId abgelaufen. Wiederholen Sie ggf. ohne diesen Token 
        // 11010: dieser basket ist `granted` und somit nicht mehr veränderbar

Request

cURL

curl --request POST \
  'http://pos.dev.qnips.com/api/pos/v3/baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2}' \
  --header 'Content-Type: application/json' \
  --header 'DevKey: {YOUR_DEV_KEY}' \
  --header 'TrackingUnitId: {trackingUnitId}' \
  --data-raw '{
   "BillNumber":"1234",
   "Timestamp":"2015-04-21T08:15:45.000+02:00",
   "TotalValue":159.90,
   "HasDiscounts":false,
   "TableId":"123",
   "WaiterName":"Max Mustermann",
   "CurrencyISO":"EUR",
   "Positions":[
      {
        "ProductId":"123",
        "ProductName":"Adidas Sneaker 123",
        "Amount":2,
        "HasDiscounts":false,
        "CurrentGrossPrice":79.95,
        "RegularGrossPrice":79.95,
        "VatInPercent":19.0,
        "OrderTime":"2015-04-21T08:15:45.000+02:00",
        "ImageUrl":"http://abc.de/xyz",
        "ProductProps":{
            "Größe":"43",
            "Farbe":"black"
        }
      }
   ],   
   "BillPdf":"98761238467129803470987809123489798172435980728347578091873645786..."
}
'

Dokumentationsbeispiel. Platzhalter vor der Verwendung ersetzen.

Response

Response-Header

Content-Type: application/json

Response 200

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

Response 500

// HTTP-InternalServerError: Ein unbekannten Problem bei der Verarbeitung aufgetreten

Response 401

// HTTP-Unauthorized: DevKey oder trackingUnitId nicht angegeben oder nicht vorhanden

Response 403

// HTTP-Forbidden: trackingUnitId ist noch nicht vom Merchant aktiviert

Response 400

{
    "ErrorId":123,
    "ErrorText":"Details zum Fehler"
}

// hier alle möglichen ErrorCodes inkl. Texte für diese Resource
// 1000: Body enthält syntaktische Fehler und kann nicht deserialisiert werden            
// 11004: consumerIdentToken nicht gefunden. Wiederholen Sie ggf. ohne diesen Token
// 11005: consumerIdentToken gesperrt. Wiederholen Sie ggf. ohne diesen Token
// 11006: consumerIdentToken abgelaufen. Wiederholen Sie ggf. ohne diesen Token
// 11007: giftCardId nicht gefunden. Wiederholen Sie ggf. ohne diesen Token
// 11008: giftCardId gesperrt. Wiederholen Sie ggf. ohne diesen Token
// 11009: giftCardId abgelaufen. Wiederholen Sie ggf. ohne diesen Token 
// 11010: dieser basket ist `granted` und somit nicht mehr veränderbar