プロジェクトは、SDGs（持続可能な開発目標）の17の目標の中からテーマを選び、その達成を目指して取り組む活動です。法人・個人を問わず、誰でもホストとして自由にプロジェクトを立ち上げ、登録できます。

※各種イベントの開催や経済活動等による環境への影響をオフセットする目的で、それらのイベントをプロジェクトとして登録することも可能です。

以下では、プロジェクト（SDGs活動）を本プログラムに登録する手順をご案内します。

現行のホスト導線には、LPのAIクイック登録から下書きを作る方法と、新規プロジェクト登録フォームを直接入力する方法があります。どちらを選んでも最終的には同じ確認・公開フローに進みます。

1. 短時間で始める場合は AIクイック登録 を利用します。直接入力したい場合は 新規プロジェクト登録 を開きます。
2. フォームまたはAIが生成した下書きの内容を確認し、以下の内容に従って各項目を入力・更新します。
1. 基本情報
• プロジェクト名: 任意のプロジェクト名称を入力してください。
• シンボル: プロジェクトを識別するためのユニークなコード。半角英字（大文字）4桁で設定してください。
• SDGs目標: プロジェクトのSDGs目標を選択してください。プロジェクトの活動目的に即したSDGs目標である必要があります。
• ターゲット: プロジェクト活動における主なターゲット、または関連するターゲットを選択してください。
• 活動地域: 活動エリア（都道府県 / 市区町村）を設定します。検索ページの地域条件や詳細ページの「活動地域」表示に利用されます。未設定でも登録できますが、公開時の見つけやすさ向上のため設定を推奨します。
• プロジェクト概要: プロジェクトの目的と活動内容の要約を記載してください。
• プロジェクト詳細: プロジェクトの具体的な計画、活動内容、対象者、期待する効果など、詳細な活動情報を記載します。
• 紹介動画URL: 任意で YouTube の紹介動画URLを掲載できます。公開 / 限定公開どちらの共有URLにも対応します。
2. 特典情報
• 特典のタイプ: プロジェクトで提供する特典のタイプを「固定」または「変動」から選択します。特典を設定しない場合は「特典なし」を選択してください。

プロジェクト特典には、「固定」と「変動」の二つのカテゴリーがあります。

「固定特典」は、特定のコンサートチケットや期間限定のサービス券など、目的と内容が明確でプロジェクトの進捗や状況に左右されない特典の場合に選択します。

一方、プロジェクトの進展に応じて特典の内容を柔軟に変更したい場合は、「変動特典」を選択します。これには、プロジェクトの成功に伴う特典の拡充や、不測の事態による特典の廃止が含まれます。

※固定特典の利用例:（一回限りの使い切り特典や、継続的な会員資格を付与する特典など））

• 会員証（メンバーズ会員カード機能等）
• 予約券
• コンサートやイベント等のチケット

※変動特典の利用例:（主に将来にわたるプロジェクトトークンの価値向上に取り組みたい場合など）

• 変動制の割引券・クーポン
• プロジェクトの進捗や業績に応じて特典内容を拡充または縮小する可能性がある場合
• 季節や期間、その他の条件によって特典内容を変更したい場合
• 特典名: 特典を識別する名称を入力してください。
• 必要PT数: 特典のミントに必要なエレメント数を設定します。エレメントをミントすると、同数のプロジェクトトークンが発行され、サポーターに付与されます。
• 発行上限: 特典を紐づけるプロジェクトトークンの最大発行数を設定することで、当該特典の提供数を制限することができます。上限を設けない場合は空欄としてください。
重要
特典を設定した場合、サポーターはミント時に必ず特典を選択する必要があります。

必要PT数が 2以上の場合、発行されたプロジェクトトークンは不可逆的にグループ化され、グループトークンとして扱われます。

特典が未設定のプロジェクトでは、1エレメントごとにクラシックトークン※が発行されます。

クラシックトークンの保有数に応じて特典や優待を提供する場合は、「プロジェクト詳細」に具体的な提供条件を明記してください。

「必要PT数」以外の提供条件（例：特定のトークンID、ミント期間など）を設ける場合は、当該条件を「特典内容」または「プロジェクト詳細」に必ず明記してください。

※クラシックトークンは、特典情報を持たないベーシックなプロジェクトトークンです。特典情報を持たないため、必要PT数や発行上限は設定できず、シングルトークンとして扱われます。

