API zur Gutscheineinlösung (Redeem)

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/v1/redeem 

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

Request Parameters

cpnNo string required
Coupon-Nummer.
onsitePwd string
Passwort für Vor-Ort-Coupon. Erforderlich, wenn für den Vor-Ort-Coupon ein Passwort festgelegt ist.
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. 
{
    "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

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.

Passwortverarbeitung für Vor-Ort-Gutscheine

Das Feld onsitePwd ist erforderlich, wenn ein Gutschein durch ein Passwort geschützt ist.

Es wird in Offline- oder Vor-Ort-Szenarien verwendet, in denen Mitarbeiter das Passwort vor der Einlösung überprüfen.

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.