Zum Inhalt springen
meniodeveloper
menio DashboardVorschau

GET tokens/info/{tokenId} · Web API · Addendum

API-ReferenzWeb API · Addendumtokens

GET tokens/info/{tokenId}

Web API · Addendum tokens
Geltungsbereich und Versionszuordnung laut Confluence unklar.
GET/tokens/info/{tokenId}

Hiermit können verschiedene Informationen zu einem Token abgefragt werden.

Bitte bilden Sie zur {tokenId} eine Checksumme (siehe Security-Token aus dem Original Dokument) und geben Sie diese im SecurityToken-Header an.

Feld Beschreibung
IdentString string - Dieser String enthält einen eindeutigen Bezeichner für den Token und kann in einer verkürzten Form auf der Kasse angezeigt werden. (Verkürzt bedeutet hier, dass nur die letzten 3 oder 4 Zeichen erkennbar sind: 1234567890 wird zu ******7890)
TokenType string - Entweder consumerIdentifier oder giftCard Zu einem basket kann nur einziger consumerIdentifier eingereicht werden. Der Parameter giftCard entfällt. Zusätzliche GiftCards des Kunden können über balanceWithdraw als Zahlungsmittel genutzt werden.
Balance decimal - Das momentan auf diesem Token hinterlegte Guthaben
MaxBalance decimal - Der Maximalbetrag an Guthaben, den dieser Token tragen darf
RemainingBalanceToAdd decimal - Der Maximalbetrag an Guthaben, der im aktuellen Kalendermonat noch auf diesem Token hinterlegt werden kann.
IsWithdrawBalanceAllowed boolean - Gibt an, ob Bezahlungen aus dem Guthaben heraus für diesen Token erlaubt ist
IsAddBalanceAllowed boolean - Gibt an, ob Guthaben-Aufladungen für diesen Token erlaubt ist
RelatedGiftCards Array von verknüpften Geschenkkarten - Nur bei consumerIdentifier möglich. Jedes Element aus dem Array enthält eine GiftCardId und die aktuelle Balance
RequiresPin boolean - Für die nächste Nutzung der Guthabenkarte ist eine PIN-Erfassung erforderlich. Dieser Wert kann sich nach jeder Nutzung abändern, weswegen dieser Wert nicht gecached werden sollte.
InfoUrl string, optional - Eine URL, die die Kasse aufruft, um auf dem Kassendisplay weitere Infos anzuzeigen
ConsumerIdentityInfo Objekt wie weiter unten spezifiziert - Handelt es sich bei dem Token um einen Token mit TokenType = consumerIdentifier, so wird hier ein Objekt mit weiteren Informationen, wie Tags oder Infos zu seinen Treuepunkteständen ausgegeben.

ConsumerIdentityInfo-Objekt

Feld Beschreibung
Tags Array von zuordneten Tags - Dieses System kann zum Beispiel für Preisebenen, Status, etc. verwendet werden. Jedes Element aus dem Array enthält Name und eine Liste von Groups, in denen der jeweilige Tag enthalten ist.
LoyaltySchemeProgressInfos Array von LoyaltySchemeProgressInfo-Objekten - Info über eventuell berets gesammelte Treuepunkte des Konsumenten.

LoyaltySchemeProgressInfo-Objekt

Feld Beschreibung
LoyaltySchemeId integer - Dies ist die menio-interne ID des Treuepunte-Programms.
LoyaltySchemeName string - Dies ist der Name des Treuepunte-Programms, wie er auch in den Apps gezeigt wird.
MaxPoints integer - Gibt an, wieviele Punkte in diesem Programm gesammelt werden müssen, damit ein Rabatt ausgegeben wird.
CurrentPoints integer - Gibt an, wieviele Punkte der Konsument in diesem Treuepunkte-Programm bereits gesammelt hat.

Parameter

tokenIdstringErforderlich

Geben Sie hier den von einem Trägermedium ausgelesenen Token an. Als Alternative kann der ausgelesene Token als HTTP Header Token übertragen werden.

Beispiel: cardId123

Request-Header

DevKey
{Ihr Key}
TrackingUnitId
{trackingUnitId}
Token
{tokenId}
SecurityToken
{Checksumme über {tokenId}}
Originaler Blueprint-Ausschnitt
API Blueprint
### GET tokens/info/{tokenId} [GET]

Hiermit können verschiedene Informationen zu einem Token abgefragt werden.

*Bitte bilden Sie zur* **{tokenId}** *eine Checksumme (siehe Security-Token aus dem Original Dokument) und geben Sie diese im `SecurityToken`-Header an.*

