Stempel-Validierungs-API

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.

GET

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


GET /api/stamp/v1/validate
     ?stampIdx=274

Request Parameters

stampIdx integer required
Stempel-IDX. 
{
    "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",
        "onsitePwd": "123456",
        "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",
        "payloadVersion": "v1"
    }
}

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.
stampIdx integer
Stempel-IDX.
domain string
Stempel-Domain.
cardIdx integer
Karten-IDX.
cardNm string
Kartenname.
cardTtl string
Kartentitel.
stamps integer
Anzahl der bisher gesammelten Stempel.
maxStamps integer
Maximale Anzahl der Stempel auf der Karte.
stampUrl string
URL der Stempelseite.
url string
URL, zu der weitergeleitet wird, wenn auf der Stempelseite die Schaltfläche angeklickt wird.
strtYmd date
Beginn des Gültigkeitszeitraums des Stempels.
endYmd date
Ablaufdatum des Stempels.
onsiteYn string
Enum:
YN
Gibt an, ob die Vor-Ort-Sammelfunktion aktiviert ist.
Wenn der Wert Y ist, kann das Personal Stempel direkt im Geschäft hinzufügen.
onsitePwd string
Passwort für die Vor-Ort-Stempelfunktion.
Erforderlich bei der Verwendung der Stempel-Belohnungs-API, wenn die Vor-Ort-Option aktiviert ist (Y).
memo string
Interne Notiz zu Referenzzwecken.
activeYn string
Enum:
YN
Gibt an, ob der Stempel aktiv ist.
Wenn er deaktiviert ist, kann der Kunde den Stempel nicht verwenden.
userId string
Benutzer-ID. Wird verwendet, um den Empfänger des Stempels zu verwalten.
Normalerweise entspricht dies der Anmelde-ID des Website-Mitglieds.
Wenn kein Wert gesetzt ist, wird die Benutzer-ID automatisch vom System generiert.
userNm string
Benutzername. Nur für die interne Verwaltung.
userPhnno string
Telefonnummer des Benutzers. Nur für die interne Verwaltung.
userEml string
E-Mail-Adresse des Benutzers. Nur für die interne Verwaltung.
userEtc1 string
Zusätzliches internes Verwaltungsfeld.
userEtc2 string
Zusätzliches internes Verwaltungsfeld.
stampImgUrl string
Bild-URL des Stempels.
regYmdt datetime
Erstellungsdatum des Stempels. Beispiel: 2025-07-21 11:50:20

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