Stempel-Validierungs-API (v2)

Die Stempel-Validierungs-API prüft, ob ein Stempel vor dem Hinzufügen, Entfernen oder Einlösen in einem gültigen Zustand ist.

Sie überprüft in einer Anfrage die stampIdx, den Gültigkeitszeitraum, den Aktivstatus und ob die Belohnung bereits eingelöst wurde.

Zusätzlich werden der aktuelle Akkumulationsstatus und Karteninformationen zurückgegeben, sodass eine Benutzeransicht erstellt werden kann.

Diese API ist ab dem Personal-Tarif verfügbar.

API Version

GET

/api/stamp/v2/validate?stampIdx={stampIdx}

Request
Response


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

stampIdx integer required: Stempel-IDX.
processStoreIdx integer: IDX des Geschäfts, in dem diese Anfrage tatsächlich verarbeitet wird. Bei Angabe prüft der Server Organisationszugehörigkeit, Aktivstatus und Berechtigungen, bevor der Wert im Verarbeitungsverlauf gespeichert wird.
Die verarbeitende Filiale wird nicht aus der Anfrage übernommen, sondern vom Server aus diesem Geschäft abgeleitet. Sie unterscheidet sich vom ausgebenden Geschäft (storeIdx).

{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

Response Parameters

codeinteger: Antwortcode: 0 = Erfolgreich, jeder andere Wert = Fehler
messagestring: Antwortnachricht. Wenn der Antwortcode ungleich 0 ist, wird eine Fehlermeldung zurückgegeben.
resultobject: Wenn die Überprüfung erfolgreich ist, enthält die Antwort die Stempelinformationen.
Bei einem Fehler ist der Antwortwert null und die Fehlermeldung zeigt die Ursache an.

Token für die Vor-Ort-Verifizierung (onsiteToken)

Die Antwort der v2-Validate-API enthält das Vor-Ort-Passwort (onsitePwd) nicht im Klartext. Stattdessen wird ein onsiteToken zurückgegeben, das 180 Sekunden gültig ist.

Ziel ist es, die Offenlegung des Klartextpassworts zu minimieren, nicht die Authentifizierung zu verstärken. Die Validate-API prüft das Passwort selbst nicht, daher stellt das Token keinen zusätzlichen Authentifizierungsfaktor dar. Stattdessen begrenzen kurze Gültigkeit, einmalige Verwendung und Kontextbindung die Wiederverwendung des Tokens.

Element	Wert
Gültigkeit	180 Sekunden. Die Gültigkeitsdauer wird zusätzlich in `onsiteTokenExpiresIn` zurückgegeben.
Verwendungen	Einmal. Nach der Verwendung geben nur Wiederholungen mit demselben `Idempotency-Key` das ursprüngliche Ergebnis zurück.
Bindung	Organisation, Konto des API-Schlüssels, Ressource, Aktion und das bei der Validierung bestätigte verarbeitende Geschäft
Anwendungsfälle	Coupon-Einlösung, Einlösung einer Stempelprämie und Stempelaktualisierung mit `useYn = Y`

Für Ressourcen ohne Vor-Ort-Verifizierung (onsiteYn = N) wird kein Token ausgegeben. Die v1-Validate-API gibt onsitePwd weiterhin im Klartext zurück.

Prüfung numerischer Parameter

Erhält ein numerischer Parameter einen nicht numerischen Wert oder eine Zahl außerhalb des vom Server verarbeitbaren Bereichs, wird die Anfrage sofort mit 400 (Fehlercode 653) abgelehnt.

In diesem Fall ändern sich Stempeldaten und Sammelhistorie überhaupt nicht, und es entsteht weder ein Ereigniseintrag noch eine Webhook-Zustellung. Eine Fehlerantwort bedeutet, dass nichts gespeichert wurde.

Verarbeitendes Geschäft angeben

Parameter	Bedeutung	Beschreibung
`processStoreIdx`	Verarbeitendes Geschäft	Das Geschäft, in dem diese Anfrage tatsächlich verarbeitet wird. Optional. Bei Angabe prüft der Server Organisationszugehörigkeit, Aktivstatus und Berechtigungen, bevor der Wert im Verarbeitungsverlauf gespeichert wird.

Die verarbeitende Filiale wird nicht aus der Anfrage übernommen. Der Server leitet sie aus dem angegebenen Geschäft ab und speichert sie.

Bei Nutzungsbereich BRANCH wird nur verarbeitet, wenn die Filiale des geprüften Geschäfts der Nutzungsfiliale entspricht oder Sie sich mit dem Vor-Ort-Passwort dieser Filiale authentifizieren. Ohne beides wird abgelehnt.

Nicht verwendbare Parameter — branchIdx (ausgebende Filiale), storeIdx (ausgebendes Geschäft), useScope (Nutzungsbereich) und useBranchIdx (Nutzungsfiliale) sind bereits gespeicherte Ausgaberichtlinien und können über diese API nicht geändert werden. Bei Angabe wird mit 400 (Fehlercode 1227) abgelehnt.

Welche Rolle hat die Stempelvalidierung?

Die Stempel-Validierungs-API geht über eine einfache Prüfung hinaus.
Sie dient dazu, auf Basis des aktuellen Status die nächste Aktion zu bestimmen.

Prüfen, ob weitere Stempel vergeben werden können
Überprüfen, ob Belohnungsbedingungen erfüllt sind
Status der Kampagnenteilnahme feststellen
Fortschritt pro Nutzer abrufen

Kurz gesagt: die zentrale API zur Auswertung des Kampagnenfortschritts.

Was sich aus dem Ergebnis ableiten lässt

Die Antwort (result) enthält alle erforderlichen Daten zur Bewertung des Fortschritts.

Damit können Sie:

stamps mit maxStamps vergleichen
Ermitteln, ob weitere Vergaben möglich sind
Prüfen, ob Belohnungsbedingungen erfüllt sind
Status (activeYn) überprüfen
Nutzungskontext (onsiteYn) bewerten
Personalisierung auf Basis von Nutzerdaten umsetzen

Kern: „Validierungs-API = Status + Input für Entscheidungslogik“

Verwendung der Antwortdaten

Die Antwort der Validierungs-API wird direkt in der Anwendungslogik verwendet.

Beispiele:

Fortschritt anzeigen: Anzeige des aktuellen Status in der UI
Aktionen steuern: Aktivieren oder Deaktivieren von Funktionen
Belohnungen anzeigen: Anzeige bei Zielerreichung
Nutzerstatus verarbeiten: Logik basierend auf Fortschritt anwenden

Kurz gesagt: Diese API ist die zentrale Datenquelle zwischen UI und Geschäftslogik.

Unterschied zur Coupon-Validierungs-API

Beide APIs liefern Validierungsdaten, jedoch mit unterschiedlichem Fokus.

Die Coupon-Validierung liefert transaktionsbezogene Daten wie Rabattart, Wert und Nutzung.
Die Stempel-Validierung liefert Fortschrittsdaten wie stamps, maxStamps, Kartenname, Titel und Bild-URL.

Die Coupon-Validierung berechnet „wie viel Rabatt aktuell gilt“,
während die Stempel-Validierung zeigt „wie viel gesammelt wurde und was noch fehlt“.

Operative Bedeutung

Die Stempel-Validierungs-API bildet das Zentrum des Eventflusses.

Verhindert fehlerhafte Stempelvergaben
Blockiert Aktionen bei nicht erfüllten Bedingungen
Verbessert die Nutzererfahrung
Sichert die Stabilität der Eventlogik

Ohne Validierung können Dateninkonsistenzen und Fehler im Ablauf entstehen.

Wichtige Hinweise

Der Status kann sich zwischen Validierung und tatsächlicher Ausführung ändern
Die Ausführungs-API sollte direkt nach der Validierung aufgerufen werden
Eine reine clientseitige Validierung ist nicht ausreichend
Bei hoher Last sollten Aufrufe optimiert und Retry-Mechanismen implementiert werden