Online Stempel-Update-API

API Version

PUT

/api/stamp/v2/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

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 onsiteToken mitgesendet werden.
onsiteToken string: Kurzlebiges Austausch-Token. v2 akzeptiert das Klartext-Passwort (onsitePwd) nicht.
Hat die Ressource onsiteYn = Y, senden Sie das von der Validate-API zurückgegebene onsiteToken unverändert.
Idempotency-Key ist bei Anfragen mit Token erforderlich. Ein erneuter Versuch mit demselben Schlüssel gibt das ursprüngliche Ergebnis zurück; dasselbe Token mit einem anderen Schlüssel wird mit 400 (Fehlercode 1228) abgelehnt.
Wurde bei der Prüfung ein verarbeitendes Geschäft angegeben, muss diese Anfrage dasselbe verwenden.
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.
branchIdx integer: IDX der ausgebenden Filiale. Ohne Angabe erfolgt die Ausgabe durch die Zentrale; senden Sie 0, um den Wert zu leeren.
Ab dem Business-Tarif verfügbar.
storeIdx integer: IDX des ausgebenden Geschäfts. Bei Angabe wird die Filiale, zu der das Geschäft gehört, zur ausgebenden Filiale. Eine abweichende Filiale führt zu einem Fehler.
useScope string: Nutzungsbereich. Zulässig sind nur ALL (alle Geschäfte) oder BRANCH (eine bestimmte Filiale). Ohne Angabe gilt ALL.
useBranchIdx integer: IDX der Nutzungsfiliale. Nur erforderlich, wenn useScope = BRANCH; bei ALL immer leer.

{
    "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.

Ausgebende Filiale, ausgebendes Geschäft und Nutzungsbereich

Die hier angegebenen Werte sind die bei der Ausgabe gespeicherte Richtlinie. "Wo wurde ausgegeben" (ausgebende Filiale, ausgebendes Geschäft) und "wo kann der Kunde es einlösen" (Nutzungsbereich, Nutzungsfiliale) sind unterschiedliche Konzepte, daher sind die Parameter getrennt.

Parameter	Bedeutung	Beschreibung
`branchIdx`	Ausgebende Filiale	Ohne Angabe gibt die Zentrale aus. Senden Sie `0`, um auf die Zentrale zurückzusetzen.
`storeIdx`	Ausgebendes Geschäft	Bei Angabe wird die Filiale des Geschäfts zur ausgebenden Filiale. Eine abweichende Filiale wird abgelehnt.
`useScope`	Nutzungsbereich	`ALL` (alle Geschäfte) oder `BRANCH` (eine Filiale). Standard ist `ALL`.
`useBranchIdx`	Nutzungsfiliale	Nur bei `useScope=BRANCH` erforderlich. Bei `ALL` immer leer.

Nicht verwendbare Parameter — processStoreIdx (verarbeitendes Geschäft) bezeichnet das Geschäft, in dem eine Prüfung, Einlösung, Gutschrift oder Abbuchung tatsächlich stattgefunden hat, und kann in dieser API nicht verwendet werden. Bei Angabe wird mit 400 (Fehlercode 1227) abgelehnt.

Filial- und Geschäftsfunktionen stehen nur ab dem Business-Tarif zur Verfügung.

Idempotency-Key

Um nach einem Netzwerkfehler sicher erneut zu senden, übermitteln Sie im Header Idempotency-Key einen pro Anfrage eindeutigen Wert. Alternativ können Sie ihn als requestId im Body senden; werden beide mit unterschiedlichen Werten gesendet, wird die Anfrage abgelehnt. Zulässig sind 8–64 Zeichen aus Buchstaben, Ziffern und . _ : -.

Wird dieselbe Anfrage mit demselben Key erneut gesendet, wird das ursprüngliche Ergebnis zurückgegeben, ohne erneut zu verarbeiten. Nichts wird doppelt verarbeitet und Webhooks werden nicht erneut gesendet.

Verwenden Sie denselben Key nur für Wiederholungen derselben logischen Operation. Für eine andere Operation verwenden Sie stets einen neuen Key. Derselbe Key mit anderem Anfrageinhalt oder für eine andere Operation kann mit 409 abgelehnt werden.

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.

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

v2 akzeptiert das Vor-Ort-Passwort (onsitePwd) nicht im Klartext. Senden Sie das von der Validate-API zurückgegebene onsiteToken unverändert. Wird onsitePwd allein oder zusammen mit onsiteToken gesendet, wird die Anfrage mit 400 (Fehlercode 1227) abgelehnt.

Idempotency-Key ist für Anfragen mit Token erforderlich. Ein erneuter Versuch mit demselben Idempotency-Key gibt das ursprüngliche Verarbeitungsergebnis zurück. Wird dasselbe Token mit einem anderen Idempotency-Key wiederverwendet, wird die Anfrage mit 400 (Fehlercode 1228) abgelehnt.

Das bei der Validierung verwendete Geschäft muss mit dem Geschäft übereinstimmen, in dem die Verarbeitung erfolgt. Wurde bei der Validierung processStoreIdx angegeben, muss diese Anfrage dasselbe Geschäft verwenden. Ein ohne Geschäft validiertes Token kann nachträglich keinem Geschäft zugeordnet werden.

Abgelaufene, manipulierte, bereits verwendete oder falsch gebundene Token geben alle 1228 zurück. Die Ursachen werden bewusst nicht getrennt ausgewiesen, damit Dritte den internen Zustand nicht mithilfe anderer Token ausforschen können.

Für Ressourcen ohne Vor-Ort-Verifizierung (onsiteYn = N) ist kein Token erforderlich. v1 akzeptiert onsitePwd weiterhin im Klartext.

Diese API verwendet das Token nur, wenn tatsächlich ein Übergang zur Prämieneinlösung (N → Y) erfolgt. Wird ein Token bei einer normalen Aktualisierung mitgesendet, die nur Notiz, Zeitraum oder Aktivstatus ändert, wird die Anfrage mit 400 (Fehlercode 1227) abgelehnt. Auch wenn die Anfrage useYn = Y enthält, wird das Token nicht verbraucht, solange kein tatsächlicher Übergang N → Y stattfindet (zum Beispiel wenn die Prämie bereits eingelöst wurde).

Diese API akzeptiert keinen Parameter für das verarbeitende Geschäft (processStoreIdx). Bei einer Prämieneinlösung wird der Verarbeitungsort aus dem bei der Validierung an das Token gebundenen Geschäft ermittelt, nicht aus der Anfrage, und im Ereignis sowie im Webhook protokolliert. Bei normalen Aktualisierungen wird dieser Verarbeitungsort nicht angewendet.

Dasselbe Token kann auch mit der API zur Prämieneinlösung (Redeem) verwendet werden, jedoch nur einmal in einer der beiden APIs. Sobald das Token in einer API verbraucht wurde, wird es von der anderen abgelehnt.

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

Stempel-Update-API (v2)