Stempel-Update-API

Die Stempel-Update-API ermöglicht die Aktualisierung bereits ausgestellter Stempel.

Neben einfachen Änderungen können Sie die Stempelanzahl anpassen, die Einlösung von Belohnungen verarbeiten und PINs zurücksetzen, wodurch Sie die Kontrolle über den Nutzerstatus behalten.

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

PUT

/api/stamp/v1/update 

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "resetPinYn": "Y",
    "userEml": "example@gmail.com"
}

Request Parameters

stampIdx integer required
Stempel-IDX.
cardIdx integer
Karten-IDX.
Die Karten-IDX kann auf der Seite „Stempelkarte“ im Dashboard eingesehen werden.
stamps integer
Gibt die Anzahl der gesammelten Stempel an.
Zeigt die Gesamtzahl der Stempel, die der Kunde gesammelt hat. Durch das Ändern dieses Wertes wird der Stempelstatus aktualisiert; sowohl Erhöhungen als auch Verringerungen sind möglich.
Wenn alle Stempel gesammelt wurden (stamps = maximale Stempelanzahl der Karte), muss useYn auf Y gesetzt werden, um den Stempel als eingelöst zu markieren.
resetPinYn string
Default:N
Enum:
YN
Legt fest, ob die PIN des Kunden für den Stempel zurückgesetzt werden soll.
Y: Setzt die vom Kunden festgelegte PIN zurück. Nach dem Zurücksetzen muss der Kunde beim nächsten Aufruf der Stempelseite eine neue PIN festlegen.
N: Behält die aktuelle PIN bei.
useYn string
Default:N
Enum:
YN
Gibt an, ob der Kunde die Stempelbelohnung verwendet hat.
Y: Der Kunde hat alle Stempel gesammelt und eine Belohnung eingelöst (z. B. kostenloses Getränk, Rabatt usw.). Nach der Einlösung wird der Stempel deaktiviert und ein neuer muss ausgegeben werden.
N: Die Belohnung wurde noch nicht eingelöst.
domain string
Default:https://vvd.bz
Stempel-Domain.
Wenn kein Wert angegeben wird, wird die Standarddomain verwendet.
Verfügbar für Premium-Tarife oder höher — Sie können eine benutzerdefinierte Domain angeben, die im Bereich „Link-Domain-Verwaltung“ registriert ist.
strtYmd date
Startdatum der Stempelgültigkeit. Beispiel: 2025-01-01
endYmd date
Ablaufdatum des Stempels. Beispiel: 2025-12-31
Das Ablaufdatum kann bis zu 5 Jahre ab dem heutigen Datum festgelegt werden.
activeYn string
Default:Y
Enum:
YN
Gibt an, ob der Stempel aktiv ist. Wenn deaktiviert, kann der Kunde den Stempel nicht verwenden.
memo string
Interne Notiz zu Referenzzwecken.
userId string
Benutzer-ID. Wird verwendet, um den Empfänger des Stempels zu verwalten.
Normalerweise geben Sie die Login-ID des Website-Mitglieds ein.
Wenn kein Wert angegeben wird, generiert das System automatisch eine Benutzer-ID.
userNm string
Benutzername. Nur für interne Verwendung.
userPhnno string
Telefonnummer des Benutzers. Nur für interne Verwendung.
userEml string
E-Mail-Adresse des Benutzers. Nur für interne Verwendung.
userEtc1 string
Zusätzliches Feld für interne Verwaltung.
userEtc2 string
Zusätzliches Feld für interne Verwaltung. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
Antwortcode: 0 = Erfolg, andere Werte = Fehler
message string
Antwortnachricht. Wenn der Code nicht 0 ist, wird eine Fehlermeldung zurückgegeben.
result null

Warum die direkte Steuerung der Stempelanzahl notwendig ist

Beim Betrieb eines Stempelsystems gibt es Situationen, in denen die Anzahl manuell angepasst werden muss.

Typische Fälle sind die Korrektur fehlerhafter Vergaben, Bonusaktionen und manuelle Anpassungen durch Administratoren.

Mit dem Parameter stamps können Sie den aktuellen Wert erhöhen oder verringern, ohne ihn zu überschreiben.
Wird die maximale Anzahl erreicht, muss useYn auf Y gesetzt werden, um die Belohnung zu verarbeiten.

Ablauf von Belohnung und erneuter Stempelvergabe

Wenn useYn auf Y gesetzt wird, gilt der Stempel als eingelöst.

Nach der Einlösung muss ein neuer Stempel über die Erstellungs-API ausgegeben werden, um die Sammlung neu zu starten.
Dieser Ablauf bildet den zentralen Zyklus eines stempelbasierten Belohnungssystems.
Die Automatisierung von Einlösung → Neuerstellung → erneute Sammlung fördert wiederkehrende Interaktionen.

Wann ein PIN-Reset erforderlich ist

Wird resetPinYn auf Y gesetzt, wird die PIN des Nutzers zurückgesetzt.

Dies ist erforderlich, wenn der Nutzer seine PIN vergisst, das Gerät wechselt oder aus Sicherheitsgründen ein Reset notwendig ist.

Nach dem Zurücksetzen muss der Nutzer beim Zugriff auf die Stempelseite eine neue PIN festlegen. Bei N oder fehlendem Parameter bleibt die bestehende PIN erhalten.

Anwendungsfälle

  • Fehlerkorrektur: Falsch vergebene Stempel manuell korrigieren
  • Kampagnenanpassung: Änderungen während laufender Kampagnen übernehmen
  • Erneute Verifizierung: PIN-Reset für erneute Offline-Authentifizierung
  • Deaktivierung: Stempel nach Kampagnenende deaktivieren

Wichtige Hinweise

  • Stellen Sie sicher, dass Änderungen an stamps mit der bestehenden Historie konsistent sind
  • Nach der Nutzung (useYn) sollte der Vorgang als irreversibel behandelt werden
  • Führen Sie Betriebsprotokolle und eine detaillierte Änderungshistorie für Nachvollziehbarkeit und Audit