• 特典内容: 特典の内容を詳しく説明します。「必要PT数」以外の提供条件を設定する場合は、その詳細も必ず明記してください。
• 提供方法: 特典の提供方法と手順を記載します。

特典の提供方法については、内容に応じて受渡しや利用方法を明記してください。

例えば、来店型の特典として物品やサービスを提供する場合は、マイコレクションページから表示できる トークンのQRコード※や対象のトークンリスト画面を来店時にスタッフに提示する方法などを記載します。

また、チケットなどの入場券の場合は、ゲートで提示したり、専用のスキャナーにかざしたりすることが一般的です。

一方、非来店型の場合は、サスプラカード番号と登録メールアドレスへ送られるワンタイムパスを使ってオンラインで 特典を利用できるなど、実際に特典を受けとる方法を具体的に明記すると良いでしょう。

各種プロジェクトの内容や特典の特性に応じて、対応可能な提供方法を設定してください。

※QRコードにはプロジェクトトークンのデータが含まれています。 現行環境では、SustinaPlus公式アプリ とホスト向け真正確認API（/host/verify_nft、/host/verify_nft_manual）が提供されています。 ホストは、SustinaPlus公式アプリの「クイックスキャン > ホスト QRスキャン」から簡易運用することも、独自のPOSやアプリケーションにAPIを統合することもできます。

3. ミント制限
• PT発行可能総数: PT発行可能総数に上限を設ける場合は、その最大数を設定してください。
  この設定は、プロジェクト全体のPT発行数を制限したい場合に使用します。発行数が上限に達すると、特典ごとの発行上限に関係なく、新規ミントができなくなります。
  なお、この設定は登録後も変更可能で、プロジェクトの進捗に応じて上限を引き上げたり、撤廃することができます。
• 有効期間: 対象プロジェクトでミントの受付期間を設定したい場合に使用します。この設定は登録後に変更できません。
  例えば、期間限定プロジェクトでは、開始日と終了日を設定することで、ミントできる期間を事前に指定できます。
  また、開始日だけを設定すれば、プロジェクトの開始予約が可能です。終了日のみを設定して、ミント期限を設けることもできます。
4. ロゴ情報
• プロジェクト・ロゴ: プロジェクトを象徴するロゴ画像をアップロードします。この画像は発行されるPTのロゴとして使用されます。
• アイキャッチ画像: プロジェクトの雰囲気を伝える画像を設定します。この画像はプロジェクト詳細ページの概要欄に表示されます。
• バナー画像: プロジェクトを宣伝するためのバナー画像を設定します。
5. ホスト情報
• プロジェクトURL: プロジェクトの公式サイトやホストの詳細情報が確認できるURLを設定してください。これにより、ユーザーは詳細ページからプロジェクトの公式情報にアクセスできます。
• 外部リンク: プロジェクトに関連するSNSリンク等を最大3つまで設定できます。
3. 入力が完了したら、「確認ページへ進む」ボタンを押してください。
4. 確認ページで入力内容を確認し、必要に応じて「修正」ボタンで入力内容を修正します。
5. 現行の確認ページでは、すぐに公開する場合は「登録（公開）」、あとで公開する場合は「仮登録」を選択できます。
6. 「仮登録」を選んだプロジェクトは非公開のまま保存され、詳細ページまたは「マイプロジェクト」から編集・再開できます。公開準備が整ったら詳細ページの「公開する」ボタンで公開します。

登録後のプロジェクトは、「マイプロジェクト」ページと各プロジェクトの詳細ページから管理できます。現行UIでは、編集、公開/非公開、休止/再開、フィード確認、ホルダー管理、お知らせ配信などをここから行います。

1. プロジェクトの編集
   1. アクセス方法： ヘッダーの「マイページ」からマイプロジェクトを選択します。
   2. 操作手順：
      1. マイプロジェクトページにアクセスすると、登録済みのプロジェクト一覧が表示されます。
      2. 編集したいプロジェクトのカードにある「編集」ボタンをクリックします。
      3. プロジェクト編集ページへ遷移後、既存の登録情報が入力されたフォームが表示されます。
      4. 編集を希望する項目の内容を更新します。編集しない項目は変更不要です。
      5. 全項目の編集が完了したら、ページ下部にある「プロジェクト更新」ボタンをクリックします。
      6. 確認メッセージが表示されたら、「OK」を選択して変更を確定します。

   更新後、詳細ページが表示され、「プロジェクトが更新されました」とのメッセージが表示されれば、更新は成功です。エラーが発生した場合は、エラーメッセージに従って、必要な修正を行ってください。

