API zur Gutscheinvalidierung

Die Vivoldi Coupon Validation API ermöglicht es, vor der Einlösung zu prüfen, ob ein Gutschein gültig ist.

Neben der Verfügbarkeit liefert sie auch Rabattdetails, Nutzungsbedingungen und Benutzerdaten, sodass flexible Geschäftslogiken umgesetzt werden können.

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

GET

/api/coupon/v1/validate?cpnNo={cpnNo} 


GET /api/coupon/v1/validate
     ?cpnNo=ZJLF0399WQBEQZJM

Request Parameters

cpnNostringrequired
Coupon-Nummer. 
{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsitePwd": "12345",
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25"
    }
}

Response Parameters

codeinteger
Antwortcode: 0 = Erfolgreich, jeder andere Wert = Fehler
messagestring
Antwortnachricht. Wenn der Antwortcode ungleich 0 ist, wird eine Fehlermeldung zurückgegeben.
resultobject
Bei erfolgreicher Prüfung: Die Antwort enthält die Coupon-Informationen.
Bei fehlgeschlagener Prüfung: Die Antwort ist null und kann über die Fehlermeldung eingesehen werden.
cpnNostring
Coupon-Nummer.
domain string
Coupon-Domain.
nmstring
Coupon-Name.
discTypeIdxinteger
Rabatt-Typ. (457: Prozent-Rabatt %, 458: Betrag-Rabatt)
discdouble
Für Prozentrabatt (457): Bereich 1–100%. Für Betragsrabatt (458): Betrag eingeben.
discCurrencystring
Währungseinheit. Erforderlich bei Betragsrabatt (discTypeIdx:458).
formatDiscCurrencystring
Währungssymbol.
strtYmddate
Startdatum der Coupon-Gültigkeit.
endYmddate
Ablaufdatum des Coupons.
useLimitinteger
Nutzungslimit für Coupons. (0: unbegrenzt, 1–5: begrenzte Nutzung)
imgUrlstring
Coupon-Bild-URL.
onsiteYnstring
Vor-Ort-Coupon. Bestimmt, ob die Schaltfläche „Coupon verwenden“ auf der Coupon-Seite angezeigt wird.
Erforderlich, wenn Coupons in einem stationären Geschäft eingelöst werden.
onsitePwd string
Passwort für Vor-Ort-Coupons.
Erforderlich beim Aufruf der Coupon-Verwendungs-API, wenn die Vor-Ort-Option aktiviert ist (Y).
memostring
Interne Notiz.
urlstring
Wenn eine URL eingegeben wird, erscheint auf der Coupon-Seite die Schaltfläche „Zum Coupon einlösen“.
Ein Klick auf die Schaltfläche oder das Coupon-Bild leitet zur angegebenen URL weiter.
userIdstring
Wird zur Verwaltung des Coupon-Empfängers verwendet.
Pflichtfeld, wenn die Nutzung auf 2–5 festgelegt ist.
In der Regel Login-ID oder englischer Name des Website-Mitglieds.
userNmstring
Name des Coupon-Nutzers. Nur für interne Verwaltung.
userPhnnostring
Telefonnummer des Coupon-Nutzers. Nur für interne Verwaltung.
userEmlstring
E-Mail des Coupon-Nutzers. Nur für interne Verwaltung.
userEtc1string
Zusätzliches internes Feld.
userEtc2string
Zusätzliches internes Feld.
useCntinteger
Anzahl der Coupon-Nutzungen.
regYmdtdatetime
Erstellungsdatum des Coupons. Beispiel: 2025-07-21 11:50:20

Was lässt sich aus dem Validierungsergebnis ableiten?

Diese API geht über eine einfache „gültig / ungültig“-Prüfung hinaus.
Sie ist darauf ausgelegt, dass Entwickler auf Basis detaillierter Daten eigene Logiken implementieren können.

Mit den Antwortdaten (result) können Sie Folgendes bestimmen:

  • Ob ein Rabatt angewendet werden kann und wie hoch er ist
  • Ob der Gutschein auf bestimmte Nutzer beschränkt ist (userId, userEml)
  • Ob Nutzungslimits überschritten wurden (useCnt, useLimit)
  • Ob der Gutschein abgelaufen ist oder noch nicht gültig ist (strtYmd, endYmd)
  • Ob bestimmte Bedingungen erfüllt sind (online/offline, etc.) (onsiteYn)
  • Die Ziel-URL nach Anwendung des Gutscheins (url)

Mit anderen Worten: Statt eines einfachen Ergebnisses
erhalten Sie strukturierte Daten für flexible Anwendungslogik.

Validierungsmethode

Die Validierung erfolgt anhand des Gutscheincodes (cpNo) unter Berücksichtigung mehrerer Kriterien.

  • Existenz
  • Gültigkeitszeitraum
  • Nutzungslimits
  • Nutzerbedingungen
  • Anwendungsumgebung

Das Ergebnis wird als strukturierte Daten zurückgegeben, nicht nur als Boolean.

Nutzung der Antwortdaten

Das result-Objekt enthält alle wesentlichen Gutscheininformationen.

Entwickler können diese Daten verwenden, um:

  • Rabatte in Echtzeit im Frontend zu berechnen und anzuzeigen
  • Die Nutzung auf bestimmte Benutzer zu beschränken
  • Bedingte Logik basierend auf dem Zahlungsbetrag umzusetzen
  • UI-Meldungen je nach Gutscheinstatus anzuzeigen (abgelaufen, eingelöst, etc.)

Anwendungsfälle

  • Prüfung vor Zahlung: Gutschein validieren und nur bei Gültigkeit anwenden
  • Benutzerhinweise: Meldungen je nach Ergebnis anzeigen (abgelaufen oder bereits eingelöst)
  • Rabattberechnung: Daten (disc, discType) zur Berechnung des Endbetrags nutzen

Nach dem Löschen kann derselbe Code erneut verwendet werden.

Wichtige Hinweise

  • Das Validierungsergebnis entspricht dem Status zum Zeitpunkt der Abfrage und kann sich bis zur Einlösung ändern.
  • Implementieren Sie stets den Ablauf: Validierung → Einlösung (Redeem).
  • Eine ausschließliche clientseitige Validierung stellt ein Sicherheitsrisiko dar.
  • Überprüfen Sie die Rabattberechnung zusätzlich serverseitig, um Genauigkeit und Sicherheit zu gewährleisten.