REST API 仕様書 0.0.3
本ドキュメントでは、Game8 Storeと連携するためのAPI仕様を説明します。
API一覧
パブリッシャー様側で実装いただくAPI
Game8 Store からリクエストが送信されます。
| API名 / API Name | エンドポイント / Endpoint | メソッド / Method | 必須 / Required | 説明 / Description |
|---|---|---|---|---|
| アイテム購入可否チェック / Purchase Eligibility Check | 必須 | ユーザーが指定アイテムを購入可能かを確認 | ||
| アイテム購入登録 / Register Purchase | 必須 | 購入完了後、ゲーム内アイテムを付与 | ||
| プレイヤー情報取得 / Retrieve Player Information | 推奨 | ゲーム内IDをもとに、プレイヤー名とレベルの情報を取得。 |
1. 共通仕様
| 項目 | 内容 |
|---|---|
| ホスト | Game8提供API: パブリッシャー提供API: |
| プロトコル | HTTPS |
| 文字コード | UTF-8 |
1.1. リクエスト仕様
1.2. レスポンス仕様
共通レスポンスヘッダー
| キー | 値 |
|---|---|
| Content-Type | application/json |
共通レスポンスボディ
| キー | 値 | 内容 |
|---|---|---|
| request_id | 一意のリクエストID。トラブルシューティングなどでリクエストの追跡をする際に使用。 | |
| timestamp | レスポンスのタイムスタンプ | |
| result_code | 結果コード | |
| message | メッセージ |
エラーコード一覧 に記載されているエラーが発生した場合、共通レスポンスボディの項目のみを返却。
1.3 X-Signatureの設定
リクエストが正規のものか判定するため、ゲームごとに発行された秘密鍵を使って署名し、リクエストヘッダーに設定します。
署名の設定方法
- GETの場合はクエリ文字列、POSTの場合はリクエストボディの内容でダイジェストを計算します。ダイジェストは、秘密鍵のシークレットを利用してHMAC-SHA256で算出します。
ダイジェストの計算に使用するメッセージ例
GETの場合：game=game123&user=user456&…
POSTの場合：{\”game\”:\”game123\”,\”user\”:\”user456\”,…}
- 算出したダイジェストをBase64エンコードして、リクエストヘッダーのX-Signatureに設定します。
署名の検証方法
- GETの場合はクエリ文字列、POSTの場合はリクエストボディの内容でダイジェストを計算します。ダイジェストは、秘密鍵のシークレットを利用してHMAC-SHA256で算出します。
ダイジェストの計算に使用するメッセージ例
GETの場合：game=game123&user=user456&…
POSTの場合：{\”game\”:\”game123\”,\”user\”:\”user456\”,…}
- 算出したダイジェストをBase64エンコードして、リクエストヘッダーのX-Signatureの内容と一致するか検証します。
- 一致する場合は、正規なリクエストとして処理を実施します。
- 不一致の場合は、不正なリクエストとしてエラー返却します。
秘密鍵の取得方法
秘密鍵はGame8, Inc.にて作成し、共有いたします。
2. パブリッシャー様側で実装いただくAPI詳細
2.1. アイテム購入可否チェック（GET /check）
概要
ゲーム内アイテムが購入可能かどうかを確認し、年齢制限や購入上限を考慮した結果を返す。
また、数量限定などのアイテム購入時に決済までのタイムラグによる購入停止を避けるために、transaction id を設定することで対象アイテムを確保。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | 署名検証用の署名 |
クエリパラメータ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| transaction_id | string | ✅ | 取引を一意に特定する識別子 |
| item | string | ✅ | ゲーム内で発番された、購入対象のアイテムID （？） |
| price | integer | ✅ | 購入対象アイテムのGame8Store内での販売価格（税込・円） |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| purchasable | string | 購入可能： 購入不可： メンテナンス中： |
| age_category | string | ユーザーの年齢区分。例として / / / / などがありますが、必要に応じて他の値を設定できます。 |
| monthly_limit | integer | 月額購入制限額（円）、 の場合は制限なし |
| remaining_limit | integer | 残り購入可能額（円）、 の場合は制限なし |
| requested_price | integer | リクエストされたアイテムの価格（円） |
レスポンス例（購入可能）
レスポンス例（購入不可 - 年齢確認未提出）
レスポンス例（購入不可 - 購入制限オーバー）
レスポンス例（購入不可 - アイテム未販売）
レスポンス例（購入不可 - メンテナンス中）
2.2. アイテム購入実績登録（POST /register）
概要
購入完了後、ゲーム内アイテムを増加させるための処理。
購入実績登録をする前に、以下の処理を入れることを推奨します。
- アイテム購入可否チェックAPIを通したtransaction_idを含むリクエストのみ受け付ける
- 購入制限に抵触していないことを検証する
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | POST |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | 署名検証用の署名 |
リクエストボディ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| item | string | ✅ | ゲーム内で発番された、購入対象のアイテムID （？） |
| transaction_id | string | ✅ | 取引を一意に特定する識別子 |
| item_name | string | ✅ | 購入アイテムの名称（例；ジェム100個パック） |
| price | integer | ✅ | 購入対象アイテムのGame8Store内での販売価格（税込・円） |
| contents | array | ✅ | アイテムに含まれる内容物のリスト |
contents 配列の構造
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| content_id | string | ✅ | にサフィックスをつけたアイテム内内容物のIDを自動付与（例：） |
| content_name | string | ✅ | アイテム内の内容物の名称（例：ジェム） |
| quantity | integer | ✅ | アイテム内の内容物の個数（例：1000） |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| item_granted | boolean | ゲーム内アイテムが付与されたか ( / ) |
レスポンス例（成功）
レスポンス例（失敗 - ユーザー不明）
レスポンス例（失敗 - 登録済み）
2.5.プレイヤー情報取得（GET /user_info）
概要
ユーザーが入力したゲーム内IDをもとに、プレイヤー名とレベルの情報を取得する。取得した情報を購入確認画面で表示することで、ユーザーは入力したIDの正確性と、ゲームとの接続が正常であることの確認ができる。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | 認証情報 | |
| Content-Type | コンテンツタイプ | |
| X-Signature | 署名検証用の署名 |
クエリパラメータ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| request_id | string | ✅ | 一意のリクエストID |
| timestamp | string (ISO8601) | ✅ | レスポンスのタイムスタンプ |
| result_code | string | ✅ | 結果コード |
| message | string | ✅ | メッセージ |
| user_name | string | ✅ | プレイヤー名（マスク可） |
| user_level | integer | ✅ | プレイヤーレベルやランク。ゲーム内に該当情報が存在しない場合は-1を返す。 |
入力したゲーム内IDをもとに、他のプレイヤーの名前も取得できるため、必要に応じてプレイヤー名をマスクしてください。
user_name のマスク例
| プレイヤー名 | マスクしたuser_name |
|---|---|
| aa | *a |
| aaa | *aa |
| aaaa | **aa |
| aaaaa | ***aa |
レスポンス例（成功）
レスポンス例（失敗 - プレイヤーIDが見つからない）
レスポンス例（失敗 - アカウントがBANなどにより非アクティブ状態）
レスポンス例（失敗 - サーバーメンテナンス中）
3.エラーハンドリング
3.1. エラーコード一覧
| エラーコード | 説明 | 対応策 |
|---|---|---|
| 成功 | - | |
| 不正なリクエストフォーマット | リクエストの構造や必須パラメータを確認し、正しい形式で送信する | |
| 認証情報が不足している | ヘッダーに正しい を設定する | |
| 無効なアクセストークン | アクセストークンの有効期限を確認し、必要に応じて再発行する | |
| アクセス権限が不足している | APIエンドポイントへの適切な権限があるか確認する | |
| 署名内容が不一致 | 署名に利用している秘密鍵のシークレットが正しいことを確認する | |
| 処理済みのリクエスト | 重複した を送信しないようにする | |
| 必須パラメータが不足している | 必須パラメータを確認し、リクエストを修正する | |
| パラメータの型が無効 | 例: に を渡している場合、整数値に修正する | |
| パラメータの値が不正 | 許可されていない値や範囲外の値を送信していないか確認する | |
| 該当するデータが存在しない | 存在する や を指定しているか確認する | |
| 購入制限の上限に達している | の値を確認し、制限を超えていないか確認する | |
| 年齢確認が行われていない | ユーザーにゲーム内での年齢確認を促す | |
| アイテム販売中止 | ストア側の販売アイテムの調整を営業・開発チームへ問い合わせる | |
| アカウント停止により購入不可 | - | |
| 無効な取引ID | が正しいか確認する | |
| 指定されたユーザーが存在しない | が正しいか確認する | |
| 指定されたアイテムが存在しない | を確認し、正しいものを指定する | |
| 登録済み取引ID | が正しいか確認する | |
| サーバー内部エラー | サーバー側の問題の可能性があるため、一定時間後に再試行する | |
| 一時的なシステム障害 | 再試行する（推奨: 5秒後にリトライ） | |
| 不明なエラー | 詳細なエラーメッセージを確認し、開発チームへ問い合わせる | |
| メンテナンス中 | サービス停止中として一定時間後に再試行する |
3.2. エラーハンドリングの推奨フロー
- を確認
- （成功）であれば正常処理。
- それ以外の場合、エラーの種類を判定。
- クライアント側で修正可能なエラーか確認
- 系, 系はリクエスト内容の修正で対応可能。
- 系はデータの整合性を確認。
- リトライ可能なエラーか確認
- , は一時的なエラーの可能性があるため、数秒後にリトライ。
- エラーメッセージを記録・通知
- 不明なエラー（）はログを残し、開発チームに報告。
3.3. リトライポリシー
| エラーコード | リトライ間隔 | 最大リトライ回数 | 備考 |
|---|---|---|---|
| 5秒後 | 3回 | サーバー内部エラーのため、短時間で解消する可能性あり | |
| 10秒後 | 5回 | 一時的なシステム障害のため、長めの間隔を空ける | |
| なし | 0回 | 不明なエラーは即時報告 |
このエラーハンドリングリストを参考に、適切なエラーハンドリングを実装してください。