Installieren Sie die Vivoldi-App von Google Play, um es noch bequemer zu machen.

Stempel-Belohnung Einlösen API (v2)

Die API zum Einlösen von Stempel-Belohnungen markiert eine Belohnung (z. B. kostenloses Getränk oder Rabatt) als eingelöst, sobald alle erforderlichen Stempel gesammelt wurden.

Nach der Einlösung kann der Stempel nicht erneut verwendet werden, und ein neuer muss erstellt werden, um den nächsten Zyklus zu starten.
Sie wird in Systemen verwendet, die Belohnungen basierend auf Besuchs- oder Kaufhistorie anbieten.

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

PUT

/api/stamp/v2/redeem 

{
    "stampIdx": 394,
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stamp IDX.
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.
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": 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.

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.

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.

In welcher Phase wird diese API verwendet?

Dies ist die letzte Phase im Stempelsystem.

  • Überprüfung der vollständigen Sammlung
  • Durchführung der Belohnung
  • Statuswechsel auf eingelöst

Es handelt sich nicht nur um eine Statusänderung, sondern um den finalen Abschluss des Kampagnenergebnisses.

Abschluss des Stempelzyklus

Diese API stellt den letzten Schritt im Stempelzyklus dar.

Für Nutzer ist es der Moment der Belohnung. Für Entwickler markiert es das Ende eines Zyklus und den Beginn des nächsten.

Nach dem Redeem-Aufruf sollte Create erneut ausgeführt werden, um die Nutzung fortzusetzen.

Gesamter Ablauf

  1. Create → Stempel erstellen
  2. Add Stamp → Stempel sammeln
  3. Validate → Status prüfen
  4. Redeem → Belohnung einlösen
  5. Create → Neuer Zyklus starten

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.

Automatisierung nach Einlösung

Nach der Einlösung können Folgeprozesse automatisiert werden.

  • Die Coupon Create API aufrufen, um sofort eine Belohnung auszustellen
  • Einen neuen Stempel erstellen, um den nächsten Zyklus zu starten

Dies ermöglicht einen vollständig automatisierten Reward-Lifecycle ohne manuelle Eingriffe.

Wichtige Punkte im Betrieb

Diese API ist nicht nur eine Funktion, sondern der Punkt, an dem Geschäftsergebnisse verbindlich festgelegt werden.

Stellen Sie sicher, dass die Reihenfolge Validierung → Einlösung, serverseitige Transaktionskontrolle und Audit-Logging eingehalten wird.