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

Stempel reduzieren API (v2)

Die API zum Reduzieren von Stempeln verringert die Anzahl eines bestehenden Eintrags um eins.

Sie gehört nicht zum normalen Ablauf, sondern wird für Korrekturen wie fehlerhafte Vergaben, Anpassungen von Kampagnenregeln oder zur Bearbeitung von Nutzeranfragen verwendet.
Die Anzahl der Stempel fällt niemals unter null.

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

PUT

/api/stamp/v2/remove 

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

Wann Stempel reduziert werden sollten

Diese API ist nicht für die häufige Nutzung gedacht, sondern als Werkzeug zur Behebung von Datenproblemen.
Sie wird in folgenden Fällen eingesetzt:

  • Doppelte Verarbeitung führt zu mehrfacher Stempelvergabe
  • Systemfehler verursachen falsche Erhöhungen
  • Änderungen der Kampagnenregeln erfordern Datenanpassungen
  • Fehlerhafte Vergaben müssen rückgängig gemacht werden

Unkorrigierte Daten erhöhen Kosten und senken das Vertrauen.
Diese API ermöglicht eine sofortige Korrektur.

Beziehung zur Add Stamp API

Beide APIs arbeiten in entgegengesetzte Richtungen, erfüllen jedoch klar definierte Rollen.

  1. Add Stamp → Erfasst Nutzeraktionen im normalen Ablauf
  2. Remove Stamp → Korrigiert oder setzt Daten zurück

Bei jeder Nutzung der Add Stamp API sollten Fehler- und Abbruchszenarien berücksichtigt werden,
und Remove Stamp in den Ablauf integriert werden, um Stabilität zu gewährleisten.

Wichtige Punkte im Betrieb

Die Stempel-Reduzierungs-API wird selten verwendet und ist eine wichtige Verwaltungs-API zur Behebung von Datenproblemen.

  • Nicht korrigierte Daten verringern das Vertrauen
  • Übermäßige Vergabe erhöht die Kosten
  • Kann die Nutzererfahrung negativ beeinflussen

Verwenden Sie sie zusammen mit Audit-Logs und strenger administrativer Zugriffskontrolle.

Wichtige Hinweise

  • Die Anzahl fällt nicht unter 0. Prüfen Sie stamps mit der Validierungs-API vor der Reduzierung
  • Wiederholte Aufrufe können zu übermäßiger Reduzierung führen
  • Nicht direkt vom Client aufrufen; serverseitige Kontrolle ist erforderlich
  • Änderungen protokollieren und durch Adminrechte schützen