2. 公開・非公開の切り替え
   1. 公開方法： 仮登録したプロジェクトは、詳細ページ右上の「公開する」ボタンから公開できます。公開するとホームや検索結果に表示され、ミント受付が開始されます。
   2. 非公開化： すでに公開中のプロジェクトは、同じ位置の「非公開にする」ボタンから公開状態を解除できます。非公開にしてもプロジェクト自体は削除されず、再編集や再公開が可能です。
3. プロジェクトの休止・再開

   本機能は、やむを得ない理由によりミントの受付を停止せざるを得ない状況になった場合にミントの受付を手動で休止および再開するための機能です。休止および再開の際は、サポーターが変更の理由と状況を適時に把握できるよう、公式サイトやSNSを通じて適切に情報を提供することが求められます。

   1. 休止の設定：
      1. 「マイプロジェクト」ページから、休止したいプロジェクトのトグルスイッチ（稼働中）を操作すると、プロジェクトは非アクティブ状態（休止中）に切り替わります。
      2. トグルスイッチを「非アクティブ」に切り替えると、プロジェクトは休止中と表示され、新規ミントの受付が停止されます。
   2. 再開の設定：
      1. 再開したいプロジェクトのトグルスイッチ（休止中）を操作します。
      2. トグルスイッチを「アクティブ」に切り替えると、プロジェクトが再び稼働中と表示され、新規のミント受付が再開されます。
4. フィード確認と進捗発信
   1. アクセス方法： マイプロジェクトの各カードにある「フィード」ボタン、またはヘッダーの「SNS」から対象プロジェクトの投稿スレッドへ進みます。
   2. 活用方法： 公開後の進捗報告、告知、サポーターとのコメント/返信の確認に利用できます。公開中プロジェクトの活動状況を継続的に発信する導線として活用してください。
5. ホルダー管理
   1. アクセス方法： マイプロジェクトの各カードにある「ホルダー管理」ボタンをクリックします。
   2. 確認できる内容： 発行済みPTを NFT 単位で一覧表示し、現在の保有ユーザー、ミント日時、取得日時、特典名、親子トークン区分、利用回数を確認できます。
   3. 補助機能： ユーザー別表示への切り替えと、CSVダウンロードが利用できます。運用報告や来場管理、保有状況の確認に利用してください。
6. お知らせ配信
   1. アクセス方法： マイプロジェクトの各カードにある「お知らせ配信」ボタンから履歴画面を開き、「新規作成」を押します。
   2. 配信対象： 対象プロジェクトの現ホルダーにメールを送信できます。配信停止設定済みユーザーは自動で除外されます。
   3. 補助機能： まず自分宛に送る「テスト配信」、配信履歴の確認、配信ログCSVのダウンロードに対応しています。
7. 更新履歴と削除
   1. 更新履歴： プロジェクト詳細ページ下部の「更新履歴」から、主な変更内容を確認できます。
   2. 削除： プロジェクト詳細ページ下部の「プロジェクトを削除」から削除できます。この操作は元に戻せないため、公開状態や保有者状況を確認した上で実行してください。

8. プロジェクトランク:

   プロジェクトランクは、プロジェクトトークン（PT）の発行数に基づいて設定・公開されます。ランクが上がると、プロジェクトのミント報酬やロイヤリティ（二次流通報酬率）が優遇されます。

   ランク	PT発行数の条件
   ダイアモンド	1,000,000以上
   プラチナ	100,000以上、1,000,000未満
   ゴールド	10,000以上、100,000未満
   シルバー	1,000以上、10,000未満
   ブロンズ	100以上、1,000未満
   ウッド	100未満

プロジェクト報酬は、プロジェクトの推進と持続的発展を支えるため、サポーターの活動やプロジェクトトークンの取引に応じてホストに支払われる報酬です。プロジェクト報酬は、「ミント報酬」と「ロイヤリティ」の2つに分類されます。

1. 報酬の確認方法
   1. アクセス方法： ヘッダーの「マイページ」からマイプロジェクトを選択します。
   2. マイプロジェクトページの「プロジェクト報酬」タブをクリックします。
   3. 当該ページでは、ミントおよびロイヤリティのそれぞれの報酬を確認でき、対象年月やシンボルで絞り込みが可能です。
   4. ページ下部の報酬明細テーブルにて、ミントとロイヤリティのタブ分けされた表示により、各ミントおよびPTの取引ごとの詳細を確認できます。
