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

Stempel hinzufügen API (v2)

Die API zum Hinzufügen von Stempeln erhöht die Anzahl eines bestehenden Stempels um eins.

Wenn ein Nutzer einen Kauf, Besuch oder eine bestimmte Aktion abschließt, wird durch den API-Aufruf automatisch ein Stempel hinzugefügt.
Sobald die maximale Anzahl auf der Karte erreicht ist, werden keine weiteren Stempel hinzugefügt.

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

PUT

/api/stamp/v2/add 

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stempel-IDX.
stamps integer
Anzahl der Stempel, die hinzugefügt (oder abgezogen) werden. Standardwert 1, muss größer als 0 sein.
Mengen über dem Kartenmaximum oder unter null werden vom Server begrenzt. Beträgt die tatsächliche Änderung 0, werden weder Verlaufseintrag noch Webhook erzeugt.
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.

Warum diese API zentral ist

Während die Create-API die Karte erstellt, erfasst die Add-API die tatsächlichen Nutzeraktionen.

Jeder Kauf oder Besuch wird erfasst und ermöglicht ein verhaltensbasiertes Belohnungssystem ohne separates Punktesystem.

Eine einzelne API-Anfrage reicht aus, um Aktionen direkt mit der Stempelvergabe zu verknüpfen.

Verhalten bei Erreichen des Maximums

Wenn die maximale Anzahl erreicht ist, werden keine weiteren Stempel hinzugefügt.
Empfohlener Ablauf:

  1. stamps und maxStamps prüfen
  2. Wenn gleich → vollständig erreicht
  3. Update API mit useYn=Y aufrufen
  4. Stamp Create API für neuen Zyklus aufrufen
  5. Neuen Akkumulationszyklus starten

Bedingungen und Einschränkungen

Die Stempelvergabe erfolgt nicht in jedem Fall automatisch.

Folgende Bedingungen müssen erfüllt sein:

  • Stempel ist aktiv (activeYn = Y)
  • Innerhalb des gültigen Zeitraums (strtYmd ~ endYmd)
  • Maximalwert nicht erreicht (stamps < maxStamps)
  • Noch nicht eingelöst

Diese Bedingungen gewährleisten eine korrekte Vergabe gemäß den Kampagnenregeln.

Anwendungsfälle

  • Besuchsbasierte Events: Ein Stempel pro Besuch
  • Kaufbelohnung: Automatische Vergabe nach Zahlung
  • Missionsbasierte Events: Stempel nach Abschluss bestimmter Aktionen
  • Täglicher Check-in: Ein Stempel pro Login

Wichtige Punkte im Betrieb

Die Stempel-Add-API ist ein zentraler Bestandteil, der die Qualität von Kampagnen direkt beeinflusst.

  • Fehlerhafte Stempelvergabe verringert das Vertrauen in die Kampagne
  • Doppelte API-Aufrufe können zu übermäßiger Vergabe führen
  • Hat direkten Einfluss auf die Nutzererfahrung

Sollte immer zusammen mit Validierung und serverseitiger Logiksteuerung verwendet werden.