API zur Erstellung von Online-Gutscheinen

Die Vivoldi Coupon Creation API ermöglicht es, Rabattgutscheine programmgesteuert zu erstellen.

Wählen Sie zwischen prozentualen (%) oder festen Rabattbeträgen und konfigurieren Sie Optionen wie Ablaufdatum, Nutzungsbeschränkungen, Gruppe und Vorlage direkt in der Anfrage.

Für die Erstellung mehrerer Gutscheine verwenden Sie das Dashboard.
Wenn Bilder benötigt werden, erstellen Sie zunächst eine Gutschein-Gruppe im Dashboard, laden Bilder hoch und generieren anschließend Gutscheine mit dieser Gruppe.

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

POST

/api/coupon/v1/create 

{
    "cpnNo": "",
    "cpnNoDigits": 12,
    "domain": "https://vvd.bz",
    "webhookEnableYn": N",
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5,
    "discCurrency": "USD",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "useLimit": 1,
    "grpIdx": 271,
    "tmplIdx": 0,
    "onsiteYn": "Y",
    "onsitePwd": "123456",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "url": "https://bestshop.com",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cpnNostring
Coupon-Nummer. 8–16 alphanumerische Zeichen. Wenn kein Wert angegeben ist, wird sie automatisch vom System generiert. Sonderzeichen sind nicht erlaubt.
Beispiel: V5H8GR5T
cpnNoDigits integer
Default:16
Enum:
16128
Länge des Coupon-Codes.
Wird kein Wert angegeben, gilt die Standardlänge (16).
Gilt nur, wenn kein Code vorgegeben ist. Das System erstellt automatisch einen Code mit der gewählten Länge.
domain string
Standard:https://vvd.bz
Coupon-Domain.
Wenn leer gelassen, wird die Standarddomain verwendet.
Verfügbar in Premium-Tarifen und höher: Sie können eine in der Link-Domain-Verwaltung registrierte benutzerdefinierte Domain angeben.
webhookEnableYn string
Enum:
YN
Einstellung für die Webhook-Nutzung.
Der globale Webhook muss aktiviert sein.
Diese Funktion ist nur im Enterprise-Tarif verfügbar.
nmstringrequired
Coupon-Name.
discTypeIdxintegerrequired
Rabatt-Typ. (457: Prozentsatz %, 458: Fester Betrag)
discdoublerequired
Für Prozentsatz (457): Bereich von 1–100%. Für festen Betrag (458): Betrag eingeben.
discCurrencystring
Währungseinheit. Pflichtfeld bei Verwendung eines festen Betragsrabattes (discTypeIdx:458).
strtYmddaterequired
Startdatum der Coupon-Gültigkeit. Beispiel: 2024-10-01
endYmddaterequired
Ablaufdatum des Coupons. Beispiel: 2024-12-31
Das Ablaufdatum kann nur bis zum 31. Dezember des folgenden Jahres festgelegt werden.
useLimitintegerrequired
Nutzungsbeschränkung für den Coupon. (0: Unbegrenzt, 1–5: Nutzungsanzahl)
Wenn 2 oder mehr angegeben sind, muss userId zwingend angegeben werden.
grpIdxinteger
Coupon-Gruppe. Wird verwendet, um Coupons in Gruppen zu verwalten. Die Gruppen-ID (IDX) kann im Dashboard eingesehen werden.
Wenn Gruppeneinstellungen und Coupon-Einstellungen überschneiden, haben die Gruppeneinstellungen Vorrang.
tmplIdxinteger
Coupon-Vorlage. Wird beim Erstellen eines Coupons als Referenz verwendet. Die Vorlagen-ID (IDX) kann im Dashboard eingesehen werden.
onsiteYnstring
Vor-Ort-Coupon. Zeigt die Schaltfläche „Coupon einlösen“ auf der Coupon-Seite an.
Erforderlich, wenn Mitarbeiter in einem Offline-Shop den Coupon einlösen.
onsitePwdstring
Passwort für Vor-Ort-Coupon. Erforderlich bei der Nutzung des Coupons.
memostring
Interne Notiz für Referenzzwecke.
urlstring
Wenn eine URL eingegeben wird, erscheint auf der Coupon-Seite eine Schaltfläche „Zum Einlösen gehen“.
Beim Klicken auf die Schaltfläche oder das Bild wird auf die URL weitergeleitet.
colorstring
Schriftfarbe des Coupons. HEX-Wert eingeben. Beispiel: #4F4F4F
backgroundstring
Hintergrundfarbe des Coupons. HEX-Wert eingeben. Beispiel: #FFFFFF
userIdstring
Wird verwendet, um den Empfänger des Coupons zu verwalten.
Pflichtfeld, wenn die Nutzungsbeschränkung auf 2–5 festgelegt ist. Normalerweise die Login-ID oder der Name des Benutzers.
userNmstring
Name des Coupon-Nutzers. Für interne Verwaltung.
userPhnnostring
Telefonnummer des Coupon-Nutzers. Für interne Verwaltung.
userEmlstring
E-Mail des Coupon-Nutzers. Für interne Verwaltung.
userEtc1string
Zusätzliches internes Verwaltungsfeld.
userEtc2string
Zusätzliches internes Verwaltungsfeld. 
{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

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 string
Antwortwert. Die generierte Coupon-Nummer wird zurückgegeben.
Beispiel: ZJLF0399WQBEQZJM

Wann diese API verwenden

Verwenden Sie diese API, wenn Sie Gutscheine automatisch für Promotionen, Events oder Kampagnen zur Nutzergewinnung erstellen möchten.

Sie eignet sich für verschiedene Marketing-Szenarien wie Registrierungsanreize, gezielte Rabatte und die Steigerung von Conversions aus Werbetraffic.

Konfiguration des Gutschein-Code-Formats

Der Gutscheincode wird über die Parameter cpNo und cpNoDigits gesteuert.
Wird cpNo angegeben, wird dieser Wert als Gutscheincode verwendet. Andernfalls generiert das System automatisch einen Code.

Bei der automatischen Generierung kann die Länge mit cpNoDigits (Standard: 16) festgelegt werden.
Wählen Sie die Länge je nach Anwendungsfall: längere Codes reduzieren das Kollisionsrisiko, kürzere verbessern die Benutzerfreundlichkeit.

Integration von Benutzerdaten

Um einen Gutschein einem bestimmten Benutzer zuzuordnen, setzen Sie den Parameter userId.

Für die Zuordnung zu mehreren Benutzern können die Felder userEml·userPhone·userEtc1·userEtc2 gemeinsam verwendet werden.
Diese Daten werden im Dashboard zur Identifikation und Filterung von Gutscheininhabern genutzt und sind besonders für B2C-Services geeignet, die eine Benutzerzuordnung erfordern.

Anwendungsfälle

  • Automatische Willkommensgutscheine: API-Aufruf bei Registrierung, um personalisierte Gutscheine sofort zu erstellen und bereitzustellen
  • Zeitlich begrenzte Aktionen: Start- und Enddatum festlegen, um Gutscheine nur innerhalb eines definierten Zeitraums gültig zu machen
  • Conversion-Tracking: Gutscheine mit Anzeigenlinks verknüpfen, um Klick → Einlösung → Kauf nachzuverfolgen
  • Gezielte Nutzeransprache: Personalisierte Rabatte basierend auf E-Mail oder Benutzer-ID bereitstellen
  • Gutscheine im Geschäft: onsiteYn auf Y setzen, damit Mitarbeiter Gutscheine per Passwort validieren können

Wichtige Hinweise

  • Für Gutscheine mit Bildern erstellen Sie zuerst eine Gutschein-Gruppe im Dashboard, laden Bilder hoch und geben die Gruppen-ID in grpIdx vor dem API-Aufruf an.
  • Für Webhooks setzen Sie webhookEnablYn auf Y und registrieren die Webhook-URL vorab im Dashboard.
  • Wenn useLimit unbegrenzt ist, wird der Gutschein auch nach Nutzung nicht als vollständig verwendet markiert.
  • Bei Vor-Ort-Gutscheinen ist eine sichere Verwaltung des Validierungspassworts erforderlich.