2. ミント報酬
   1. ミント報酬は、サポーターがプロジェクトをミントした際にホストへ支払われるインセンティブで、ミント時のプロジェクトランクに基づいて算定されます。
   2. 報酬の算定と支払い：
      1. サポーターがミントを実行すると、プログラムがミント実行時点のプロジェクトランクを確認します。
      2. 該当ランクの報酬額（法定通貨「円」）が算定され、報酬として JPYC で支払われます。
      3. 算定されたミント報酬はホストがプロジェクト登録時に設定したウォレットアドレスに送金されます。
   3. 報酬額：

      各プロジェクトランクに対応するミント報酬額（1PTあたりの金額）は以下の通りです。

      ランク	報酬額 (単位: 円)
      ダイアモンド	380
      プラチナ	375
      ゴールド	365
      シルバー	350
      ブロンズ	330
      ウッド	300

3. ロイヤリティ
   1. ロイヤリティは、プロジェクトトークンがマーケットプレイスで取引された際に、取引価格とプロジェクトランクに応じたロイヤリティ率を基に算定されます。
   2. ロイヤリティの算定と支払い：
      1. プロジェクトトークンが取引された際、取引価格に基づき取引成立時点のプロジェクトランクに応じたロイヤリティ率が適用されます。
      2. 適用されたロイヤリティ率に基づきロイヤリティ額が算定され、JPYC で支払われます。
      3. 算定されたロイヤリティはホストがプロジェクト登録時に設定したウォレットアドレスに送金されます。
   3. ロイヤリティ率：

      各プロジェクトランクに対応するロイヤリティ率は、次の通りです。

      ランク	ロイヤリティ率 (%)
      ダイアモンド	8.25%
      プラチナ	8.0%
      ゴールド	7.75%
      シルバー	7.5%
      ブロンズ	7.25%
      ウッド	7.0%

本APIは、ホストがプロジェクト特典を提供する際に、ユーザーから提示されたプロジェクトトークン（NFT）のQRコード（またはオンライン入力）を通じて、対象NFTの所有権および関連情報をブロックチェーンにリアルタイムで照会する機能を提供します。 これにより、ホストは既存のPOS（会計）システムや独自アプリケーションを通じて、NFTの所有確認や特典内容の照会を安全かつ迅速に行うことができ、特典提供時の認証業務を効率化できます。
以下では、APIキーの取得方法や具体的な呼び出し手順について解説します。

1. APIキーの取得
   1. まず、マイプロジェクトページにアクセスします。
   2. プロジェクト一覧が表示されたら、APIキーを確認したいプロジェクトカードの「詳細」ボタンをクリックします。
   3. 管理者向けのプロジェクト詳細ページが表示され、その中にAPIキーが表示されます。
      
      例） APIキー: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f
   4. APIキーの右側に表示されているコピーアイコンをクリックすると、クリップボードにコピーされます。コピーしたAPIキーは、外部に漏洩しないよう大切に管理してください。

   ※ APIキーはプロジェクトごとに発行されており、複数のプロジェクトを運営する場合、それぞれ異なるAPIキーが割り当てられます。

   APIキー表示例（マイプロジェクト/詳細ページ内）▼

   
