Stempel-Update-API (v1)

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.

v1-Dokumentation (Legacy).

Für neue Integrationen empfehlen wir die Verwendung der neuesten Version v2.
v1 dient der Aufrechterhaltung bestehender Integrationen und erhält keine neuen Funktionen oder Verbesserungen.

API Version

PUT

/api/stamp/v1/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsitePwd": "12345",
    "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.
Beim Wechsel von N zu Y muss die gespeicherte Stempelanzahl die maximale Stempelanzahl der Karte erreicht haben, und bei Stempeln mit Vor-Ort-Passwort muss onsitePwd mitgesendet werden.
onsitePwd string: Mitarbeiter-Passwort für Vor-Ort-Stempel.
Erforderlich, wenn useYn von N auf Y geändert wird, um die Belohnung als eingelöst zu markieren, sofern onsiteYn = Y gesetzt ist. Es gilt dieselbe Prüfregel wie bei der Redeem-API.
Nicht erforderlich, wenn nur die Stempelanzahl geändert wird oder der Stempel kein Passwort hat.
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

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.

Hinweis zur Verhaltensänderung. Bisher verarbeitete v1 die Anfrage auch dann weiter, wenn diese Prüfung fehlschlug. Dadurch konnte der Fehler von der Meldung eines anderen Parameters überschrieben werden, oder ein Teil der Stempeldaten wurde tatsächlich gespeichert, obwohl die Antwort einen Fehler meldete. Jetzt bricht die Verarbeitung wie in der neuesten Version vorher mit 400 ab.

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.

Vor-Ort-Passwort bei der Prämieneinlösung

Wenn Sie useYn von N auf Y ändern, um eine Prämie einzulösen, müssen Sie zusätzlich onsitePwd senden, wenn für den Stempel ein Passwort für die Stempelvergabe vor Ort eingerichtet ist (onsiteYn = Y).

Diese Anforderung gilt genauso wie bei der API zur Prämieneinlösung (Redeem). Dadurch wird verhindert, dass eine Prämie über die Update-API ohne Passwortprüfung eingelöst wird.

Das zu übermittelnde Passwort finden Sie im Wert onsitePwd, der von der Validierungs-API (Validate) zurückgegeben wird. Ist für den Stempel kein Vor-Ort-Passwort eingerichtet, kann onsitePwd weggelassen werden.

onsitePwd ist nicht erforderlich, wenn Sie nur die Anzahl der Stempel ändern oder einen Stempel aktualisieren, dessen Prämie bereits eingelöst wurde.

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