オンラインスタンプ作成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: カードIDX。
カードIDXはダッシュボードの「スタンプカード」ページで確認できます。
strtYmd date required: スタンプの有効開始日。例: 2025-01-01
endYmd date required: スタンプの有効期限日。例: 2025-12-31
有効期限は本日から最長5年まで設定できます。
activeYn string
Default:Y
Enum: YN: スタンプの有効状態。
無効化されている場合、顧客はスタンプを利用できません。
memo string: 内部参照用メモ。
userId string: ユーザーID。
スタンプ発行対象者の管理に使用します。
通常は、ウェブサイト会員のログインIDを入力します。
設定されていない場合、システムによって自動的にユーザーIDが生成されます。
userNm string: ユーザー名。内部管理用。
userPhnno string: ユーザー連絡先。内部管理用。
userEml string: ユーザーのメールアドレス。内部管理用。
userEtc1 string: 追加の内部管理用フィールド。
userEtc2 string: 追加の内部管理用フィールド。
storeIdx integer: 発行店舗IDX。指定すると、その店舗が属する支店が発行支店になります。異なる支店を一緒に送るとエラーになります。

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

Response Parameters

code integer: 応答コード: 0 = 成功、それ以外の値 = エラー
message string: 応答メッセージです。応答コードが0でない場合、エラーメッセージが返されます。
result integer: レスポンス値です。生成されたスタンプIDXが返されます。
例：1347

数値パラメータの検証

数値で受け取るパラメータに数値以外の値や、サーバーが処理できる範囲を超える数値を送ると、リクエストは400(エラーコード653)で直ちに拒否されます。

この場合、スタンプ情報と付与履歴は一切変更されず、イベント記録やWebhook送信も発生しません。失敗レスポンスを受け取った場合は何も保存されていない状態です。

発行支店・店舗と利用可能範囲

発行支店・利用可能範囲・利用可能支店はスタンプカードに設定された値に従います。カードが発行店舗を空けている場合にのみstoreIdxで直接選択できます。カード設定と異なる値を送ると400(エラーコード1221)で拒否されます。

ここで指定する値は発行時点で保存されるポリシーです。「どこで発行されたか」(発行支店・発行店舗)と「お客様がどこで利用できるか」(利用可能範囲・利用可能支店)は異なる概念のため、パラメータも分かれています。

パラメータ	意味	説明
`branchIdx`	発行支店	省略すると本社発行になります。`0`を送ると本社に戻します。
`storeIdx`	発行店舗	指定すると、その店舗が属する支店が発行支店になります。異なる支店を一緒に送ると拒否されます。
`useScope`	利用可能範囲	`ALL`(すべての店舗)または`BRANCH`(特定の支店)。省略時は`ALL`です。
`useBranchIdx`	利用可能支店	`useScope=BRANCH`の場合のみ必要です。`ALL`のときは常に空です。

使用できないパラメータ — processStoreIdx(処理店舗)は検証・利用・付与・差し引きが実際に行われた店舗を指す値のため、このAPIでは使用できません。一緒に送ると400(エラーコード1227)で拒否されます。

支店・店舗機能はビジネスプラン以上でのみご利用いただけます。

Idempotency-Key

ネットワークエラーで応答を受け取れなかったときに安全に再試行するには、Idempotency-Keyヘッダーにリクエストごとに一意の値を入れて送信します。本文のrequestIdでも送れますが、両方を送って値が異なる場合は拒否されます。使用できる形式は英数字と. _ : -を組み合わせた8〜64文字です。

同じkeyで同じリクエストを再送すると、再処理せずに最初の結果をそのまま返します。 重複して処理されることはなく、Webhookも再送されません。

同じkeyは同じ論理操作の再試行にのみ使用してください。異なる操作には必ず新しいkeyを使用してください。同じkeyを異なるリクエスト内容や別の操作に使用すると409で拒否される場合があります。

このAPIを利用する場面

スタンプ型キャンペーンやリワードシステムの構築に使用します。