2. APIのエンドポイント

   本サービスのAPIは、以下のエンドポイントを通じてNFTの真正確認を行うことができます。

   Base URL

   エンドポイント詳細

   エンドポイント	HTTPメソッド	用途	主パラメータ
   /host/verify_nft	POST	QR 方式（店頭スキャン）	encoded_data
   /host/verify_nft_manual	POST	オンライン方式	token_id, access_code

   リクエストヘッダー

   キー	値	説明
   X-API-KEY	プロジェクト専用のAPIキー	APIキーの認証に使用されます。 必須項目
   Content-Type	application/json	リクエストデータ形式。 必須項目

   リクエストボディ

   1. QR方式

   パラメータ名	型	必須	説明
   encoded_data	string (Base64)	必須	QRコード情報をBase64エンコードした文字列
   action	string	任意	使用カウントを操作したい場合に指定可能なパラメータ。 use: usage_count を +1 cancel: usage_count を -1 (0未満にはならない) 省略: カウント操作なし
   reward_id	integer	任意	特典コードを指定すると、それ以外のNFT QRをブロックします。 不一致の場合は 409 Conflict を返却します。 未指定の場合はこの検証をスキップします。

   ２. オンライン方式

   パラメータ名	型	必須	説明
   token_id	integer	必須	対象NFTのToken ID
   access_code	string	必須	対象NFTに設定したアクセスコード
   action	string	任意	使用カウントを操作したい場合に指定可能なパラメータ。 use: usage_count を +1 cancel: usage_count を -1 (0未満にはならない) 省略: カウント操作なし
   reward_id	integer	任意	特典コードを指定すると、それ以外のNFT QRをブロックします。 不一致の場合は 409 Conflict を返却します。 未指定の場合はこの検証をスキップします。

   レスポンスボディ

   キー	型	説明
   success	boolean	API呼び出しが成功したかどうかを示します。
   isAuthentic	boolean	QRコードの署名検証・NFTの所有確認・有効期限チェックなどを通じて、NFTが正当なものであると総合的に判断された場合に true になります。
   message	string	処理結果やエラーメッセージ
   token_id ※1	integer	NFTのトークンID
   project_code	string	プロジェクトコード
   project_name	string	プロジェクト名
   benefit_name	string	特典名
   action	string	実行されたアクション（use / cancel / null）
   usage_count	integer	当該 NFT がこれまでに利用された回数。 action="use" で +1、"cancel" で −1（下限0）。 カウント操作なしの場合は既存回数を返します。
   remaining_token	integer / null	その NFT であと何回特典を利用できるか。 null は「上限なし」を示します。
   last_used_at	string	最終利用または取消処理の日時（ISO 8601形式）。 action に "use" または "cancel" を指定した場合にのみ更新されます。 それ以外の場合は null または含まれない可能性があります。
   token_ids ※2	array<integer>	グループ検証時に対象となるすべてのトークンIDのリスト。
   representative_token_id ※2	integer	グループ検証時の代表トークンID（最小のトークンID）。 このトークンがusage_countの記録対象になります。

   ※1 token_id はシングルトークン（クラシックトークン）検証時にのみ返却されます。
   ※2 token_idsおよびrepresentative_token_idは、クラシックトークン（シングルトークン）検証では返却されません。

   レスポンス例（成功時 - シングルトークン）

   
                               {
                                   "success": true,
                                   "isAuthentic": true,
                                   "message": "Single token verified successfully",
                                   "token_id": 101,
                                   "project_code": "ABCD",
                                   "project_name": "プロジェクト名",
                                   "benefit_name": "特典名",
                                   "action": "use",
                                   "usage_count": 3,
                                   "last_used_at": "2025-06-11T12:34:56+09:00"
                               }

   レスポンス例（成功時 - グループトークン）

   
                               {
                                   "success": true,
                                   "isAuthentic": true,
                                   "message": "Group tokens verified successfully",
                                   "token_ids": [101, 102],
                                   "representative_token_id": 101,
                                   "project_code": "ABC123",
                                   "project_name": "プロジェクト名",
                                   "benefit_name": "特典名",
                                   "action": "use",
                                   "usage_count": 5,
                                   "last_used_at": "2025-06-11T15:30:00+09:00"
                               }
                               

   レスポンス例（否認時 - 所有権確認失敗）

   
                               {
                                   "success": false,
                                   "isAuthentic": false,
                                   "message": "On-chain balance check failed"
                               }
                               

   ※ オンライン入力方式でも、指定した token_id が バンドル (グループ) に属している場合は、 レスポンスは上記「グループトークン成功例」と同一構造 （token_ids, representative_token_id などを含む） で返却されます。

