ガイド
バウチャー導入ガイド
テンプレート審査から発行・利用処理まで、バウチャー機能はウォレットやプラットフォーム販売から独立しています。
発行と履行は開発者の責任です
プラットフォームはテンプレートと状態を管理し、冪等な発行、検証、利用処理、利用取消 API を提供します。特典内容、ユーザー承認、利用条件、商品・サービスの履行は開発者が担います。プラットフォームは販売や代金回収を行いません。
始める前に
- IMアカウントで開発者コンソールにサインインします。
- ボットアプリケーションを作成し、承認とアクティベーションを待ちます。
- 一度限りのsbot_トークンを保存し、必要なバウチャースコープを確認します。
1. バウチャーテンプレートを作成する
テンプレートは名前、利益、有効期限、および使用ルールを定義します。テンプレート管理にはアカウントJWTを使用し、Bot Tokenは使用しません。
- コンソールのボット詳細ページからバウチャーを開きます。
- ドラフトを作成し、その表示内容を確認して提出します。
- 承認されたテンプレートのみがライブ発行に使用できます。
2. 特定のユーザーに発行する
あなたのサーバーはBot Tokenを使用して発行APIを呼び出し、recipient_user_idを通じてIMユーザーを選択します。
curl -X POST "$API/bots/vouchers/issue" \
-H "Authorization: Bearer $BOT_TOKEN" \
-H "Idempotency-Key: order_20260903_001" \
-H "Content-Type: application/json" \
-d '{
"template_id": "YOUR_TEMPLATE_ID",
"recipient_user_id": "CUSTOMER_USER_ID"
}'各ビジネス発行に対してユニークなIdempotency-Keyを使用します。ネットワークの再試行時に再利用して重複を避けます。
3. バウチャーを提示する
発行後、ユーザーはサポートされているチャットや訪問者体験でバウチャーを表示できます。
- 紛らわしい文字を除いた 6 桁の英数字コードです。
- 店頭確認に使用できる QR 認証情報です。
- 訪問者は表示されたバウチャーを画像として保存できます。
4. 検証、引き換え、逆転
マーチャントサーバーが最初に検証し、その後ユニークな冪等性キーで引き換えます。誤った引き換えを修正するためにのみ逆転を使用してください。
POST /api/v1/bots/vouchers/verify
POST /api/v1/bots/vouchers/redeem
POST /api/v1/bots/vouchers/reverse検証は読み取り専用です。引き換えは状態を原子的に変更し、クライアントから直接呼び出してはいけません。
セキュリティとビジネスルール
- アカウントのJWTとBot Tokenは信頼できるサーバーに保管し、ウェブやアプリのバンドルには決して保存しないでください。
- 両方のコードとQRデータを引き換え資格情報として扱い、無関係な第三者に公開しないでください。
- バウチャーに有効性、範囲、制限、およびカスタマーサポートの連絡先詳細を明確に表示してください。