POST tokens/{id}/info · Web API v3 · Deutsch

API-ReferenzWeb API v3 · Deutschtokens

POST tokens/{id}/info

Web API v3 · Deutsch v3tokens

Aktualität laut Confluence unklar. Die englische POS API v3 ist die aktuelle Referenz.

GET/tokens/{id}/info

Hiermit kann abgefraget werden, ob am Token z.B. schon Guthaben aufgeladen ist, welche Aufladelimits für den Token ggf. existieren, ob eine PIN-Abfrage erforderlich ist, wieviele Treuepunkte der User dieses Tokens ggf. schon hat und vieles mehr. Diese Info kann für die visuelle Anzeige für den Kassierer relevant sein. Bitte bilden Sie zur {id} eine Checksumme (siehe Security-Token) und geben Sie diese im SecurityToken-Header an.

Parameter

idstringErforderlich

Geben Sie hier den von einem Trägermedium ausgelesenen Token an. Ist der Token länger als 50 bytes, sollte dieser anstatt über die URL, über den Token-Requestheader übermittelt werden.

Beispiel: 'cardId123'

Request-Header

DevKey

{Ihr Key}

TrackingUnitId

{trackingUnitId}

SecurityToken

{checksumme über {id}}

Token

optional {der von einem Trägermedium ausgelesene Token als Kunden-Identifier}

Kontext: tokens

Tokens sind beliebig geartete, jedoch stets voneinander unterschiedliche, nicht wiederholbare Strings, welche sowohl zur Identifikation eines Konsumenten ( consumer ) als auch zur Identifikation eines Guthabens ( balance ) verwendet werden können. In der Regel werden diese Tokens auf einem beliebigen Trägermedium gespeichert und an einen Konsumenten in Form einer Kundenkarte oder Geschenkkarte ausgehändigt. Der Konsument wird bei seinen nächsten Käufen dieses Trägermedium am POS vorzeigen müssen, um auf das darin gespeicherte Guthaben zugreifen zu können bzw. die menio-Rewards angerechnet zu bekommen.

Originaler Blueprint-Ausschnitt

API BlueprintKopieren

### POST tokens/{id}/info [GET]
Hiermit kann abgefraget werden, ob am Token z.B. schon Guthaben aufgeladen ist, welche Aufladelimits für den Token
ggf. existieren, ob eine PIN-Abfrage erforderlich ist, wieviele Treuepunkte der User dieses Tokens ggf. schon hat und vieles mehr. Diese Info kann für 
die visuelle Anzeige für den Kassierer relevant sein.
*Bitte bilden Sie zur* **{id}** *eine Checksumme (siehe [Security-Token](#introduction/grundlegendes/secutiry-token)) und geben Sie diese im `SecurityToken`-Header an.*

+ Parameters
    + id (string, `'cardId123'`) ... Geben Sie hier den von einem Trägermedium ausgelesenen Token an. Ist der Token länger als 50 bytes, sollte dieser anstatt über die URL, über den Token-Requestheader übermittelt werden.

+ Request

    + Headers

            DevKey: {Ihr Key}
            TrackingUnitId: {trackingUnitId}
            SecurityToken: {checksumme über {id}}
            Token: optional {der von einem Trägermedium ausgelesene Token als Kunden-Identifier}

+ Response 200
        
        {
            "TokenType": "consumerIdentifier",
            "Balance": 25.99,
            "MaxBalance": 99999.0,
            "RemainingBalanceToAdd": 99974.01,
            "IsWithdrawBalanceAllowed": false,
            "IsAddBalanceAllowed": true,
            "RelatedGiftCards": [],
            "IdentAliases": [
                {
                    "IdentString": "6088514929546754",
                    "Source": 4
                }
            ],
            "IdentString": "6088514929546754",
            "ExternalIdentString": "12398730984",
            "ExternalIdentStringSource": "Company",
            "ExternalCardNumber": "12356473",
            "RequiresPin": false,
            "InfoUrl": "http://pos.dev.qnips.com/TokenInfo?token=4BZC2R1iAqmappIzAMbOkQ0LZCm0b%2fmc0v7nhSITEV7snTxI%2f%2bELsNd6n1Z2fyXtMp%2fuwlg%2fgU%2be9r7bIQwSiA%3d%3d",
            "ConsumerIdentityInfo": {
                "LoyaltySchemeProgressInfos": [
                    {
                        CurrentPoints = 2,
                        MaxPoints = 10,
                        LoyaltySchemeId = 123,
                        LoyaltySchemeName = "Jedes 10. Kaffeegetränk gratis"
                    }
                ],
                "QrCodeContent": "",
                "Allowances": [
                    {
                        "Id": 180,
                        "Name": "Allowances Daily",
                        "ThirdPartyId": "AD123",
                        "RemainingValue": 2.0,
                        "Type": 1
                    }
                ]
            },
            "TagInfos":  [
                {
                    "ThirdPartyId": "DrittanbieterId",
                    "Name": "Benutzergruppe"
                }
            ]
        }

+ 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":13000,
            "ErrorText":"Details zum Fehler"
        }
        
        // hier alle möglichen ErrorCodes inkl. Texte für diese Ressource
        // 13001: token unbekannt

Request

cURLKopieren

curl --request GET \
  'http://pos.prelive.qnips.com/api/pos/v3/tokens/{id}/info' \
  --header 'DevKey: {YOUR_DEV_KEY}' \
  --header 'TrackingUnitId: {trackingUnitId}' \
  --header 'SecurityToken: {checksumme über {id}}' \
  --header 'Token: optional {der von einem Trägermedium ausgelesene Token als Kunden-Identifier}'

Dokumentationsbeispiel. Platzhalter vor der Verwendung ersetzen.

Response

200500403401400

Response 200Kopieren

{
    "TokenType": "consumerIdentifier",
    "Balance": 25.99,
    "MaxBalance": 99999.0,
    "RemainingBalanceToAdd": 99974.01,
    "IsWithdrawBalanceAllowed": false,
    "IsAddBalanceAllowed": true,
    "RelatedGiftCards": [],
    "IdentAliases": [
        {
            "IdentString": "6088514929546754",
            "Source": 4
        }
    ],
    "IdentString": "6088514929546754",
    "ExternalIdentString": "12398730984",
    "ExternalIdentStringSource": "Company",
    "ExternalCardNumber": "12356473",
    "RequiresPin": false,
    "InfoUrl": "http://pos.dev.qnips.com/TokenInfo?token=4BZC2R1iAqmappIzAMbOkQ0LZCm0b%2fmc0v7nhSITEV7snTxI%2f%2bELsNd6n1Z2fyXtMp%2fuwlg%2fgU%2be9r7bIQwSiA%3d%3d",
    "ConsumerIdentityInfo": {
        "LoyaltySchemeProgressInfos": [
            {
                CurrentPoints = 2,
                MaxPoints = 10,
                LoyaltySchemeId = 123,
                LoyaltySchemeName = "Jedes 10. Kaffeegetränk gratis"
            }
        ],
        "QrCodeContent": "",
        "Allowances": [
            {
                "Id": 180,
                "Name": "Allowances Daily",
                "ThirdPartyId": "AD123",
                "RemainingValue": 2.0,
                "Type": 1
            }
        ]
    },
    "TagInfos":  [
        {
            "ThirdPartyId": "DrittanbieterId",
            "Name": "Benutzergruppe"
        }
    ]
}

Response 500Kopieren

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

Response 403Kopieren

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

Response 401Kopieren

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

Response 400Kopieren

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

// hier alle möglichen ErrorCodes inkl. Texte für diese Ressource
// 13001: token unbekannt