3. APIの呼び出し方

   API を呼び出す際は、取得した X-API-KEY を リクエストヘッダーに必ず含めてください。
   ① QR スキャン方式 (/verify_nft) と ② オンライン入力方式 (/verify_nft_manual) は ペイロードが異なります。下記サンプルを参考に実装してください。

   ① QR スキャン方式  —  Python

   
                               import requests
   
                               BASE_URL = "https://sustina-plus.jp/api/v1/external/host"
                               API_KEY  = "あなたのAPIキー"
   
                               headers  = {
                                   "X-API-KEY": API_KEY,
                                   "Content-Type": "application/json"
                               }
   
                               # QRコードを Base64 化して encoded_data にセット
                               payload = {
                                   "encoded_data": "",
                                   "action": "use"     # +1 → "use" / −1 → "cancel" / 省略 → カウント変更なし
                               }
   
                               res = requests.post(f"{BASE_URL}/verify_nft", headers=headers, json=payload)
                               print(res.json())
                                   

   ① QR スキャン方式  —  JavaScript (Fetch)

   
                               const BASE_URL = "https://sustina-plus.jp/api/v1/external/host";
                               const API_KEY  = "あなたのAPIキー";
   
                               const payload = {
                               encoded_data: "",
                               action: "use"   // +1: use / −1: cancel
                               };
   
                               fetch(`${BASE_URL}/verify_nft`, {
                               method: "POST",
                               headers: {
                                   "X-API-KEY": API_KEY,
                                   "Content-Type": "application/json"
                               },
                               body: JSON.stringify(payload)
                               })
                               .then(r => (r.ok ? r.json() : Promise.reject(r)))
                               .then(data => console.log("NFT真正確認結果:", data))
                               .catch(err  => console.error("API エラー:", err));
                                   

   ② オンライン入力方式  —  Python

   
                               import requests
   
                               BASE_URL = "https://sustina-plus.jp/api/v1/external/host"
                               API_KEY  = "あなたのAPIキー"
   
                               headers  = {
                                   "X-API-KEY": API_KEY,
                                   "Content-Type": "application/json"
                               }
   
                               payload = {
                                   "token_id":    123,      # 対象 NFT の Token ID
                                   "access_code": "Ab12Cd34", # 英数字を含む 8 文字以上
                                   "action":      "use"
                               }
   
                               res = requests.post(f"{BASE_URL}/verify_nft_manual",
                                                   headers=headers, json=payload)
                               print(res.json())
                                   

   ② オンライン入力方式  —  JavaScript (Fetch)

   
                               const BASE_URL = "https://sustina-plus.jp/api/v1/external/host";
                               const API_KEY  = "あなたのAPIキー";
   
                               const payload = {
                               token_id:    123,
                               access_code: "Ab12Cd34",
                               action:      "use"
                               };
   
                               fetch(`${BASE_URL}/verify_nft_manual`, {
                               method: "POST",
                               headers: {
                                   "X-API-KEY": API_KEY,
                                   "Content-Type": "application/json"
                               },
                               body: JSON.stringify(payload)
                               })
                               .then(r => (r.ok ? r.json() : Promise.reject(r)))
                               .then(data => console.log("NFT真正確認結果:", data))
                               .catch(err  => console.error("API エラー:", err));
                                   

   補足：
   ・QR 方式では encoded_data のみ必須です。
   ・オンライン方式では token_id とaccess_code が必須で、ウォレットアドレスはサーバ側で自動照合されます。
   ・プロジェクトに複数の特典がある／イベントで “特定の特典だけ” を提供する場合はリクエストに reward_id を付けてください。
   ・HTTP ステータス 200 であればJSON 内 success が真かどうかで認証結果を判定してください。

4. APIキー管理の注意点
   • APIキーは機密情報です。ソースコードの公開リポジトリや第三者が閲覧可能な場所に記述しないでください。
   • 万が一APIキーが漏洩したり、不正利用が疑われる場合は速やかにキーを変更し、サポートへ連絡してください。
   • システムで複数人がAPIキーを共有する場合は、各プロジェクトの運用ルールを明確にし、アクセス権限管理を厳密に行うことを推奨します。
5. トラブルシューティング

   APIが正常に動作しない場合は、以下の点を確認してください。

   • APIキーが正しいものか（誤って他のプロジェクトのキーを使用していないか）
   • Base URLやエンドポイントのURLに誤りがないか
   • HTTPメソッドがPOSTになっているか
   • encoded_dataに必要な情報が正しく含まれているか
   • QRコードが有効期限内（生成から５分以内）であるか（有効期限を過ぎた場合はエラーが発生します）
   • APIキーが無効または削除されていないか

   レスポンス例とその原因（エラー時）

   
                               {
                                   "success": false,
                                   "message": "Invalid API key"
                               }
                               

   → 提供されたAPIキーが無効・削除済み、またはプロジェクトと一致していません。

   
                               {
                                   "success": false,
                                   "message": "No 'encoded_data' provided"
                               }
                               

   → 必須パラメータ encoded_data がリクエストに含まれていません。

   
                               {
                                   "success": false,
                                   "message": "Invalid QR data structure"
                               }
                               

   → QRコードが正しい形式でエンコードされていない、または構造が壊れています。

   
                               {
                                   "success": false,
                                   "isAuthentic": false,
                                   "message": "QR code expired (over 5 minutes)"
                               }
                               

   → QRコードが発行されてから5分以上経過しており、有効期限切れです。

   
                               {
                                   "success": false,
                                   "message": "Group tokens include multiple project codes",
                                   "multiple_projects": ["ABCD", "EFGH"]
                               }
                               

   → グループに含まれるNFTが異なるプロジェクトに属しており、検証対象外です。

   
                               {
                                   "success": false,
                                   "message": "Reward ID mismatch",
                                   "expected": 7,
                                   "provided": 5
                               }
                               

   → 呼び出し側が reward_id=7 を指定したのに、QR/トークンは reward_id=5 を持っていたケースです。

   
                               {
                                   "success": false,
                                   "message": "Token or access_code invalid"
                               }
                               

   → token_id と access_code の組み合わせが一致しない、またはトークンが存在しません。

   上記以外のエラーが発生した場合や原因が特定できない場合は、サポートまでご連絡ください。

