Coupon Validation API für Online-Gutscheine

API Version

GET

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

Request
Response


GET /api/coupon/v2/validate
     ?cpnNo=ZJLF0399WQBEQZJM
     &processStoreIdx=22

Request Parameters

cpnNostringrequired: Coupon-Nummer.
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": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "grpIdx": 271,
        "grpNm": "Birthday 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",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "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",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

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.

Token für die Vor-Ort-Verifizierung (onsiteToken)

Die Antwort der v2-Validate-API enthält das Vor-Ort-Passwort (onsitePwd) nicht im Klartext. Stattdessen wird ein onsiteToken zurückgegeben, das 180 Sekunden gültig ist.

Ziel ist es, die Offenlegung des Klartextpassworts zu minimieren, nicht die Authentifizierung zu verstärken. Die Validate-API prüft das Passwort selbst nicht, daher stellt das Token keinen zusätzlichen Authentifizierungsfaktor dar. Stattdessen begrenzen kurze Gültigkeit, einmalige Verwendung und Kontextbindung die Wiederverwendung des Tokens.

Element	Wert
Gültigkeit	180 Sekunden. Die Gültigkeitsdauer wird zusätzlich in `onsiteTokenExpiresIn` zurückgegeben.
Verwendungen	Einmal. Nach der Verwendung geben nur Wiederholungen mit demselben `Idempotency-Key` das ursprüngliche Ergebnis zurück.
Bindung	Organisation, Konto des API-Schlüssels, Ressource, Aktion und das bei der Validierung bestätigte verarbeitende Geschäft
Anwendungsfälle	Coupon-Einlösung, Einlösung einer Stempelprämie und Stempelaktualisierung mit `useYn = Y`

Für Ressourcen ohne Vor-Ort-Verifizierung (onsiteYn = N) wird kein Token ausgegeben. Die v1-Validate-API gibt onsitePwd weiterhin im Klartext zurück.

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.

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.

API zur Gutscheinvalidierung (v2)