来店回数に応じたリワードキャンペーン
店舗でのスタンプ収集プログラム
ユーザー行動の認証システム
特定アクション（購入・参加など）の記録

ユーザーの行動を記録し、リワードへとつなげる用途に最適です。

スタンプカードとスタンプの関係

スタンプカードはキャンペーンのルールとデザインを定義し、スタンプはユーザーに付与される実際の単位です。

作成APIを呼び出す際に cardIdx を指定し、どのカードにスタンプを付与するかを決定します。

カードIDXはダッシュボードで確認できます。カードごとに条件やリワードが異なるため、正しいカードを選択することが重要です。

スタンプ生成の仕組みと構成要素

スタンプは単なるデータではなく、ユーザー行動を記録する単位です。

主な構成要素:

カード識別子（cardIdx）: スタンプが属するカードID
有効期間（strtYmd、endYmd）: スタンプの有効期間
ステータス（activeYn）: 利用可能かどうかを示す状態
ユーザー情報（userId、userNm、userEmail など）: 対象ユーザー
追加情報（memo、userEtc1、userEtc2）: カスタムデータ

これにより、ユーザー行動を個別に追跡・管理できます。

ユーザー情報の連携

userId はスタンプ付与対象の識別と管理に使用されます。

通常は自社の会員IDを指定します。未指定の場合はシステムによって自動生成されます。

userNm、userPhnno、userEml などを設定することで、連絡先情報を保持し、ダッシュボード上でユーザーごとのスタンプ状況を管理できます。

活用例

新規登録時のウェルカムスタンプ: 会員登録完了時にAPIを呼び出し、自動でスタンプを付与
購入連動の自動付与: 決済完了時にスタンプ生成APIを呼び出し、購入回数に応じて付与
期間限定キャンペーン: strtYmd・endYmd を使用して有効期間を限定したスタンプを発行
イベント参加履歴の管理: イベント参加時にスタンプを付与し、履歴を記録
リワードキャンペーン運用: 累計スタンプ数に応じてクーポンや特典を付与

クーポンAPIとの違い

クーポンAPIとスタンプAPIはどちらもマーケティングに活用されますが、目的と使い方は明確に異なります。

クーポンAPIは割引によって即時購入を促すコンバージョン重視のツールです。
一方、スタンプAPIはユーザー行動を記録し、継続的な利用を促すリテンション重視のツールです。

1. 目的

クーポンAPI → 割引提供 → 購入促進（Conversion）
スタンプAPI → 行動記録 → 再訪促進（Retention）

クーポンは短期的な売上向上に効果的であり、スタンプは長期的な利用促進に適しています。

2. 利用タイミング

クーポン → 決済前または決済時に使用
スタンプ → 訪問や参加などの行動時に付与

クーポンは「今すぐ購入させる仕組み」、スタンプは「次の行動を促す仕組み」です。

3. データ構造

クーポンは単発イベント型です。

単回または回数制限あり
割引額・割引率が中心
使用時に即時消費または状態更新

スタンプは累積型です。

繰り返し付与可能
ユーザー単位で累積管理
条件達成時に報酬を付与

つまり、クーポンは単発トリガー、スタンプは累積データです。

4. マーケティング戦略

クーポン戦略:

新規ユーザー獲得
コンバージョン率向上
特定商品の販売促進

スタンプ戦略:

再訪促進
顧客ロイヤルティ向上
長期キャンペーン運用

5. 併用パターン

実際のサービスでは、両APIを組み合わせて利用するケースが一般的です。

例:

スタンプを蓄積（例: 来店10回）
条件達成でクーポンを自動発行
クーポン利用で購入を促進

この構成により、 参加 → 継続 → 購入 を一連の流れとして設計できます。

利用時の注意点

cardIdx には有効なカードIDを必ず指定してください
同一ユーザーへの重複付与ルールを事前に定義してください
有効期間の設定ミスはキャンペーン運用に影響します

スタンプ作成API (v2)