1. 申請フォーム から必要事項を入力し、申請します。
2. 申請内容は SustinaPlus 運営が確認し、承認後にパートナー機能が利用可能になります。
3. 承認後は パートナーコンソール から各種設定を行います。
4. 審査中または承認済みの申請がある場合は、重複申請できません。

1. ロゴ設定ページ でロゴ画像を登録または差し替えできます。
2. 登録したロゴは、承認済みパートナーの表示箇所や関連画面で利用されます。
3. 不要になったロゴは同じ画面から削除できます。

1. 特典設定ページ で、対象タイトルごとの特典を登録します。
2. 公開期間、説明文、決済条件、表示用メディアなどを設定できます。
3. 店頭向けとオンライン向けで内容を分けたい場合は、運用方法に合わせて特典を作り分けてください。
4. 既存の利用履歴や決済履歴と紐付く特典は、削除ではなく無効化で管理される場合があります。

1. 広告設定ページ から、スレッド広告やサイト内広告を登録できます。
2. スレッド広告は、対象スレッドに紐づけて掲載します。
3. サイト内広告は画像形式で登録し、掲載には審査が必要です。
4. 画像サイズや掲載数には制限があります。画面上の案内に従って設定してください。

1. 登録情報の確認ページ では、登録内容、Web サイト URL、受取先ウォレットアドレス、API キーを確認できます。
2. 登録情報の編集ページ では、Web サイト URL、担当者情報、PR、受取先ウォレットアドレスなどを更新できます。
3. Web サイト URL は、オンライン決済で return_url を使う場合の基準になります。現行実装では、return_url のホストが登録済み Web サイト URL と一致している必要があります。
4. 受取先ウォレットアドレス は、POL または JPYC のパートナー決済で必須です。未設定または形式不正のままでは、/partner/payment_requests で決済リクエストを作成できません。
5. API キー は、API 連携で HTTP ヘッダー X-API-Key に設定して利用します。外部に公開せず、サーバー側の安全な設定として管理してください。
6. 有効な特典が残っている場合は、パートナー登録の削除ができません。

この方式は、店舗スタッフが店頭で対応する運用です。 SustinaPlus 専用アプリでお客様のサスプラカード QR を読み取り、特典確認、利用計上、必要に応じた決済まで進めます。 決済方法の選び方や API ごとの役割は、2-5 パートナー向け決済ガイド をあわせて確認してください。

この方式は、外部サイトや予約サイト、会員サイトなどからシステム連携で処理する運用です。 API 連携によって OTP 本人確認、特典確認、利用計上、決済へ進みます。 決済 API の使い分け、CASH_ETC の扱い、approval_url と return_url の役割は、 2-5 パートナー向け決済ガイド をあわせて確認してください。

POST /api/v1/external/partner/card_presentations/otp/start
X-API-Key: {API_KEY}
Content-Type: application/json

{
  "card_no": "1234-5678-9012"
}

{
  "success": true,
  "challenge_id": "challenge-1",
  "email_masked": "ta***@e***.com",
  "expires_at": 1760000000,
  "ttl_sec": 300,
  "card_no": "123456789012"
}

POST /api/v1/external/partner/card_presentations/otp/complete
X-API-Key: {API_KEY}
Content-Type: application/json

{
  "card_no": "1234-5678-9012",
  "challenge_id": "challenge-1",
  "otp_code": "123456"
}

{
  "success": true,
  "presentation_id": "PRES_1",
  "expires_at": 1760000300,
  "ttl_sec": 300,
  "encoded_data": "encoded-otp",
  "card_no": "123456789012"
}

POST /api/v1/external/partner/verify_card
X-API-Key: {API_KEY}
Content-Type: application/json

{
  "encoded_data": "encoded-otp"
}

