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

Stempel-Belohnung Einlösen API (v1)

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.

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.

PUT

/api/stamp/v1/redeem 

{
    "stampIdx": 394,
    "onsitePwd": "12345"
}

Request Parameters

stampIdx integer required
Stamp IDX.
onsitePwd string
Mitarbeiter-Passwort für Vor-Ort-Stempel.
Nur erforderlich, wenn onsiteYn = Y gesetzt ist, und muss vom Mitarbeiter bei der Bestätigung der Belohnung eingegeben werden.
Verwenden Sie den von der Validate API zurückgegebenen Wert onsitePwd. 
{
    "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.

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

Vor-Ort Stempelverarbeitung

onsitePwd wird nur benötigt, wenn ein Vor-Ort-Verifizierungspasswort aktiviert ist (onsiteYn = Y).

Mitarbeiter geben diesen Wert ein, um die Einlösung zu bestätigen und unbefugte Nutzung zu verhindern.

Verwenden Sie den von der Validierungs-API zurückgegebenen onsitePwd.
Ohne Passwort kann dieses Feld weggelassen werden.

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.