| Feld | Beschreibung |
| --- | --- |
| `IdentString` | **string** - Dieser String enthält einen eindeutigen Bezeichner für den Token und kann in einer verkürzten Form auf der Kasse angezeigt werden. (Verkürzt bedeutet hier, dass nur die letzten 3 oder 4 Zeichen erkennbar sind: `1234567890` wird zu `******7890`)
| `TokenType` | **string** - Entweder **consumerIdentifier** oder **giftCard** Zu einem basket kann nur einziger consumerIdentifier eingereicht werden. Der Parameter giftCard entfällt. Zusätzliche GiftCards des Kunden können über balanceWithdraw als Zahlungsmittel genutzt werden.|
| `Balance` | **decimal** - Das momentan auf diesem Token hinterlegte Guthaben |
| `MaxBalance` | **decimal** - Der Maximalbetrag an Guthaben, den dieser Token tragen darf  |
| `RemainingBalanceToAdd` | **decimal** - Der Maximalbetrag an Guthaben, der im aktuellen Kalendermonat noch auf diesem Token hinterlegt werden kann. |
| `IsWithdrawBalanceAllowed` | **boolean** - Gibt an, ob Bezahlungen aus dem Guthaben heraus für diesen Token erlaubt ist |
| `IsAddBalanceAllowed` | **boolean** - Gibt an, ob Guthaben-Aufladungen für diesen Token erlaubt ist |
| `RelatedGiftCards` | **Array von verknüpften Geschenkkarten** - Nur bei **consumerIdentifier** möglich. Jedes Element aus dem Array enthält eine **GiftCardId** und die aktuelle **Balance** |
| `RequiresPin` | **boolean** - Für die nächste Nutzung der Guthabenkarte ist eine PIN-Erfassung erforderlich. Dieser Wert kann sich nach jeder Nutzung abändern, weswegen dieser Wert nicht gecached werden sollte. |
| `InfoUrl` | **string, optional** - Eine URL, die die Kasse aufruft, um auf dem Kassendisplay weitere Infos anzuzeigen |
| `ConsumerIdentityInfo` | **Objekt wie weiter unten spezifiziert** - Handelt es sich bei dem Token um einen Token mit `TokenType` = **consumerIdentifier**, so wird hier ein Objekt mit weiteren Informationen, wie Tags oder Infos zu seinen Treuepunkteständen ausgegeben. |

### ConsumerIdentityInfo-Objekt

| Feld | Beschreibung |
| --- | --- |
| `Tags` | **Array von zuordneten Tags** - Dieses System kann zum Beispiel für Preisebenen, Status, etc. verwendet werden. Jedes Element aus dem Array enthält **Name** und eine Liste von **Groups**, in denen der jeweilige Tag enthalten ist. |
| `LoyaltySchemeProgressInfos` | **Array von LoyaltySchemeProgressInfo-Objekten** - Info über eventuell berets gesammelte Treuepunkte des Konsumenten. |

### LoyaltySchemeProgressInfo-Objekt

| Feld | Beschreibung |
| --- | --- |
| `LoyaltySchemeId` | **integer** - Dies ist die Qnips-interne ID des Treuepunte-Programms. |
| `LoyaltySchemeName` | **string** - Dies ist der Name des Treuepunte-Programms, wie er auch in den Apps gezeigt wird. |
| `MaxPoints` | **integer** - Gibt an, wieviele Punkte in diesem Programm gesammelt werden müssen, damit ein Rabatt ausgegeben wird. |
| `CurrentPoints` | **integer** - Gibt an, wieviele Punkte der Konsument in diesem Treuepunkte-Programm bereits gesammelt hat. |

+ Parameters

    + tokenId (string, `cardId123`) ... Geben Sie hier den von einem Trägermedium ausgelesenen Token an. Als Alternative kann der ausgelesene Token als HTTP Header *Token* übertragen werden.

+ Request

    + Header

            DevKey: {Ihr Key}
            TrackingUnitId: {trackingUnitId}
            Token: {tokenId}
            SecurityToken: {Checksumme über {tokenId}}

+ Response 200 (application/json)

    + Body

            {
                "IdentString": "1234567890",
                "TokenType": "consumerIdentifier", // oder "giftCard"
                "Balance": 10.58,
                "MaxBalance": 100.00,
                "RemainingBalanceToAdd": 5.08,
                "IsWithdrawBalanceAllowed": true,
                "IsAddBalanceAllowed":true,
                "RelatedGiftCards": [
                    {
                        "GiftCardId": "giftCard123",
                        "Balance": 20.04
                    }
                ],
                "RequiresPin": true,
                "InfoUrl": "http://...",
                "ConsumerIdentityInfo":{
                    "Tags": [
                        {
                            "Name": "Mitarbeiter",
                            "Groups": [
                                "priceLevel"
                            ]
                        }
                    ],
                    "LoyaltySchemeProgressInfos": [
                        {
                            "LoyaltySchemeId": 123,
                            "LoyaltySchemeName": "Jedes 10. Heißgetränk umsonst",
                            "MaxPoints": 10,
                            "CurrentPoints": 3
                        }
                    ]
                }
            }

+ Response 500

        // HTTP-InternalServerError: Ein unbekannten Problem bei der Verarbeitung aufgetreten
        {
            "ErrorMessage": "some explanation"
            "StackTrace": "text"
        }

+ Response 403 

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

+ Response 401 

        // HTTP-Unauthorized: DevKey, trackingUnitId oder SecurityToken nicht angegeben/falsch

+ Response 400

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