{
  "success": true,
  "mode": "preview",
  "presentation_id": "PRES_1",
  "rewards": [
    {
      "id": 36,
      "name": "サンプル特典",
      "eligible_now": true,
      "pay_mode": "FIXED",
      "charge_amount": 1200,
      "fixed_amount": "1200"
    }
  ],
  "enabled_currencies": ["POL", "JPYC", "CASH_ETC"],
  "active_payment": null,
  "session_state": {
    "active_payment_exists": false,
    "manual_redeem_available": true,
    "payment_request_create_available": true,
    "next_action": "choose_manual_or_payment"
  },
  "settlement_contract": {
    "manual_redeem_supported": true,
    "payment_request_supported": true,
    "pay_mode_is_metadata": true,
    "manual_redeem_blocked_when_active_payment_exists": true,
    "new_session_required_after_terminal": true
  }
}

POST /api/v1/external/partner/payment_requests
X-API-Key: {API_KEY}
Content-Type: application/json

{
  "encoded_data": "encoded-otp",
  "reward_id": 36,
  "currency": "JPYC",
  "amount": "1200",
  "amount_jpy": "1200",
  "return_url": "https://partner.example.com/checkout/sustina/complete",
  "return_state": "order_12345"
}

{
  "success": true,
  "approval_required": true,
  "approval_url": "https://sustina-plus.jp/partner/card?payment_id=PAY_xxx",
  "return_url": "https://partner.example.com/checkout/sustina/complete",
  "return_state": "order_12345",
  "payment": {
    "payment_id": "PAY_xxx",
    "status": "requested",
    "currency": "JPYC",
    "amount": "1200",
    "amount_jpy": "1200",
    "reward_id": 36
  }
}

1. card_presentations/otp/start を呼ぶ
2. ユーザーがメールで受け取った OTP を入力する
3. card_presentations/otp/complete を呼び、encoded_data を受け取る
4. verify_card を呼び、reward_id と enabled_currencies を確認する
5. payment_requests を呼ぶ
6. approval_required=true なら approval_url に遷移させる
7. return_url に戻ったら payment_id で再照会し、payment.status=confirmed を確認する
8. confirmed を確認した後にだけ、外部サイト側の注文確定や予約確定を行う

{
  "encoded_data": "...",
  "reward_id": 36,
  "currency": "JPYC",
  "amount": "1200",
  "amount_jpy": "1200",
  "return_url": "https://partner.example.com/checkout/sustina/complete",
  "return_state": "order_12345"
}

パートナー決済機能を使うと、特典利用の確認、利用計上、決済記録、ユーザー承認を、 同じ照合セッションの中で管理できます。 店頭 QR 方式でも、オンライン API 方式でも、決済処理の考え方は共通です。

パートナー側で最初に決めるべきことは、SustinaPlus に何を記録したいかです。 選択肢は大きく分けて 3 つです。

CASH_ETC は、現金やその他決済の場合に使う区分です。 ここでいう「その他決済」には、クレジットカード、他社 QR 決済、既存の外部決済代行などが含まれます。

重要なのは、CASH_ETC は「何もしない近道」ではないことです。 SustinaPlus 側では PaymentRequest を作成し、決済種別を CASH_ETC として保存し、 その場で confirmed に進めます。 決済実体そのものは、パートナー側の会計・決済システムで行います。

POL または JPYC を使う場合は、ユーザー承認が必要です。 そのため、パートナー側で決済リクエストを作成したあと、ユーザーを SustinaPlus の承認画面へ遷移させます。

1. /partner/payment_requests を呼び出します。
2. レスポンスで payment_id、approval_required=true、approval_url を受け取ります。
3. パートナー側でユーザーを approval_url へ遷移させます。
4. ユーザーは SustinaPlus の承認画面で、ウォレット承認または署名を行います。
5. 決済完了後、return_url を指定していれば、その URL へ戻ります。
6. 戻り先では、クエリ文字列だけで完了扱いにせず、必ず /partner/payment_requests/<payment_id> を再照会し、payment.status=confirmed を確認してください。

1. return_url は https の絶対 URL で、登録済みパートナーサイトのホストと一致している必要があります。
2. return_url に戻ってきても、そのクエリだけで注文完了とせず、必ず payment_id で再照会してください。
3. 同じ照合セッションで未完了の決済がある場合は、manual の利用計上に切り替えられません。
4. 現行実装で利用できる通貨は POL、JPYC、CASH_ETC です。WETH はパートナー決済 API では利用できません。