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

API zur Gutscheineinlösung (Redeem) (v2)

Die Vivoldi Coupon Redeem API markiert einen ausgestellten Gutschein als eingelöst.

Die Einlösung kann automatisch per API erfolgen, ohne manuelle Bearbeitung im Dashboard.
Jeder Aufruf reduziert die verbleibenden Nutzungen, und nach Erreichen des Limits wird die weitere Einlösung blockiert.

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

PUT

/api/coupon/v2/redeem 

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233",
    "processStoreIdx": 22
}

Request Parameters

cpnNo string required
Coupon-Nummer.
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.
userId string
Benutzer-ID. Identifiziert den Aussteller oder Nutzer des Coupons.
Muss angegeben werden, wenn das Nutzungslimit des Coupons auf 2–5 gesetzt ist.
memo string
Interne Notiz. Kann verwendet werden, um Benutzer-IP, Einsatzort des Coupons oder andere Informationen zu dokumentieren.
Wenn die Nutzung des Coupons unbegrenzt ist, kann dieses Feld anstelle von userId genutzt werden, um Benutzer zu unterscheiden.
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

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.

Verwendung mit der Validierungs-API

Da die Coupon Redeem API den Status ändert, wird empfohlen, vor dem Aufruf die Gültigkeit mit der Validierungs-API zu prüfen.

Durch die vorherige Prüfung können unnötige Verarbeitungen für abgelaufene oder bereits eingelöste Gutscheine vermieden werden.

Der Standardablauf ist: Validierung → Einlösung.

Wann diese API verwenden

Verwenden Sie diese API, wenn Sie einen Gutschein nach der Validierung anwenden möchten.

  • Markieren eines Gutscheins als eingelöst nach erfolgreicher Zahlung
  • Erfassung der Rabattnutzung bei Bestellbestätigung
  • Verarbeitung von Vor-Ort- oder Offline-Nutzung
  • Statusaktualisierung zur Vermeidung von Mehrfachnutzung

Kurz gesagt: Dies ist der letzte Schritt, in dem der Gutschein tatsächlich verwendet wird.

Ablauf der Gutscheineinlösung

Der Gutschein wird anhand des Codes (cpnNo) als eingelöst markiert.

  • Die Nutzung wird sofort reduziert
  • Der Gutschein wird in einen nicht wiederverwendbaren Zustand versetzt
  • Die Einlösung wird basierend auf Benutzerdaten (userId) protokolliert
  • Zusätzliche Informationen können über das Feld memo gespeichert werden

Dies ist nicht nur eine Statusänderung, sondern eine zentrale Transaktion im Zahlungsprozess.

Benutzeridentifikation und Memo-Nutzung

userId dient zur Identifikation des Nutzers, der den Gutschein einlöst.

Bei einer Nutzung von 2–5 Mal ist dieser Wert erforderlich und verhindert doppelte Nutzung durch denselben Benutzer.

Das Feld memo kann interne Informationen wie IP-Adresse, Nutzungsort oder Anfragequelle speichern.
Bei unbegrenzter Nutzung kann es auch als Alternative zu userId verwendet werden.

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.

Anwendungsfälle

  • E-Commerce-Integration: API nach Zahlungsabschluss aufrufen, um Gutscheine automatisch einzulösen und Rabatte zu erfassen
  • Vor-Ort-Nutzung: Mitarbeiter scannen den QR-Code, erfassen den Code und lösen ihn sofort per API ein
  • Nutzungsanalyse: IP und Anfragequelle in memo speichern, um Missbrauch oder Auffälligkeiten zu erkennen
  • Mehrfachnutzung kontrollieren: Mit userId verhindern, dass ein Benutzer das Limit überschreitet

Nach dem Löschen kann derselbe Code erneut verwendet werden, um einen neuen Gutschein zu erstellen.

Wichtige Hinweise

  • Rufen Sie diese API aus Sicherheitsgründen immer nach der Validierung auf.
  • Nach der Einlösung kann der Gutschein nicht erneut verwendet werden.
  • Bei fehlgeschlagener Zahlung kann eine Rollback-Strategie erforderlich sein.
  • Implementieren Sie Mechanismen zur Vermeidung von doppelten Einlösungen bei wiederholten Anfragen.