Online-Stempel-Erstellungs-API

API Version

POST

/api/stamp/v2/create

Request
Response

{
    "cardIdx": 123,
    "storeIdx": 22,
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "activeYn": "Y",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cardIdx integer required: Karten-IDX.
Die Karten-IDX kann auf der Seite „Stempelkarte“ im Dashboard eingesehen werden.
strtYmd date required: Startdatum der Stempelgültigkeit. Beispiel: 2025-01-01
endYmd date required: Ablaufdatum des Stempels. Beispiel: 2025-12-31
Das Ablaufdatum kann bis zu 5 Jahre ab dem heutigen Datum festgelegt werden.
activeYn string
Default:Y
Enum: YN: Aktivierungsstatus des Stempels.
Wenn deaktiviert, können Kunden den Stempel nicht verwenden.
memo string: Interne Notiz zu Referenzzwecken.
userId string: Benutzer-ID.
Wird verwendet, um den Empfänger der Stempelausgabe zu verwalten.
Normalerweise geben Sie die Login-ID eines Website-Mitglieds ein.
Wenn nicht angegeben, wird die Benutzer-ID automatisch vom System generiert.
userNm string: Benutzername. Nur für interne Verwaltung.
userPhnno string: Telefonnummer des Benutzers. Nur für interne Verwaltung.
userEml string: E-Mail-Adresse des Benutzers. Nur für interne Verwaltung.
userEtc1 string: Zusätzliches Feld für die interne Verwaltung.
userEtc2 string: Zusätzliches Feld für die interne Verwaltung.
storeIdx integer: IDX des ausgebenden Geschäfts. Bei Angabe wird die Filiale, zu der das Geschäft gehört, zur ausgebenden Filiale. Eine abweichende Filiale führt zu einem Fehler.

{
    "code": 0,
    "message": "",
    "result": 1347
}

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 integer: Antwortwert. Der generierte Stempel-IDX wird zurückgegeben.
Beispiel: 1347

Prüfung numerischer Parameter

Erhält ein numerischer Parameter einen nicht numerischen Wert oder eine Zahl außerhalb des vom Server verarbeitbaren Bereichs, wird die Anfrage sofort mit 400 (Fehlercode 653) abgelehnt.

In diesem Fall ändern sich Stempeldaten und Sammelhistorie überhaupt nicht, und es entsteht weder ein Ereigniseintrag noch eine Webhook-Zustellung. Eine Fehlerantwort bedeutet, dass nichts gespeichert wurde.

Ausgebende Filiale, ausgebendes Geschäft und Nutzungsbereich

Ausgebende Filiale, Nutzungsbereich und Nutzungsfiliale folgen den auf der Stempelkarte hinterlegten Werten. Nur wenn die Karte das ausgebende Geschäft offen lässt, können Sie es direkt über storeIdx wählen. Ein von der Karte abweichender Wert führt zu 400 (Fehlercode 1221).

Die hier angegebenen Werte sind die bei der Ausgabe gespeicherte Richtlinie. "Wo wurde ausgegeben" (ausgebende Filiale, ausgebendes Geschäft) und "wo kann der Kunde es einlösen" (Nutzungsbereich, Nutzungsfiliale) sind unterschiedliche Konzepte, daher sind die Parameter getrennt.

Parameter	Bedeutung	Beschreibung
`branchIdx`	Ausgebende Filiale	Ohne Angabe gibt die Zentrale aus. Senden Sie `0`, um auf die Zentrale zurückzusetzen.
`storeIdx`	Ausgebendes Geschäft	Bei Angabe wird die Filiale des Geschäfts zur ausgebenden Filiale. Eine abweichende Filiale wird abgelehnt.
`useScope`	Nutzungsbereich	`ALL` (alle Geschäfte) oder `BRANCH` (eine Filiale). Standard ist `ALL`.
`useBranchIdx`	Nutzungsfiliale	Nur bei `useScope=BRANCH` erforderlich. Bei `ALL` immer leer.

Nicht verwendbare Parameter — processStoreIdx (verarbeitendes Geschäft) bezeichnet das Geschäft, in dem eine Prüfung, Einlösung, Gutschrift oder Abbuchung tatsächlich stattgefunden hat, und kann in dieser API nicht verwendet werden. Bei Angabe wird mit 400 (Fehlercode 1227) abgelehnt.

Filial- und Geschäftsfunktionen stehen nur ab dem Business-Tarif zur Verfügung.

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.

Wann diese API verwenden

Diese API wird verwendet, um stempelbasierte Kampagnen und Belohnungssysteme zu erstellen.

Belohnungskampagnen basierend auf Besuchshäufigkeit
Stempelsammelprogramme im stationären Handel
Systeme zur Verifizierung von Nutzeraktivitäten
Erfassung spezifischer Aktionen (Käufe, Teilnahme usw.)

Ideal, um Nutzeraktionen zu erfassen und direkt in Belohnungen umzuwandeln.

Beziehung zwischen Stempelkarten und Stempeln

Eine Stempelkarte definiert die Regeln und das Design der Kampagne, während Stempel die Einheiten sind, die Nutzern zugewiesen werden.

Beim Aufruf der Erstellungs-API wird mit cardIdx festgelegt, welcher Karte der Stempel zugeordnet wird.

Die Card IDX ist im Dashboard verfügbar. Da jede Karte unterschiedliche Bedingungen und Belohnungen hat, ist die Auswahl der richtigen Karte entscheidend.

Struktur und Komponenten der Stempelerstellung

Ein Stempel ist nicht nur ein Datensatz, sondern eine Einheit zur Erfassung von Nutzeraktivitäten.

Wichtige Komponenten:

Karten-ID (cardIdx) : ID der zugehörigen Karte
Gültigkeitszeitraum (strtYmd, endYmd) : Zeitraum, in dem der Stempel gültig ist
Status (activeYn) : Gibt an, ob der Stempel aktiv und nutzbar ist
Nutzerinformationen (userId, userNm, userEmail, etc.) : Zielnutzer
Zusätzliche Felder (memo, userEtc1, userEtc2) : Individuelle Daten

Ermöglicht eine präzise und personalisierte Verwaltung von Nutzeraktivitäten.

Integration von Nutzerdaten

Das Feld userId dient zur Identifikation und Verwaltung des Empfängers des Stempels.

In der Regel wird die interne Benutzer-ID verwendet. Wird kein Wert angegeben, erstellt das System automatisch eine ID.

Durch das Hinzufügen von userNm, userPhnno und userEml können Kontaktdaten gespeichert und die Stempelaktivität pro Nutzer im Dashboard verwaltet werden.

Anwendungsfälle

Willkommensstempel bei Registrierung: Automatische Vergabe eines Stempels nach erfolgreicher Anmeldung durch API-Aufruf
Automatische Kaufbelohnung: Aufruf der API nach Zahlung, um Stempel basierend auf der Anzahl der Käufe zu vergeben
Zeitlich begrenzte Kampagnen: Ausstellung von Stempeln mit definierter Gültigkeit über strtYmd·endYmd
Erfassung von Event-Teilnahmen: Vergabe von Stempeln zur Nachverfolgung der Teilnahmehistorie
Belohnungskampagnen: Vergabe von Gutscheinen oder Vorteilen basierend auf gesammelten Stempeln

Unterschied zur Coupon-API

Die Coupon-API und die Stempel-API werden beide im Marketing eingesetzt, verfolgen jedoch unterschiedliche Ziele und Einsatzweisen.

Die Coupon-API ist auf Conversion ausgerichtet und fördert sofortige Käufe durch Rabatte.
Die Stempel-API konzentriert sich auf Retention, indem sie Nutzerverhalten erfasst und wiederkehrende Interaktionen fördert.

1. Zielsetzung

Coupon-API → Rabatt → Kaufanreiz (Conversion)
Stempel-API → Verhaltensdaten → Wiederkehr fördern (Retention)

Coupons eignen sich für kurzfristige Umsatzsteigerung, während Stempel die langfristige Kundenbindung stärken.

2. Einsatzzeitpunkt

Coupon → Vor oder während des Bezahlvorgangs
Stempel → Bei Aktionen (Besuch, Teilnahme etc.)

Coupons treiben den sofortigen Kauf, während Stempel zukünftige Aktionen anstoßen.

3. Datenstruktur

Coupons sind ereignisbasiert.

Einmalig oder begrenzt nutzbar
Fokus auf Rabattwert oder -satz
Wird bei Nutzung verbraucht oder aktualisiert

Stempel sind kumulativ.

Mehrfach vergebbar
Nutzerbezogene Akkumulation
Belohnung bei Zielerreichung

Kurz gesagt: Coupons sind Einmal-Trigger, Stempel sind kumulative Zustandsdaten.

4. Marketingstrategie

Coupon-basierte Strategie:

Neukundengewinnung
Steigerung der Conversion-Rate
Förderung bestimmter Produkte

Stempel-basierte Strategie:

Wiederkehr fördern
Kundenloyalität stärken
Langfristige Kampagnen

5. Kombination

In der Praxis werden beide APIs häufig kombiniert.

Beispiel:

Stempel sammeln (z. B. 10 Besuche)
Automatische Coupon-Ausgabe bei Zielerreichung
Kaufanreiz durch Coupon-Nutzung

Dies verbindet Engagement → Retention → Conversion in einem durchgängigen Ablauf.

Wichtige Hinweise

cardIdx muss eine gültige Karten-ID sein
Definieren Sie klare Regeln zur Vermeidung doppelter Stempel pro Nutzer
Falsch konfigurierte Zeiträume können die Kampagnenleistung beeinträchtigen

Stempel-Erstellungs-API (v2)