REST API 仕様書 0.0.3
本ドキュメントでは、Game8 Storeと連携するためのAPI仕様を説明します。
APIを利用することで、ゲーム内アイテムの購入可否チェック、購入登録、購入履歴の取得、売上データの取得などを行えます。
パブリッシャー様からのご要望は積極的に取り入れていく方針ですので、改善点や追加機能のリクエストがあればお気軽にお知らせください。また、すでにパブリッシャーAPIが存在する場合は、可能な限りその仕様に合わせる形で調整を行います。
目次
API一覧パブリッシャーが実装するAPIGame8 Store が提供するAPI1. 共通仕様1.1. リクエスト仕様リクエストヘッダー1.2. レスポンス仕様共通レスポンスヘッダー共通レスポンスボディ1.3 X-Signatureの設定署名の設定方法署名の検証方法秘密鍵の取得方法2. パブリッシャーが実装するAPI2.1. アイテム購入可否チェック（GET /check）必須2.2. アイテム購入実績登録（POST /register）必須2.3. サービス稼働 チェック（GET /service_status）2.4. 取引ID リリース（POST /release）3.Game8が提供するAPI3.1. 購入履歴取得（GET /history）3.2. 売上データ取得（GET /sales）4.エラーハンドリング4.1. エラーコード一覧4.2. エラーハンドリングの推奨フロー4.3. リトライポリシー
API一覧
パブリッシャーが実装するAPI
Game8 Store からリクエストが送信されます。
| API名 / API Name | エンドポイント / Endpoint | メソッド / Method | 必須 / Required | 説明 / Description |
|---|---|---|---|---|
| アイテム購入可否チェック / Purchase Eligibility Check | 必須 | ユーザーが指定アイテムを購入可能かを確認 | ||
| アイテム購入登録 / Register Purchase | 必須 | 購入完了後、ゲーム内アイテムを付与 | ||
| サービス稼働チェック / Service Status Check | 任意 | ゲームサービスが正常に稼働しているかを確認 | ||
| 取引ID リリース / Transaction ID release | 任意 | 購入確保したが確定しなかった場合の在庫リリース |
Game8 Store が提供するAPI
パブリッシャーがこのAPIを利用します。
| API名 / API Name | エンドポイント / Endpoint | メソッド / Method | 必須 / Required | 説明 / Description |
|---|---|---|---|---|
| 購入履歴取得 / Get Purchase History | 任意 | 指定ユーザーの過去の購入履歴を取得 | ||
| 売上データ取得 / Get Sales Data | 任意 | 指定期間内の売上情報を取得 |
1. 共通仕様
| 項目 | 内容 |
|---|---|
| ホスト | Game8提供API: パブリッシャー提供API: |
| プロトコル | HTTPS |
| 文字コード | UTF-8 |
1.1. リクエスト仕様
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | 署名検証用の署名 |
アクセストークンは、英数字（大文字・小文字を含む）を含む16〜36文字のランダムな文字列である必要があります。
ご自身で作成いただくことも可能ですが、弊社で作成してお渡しすることも可能ですので、ご希望の場合はお問い合わせください。
1.2. レスポンス仕様
共通レスポンスヘッダー
| キー | 値 |
|---|---|
| Content-Type | application/json |
共通レスポンスボディ
| キー | 値 | 内容 |
|---|---|---|
| request_id | 一意のリクエストID。トラブルシューティングなどでリクエストの追跡をする際に使用。 | |
| timestamp | レスポンスのタイムスタンプ | |
| result_code | 結果コード | |
| message | メッセージ |
エラーコード一覧 に記載されているエラーが発生した場合、共通レスポンスボディの項目のみを返却。
1.3 X-Signatureの設定
リクエストが正規のものか判定するため、共通の秘密鍵を使って署名し、リクエストヘッダーに設定します。
署名の設定方法
- GETの場合はリクエストパラメータ、POSTの場合はリクエストボディの内容でダイジェストを計算します。
- 秘密鍵のシークレットを利用してHMAC-SHA256を算出します。
- 算出したダイジェストをBase64エンコードして、リクエストヘッダーのX-Signatureに設定します。
署名の検証方法
- GETの場合はリクエストパラメータ、POSTの場合はリクエストボディのダイジェストを計算します。
- 秘密鍵のシークレットを利用してHMAC-SHA256を算出します。
- 算出したダイジェストを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 | ✅ | 購入金額（円） |
| 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.3. サービス稼働 チェック（GET /service_status）
概要
ゲームサービスが正常に稼働しているかを確認し、アイテム購入等のサービスが利用可能かを判断します。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | 署名検証用の署名 |
リクエストパラメータ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| service_status | string | 稼働中： 稼働停止中： メンテナンス中： |
レスポンス例（成功）
2.4. 取引ID リリース（POST /release）
概要
アイテム購入可否チェック（/check）で確保したが、購入確定しなかった場合に在庫確保をリリース（購入キャンセル）する。
ただし、すでに同一Transaction IDでゲーム内でアイテム付与されている場合には、本処理でのキャンセルは実施できないものとする。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | POST |
| エンドポイント | |
| プロトコル | 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 | メッセージ |
レスポンス例（成功）
3.Game8が提供するAPI
3.1. 購入履歴取得（GET /history）
概要
パブリッシャーは本エンドポイントを呼び出すことで、Game8 のサーバーから指定ユーザーの購入履歴を取得できます。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | 署名検証用の署名 |
リクエストパラメータ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| limit | integer | ❌ | 取得する履歴の最大件数（デフォルト: 10） |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| history | array | 購入履歴のリスト |
history 配列のデータ構造
| キー | 型 | 説明 |
|---|---|---|
| transaction_id | string | 決済トランザクションID |
| item | string | アイテムID |
| item_name | string | 購入アイテムの名称（例；ジェム100個パック） |
| price | integer | 購入金額（円） |
| quantity | integer | 購入したアイテムの個数（例：100） |
| timestamp | string (ISO8601) | 購入日時 |
レスポンス例（成功）
3.2. 売上データ取得（GET /sales）
概要
パブリッシャーは本エンドポイントを呼び出すことで、Game8 のサーバーから指定期間内の売上データを取得できます。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | 署名検証用の署名 |
リクエストパラメータ
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| start_date | string (YYYY-MM-DD) | ✅ | 取得開始日 |
| end_date | string (YYYY-MM-DD) | ✅ | 取得終了日 |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| total_sales | integer | 期間内の総売上額（円） |
| total_fees | integer | 期間内の総手数料（円） |
| net_sales | integer | 期間内の純売上額（売上 - 手数料） |
| transactions | array | 売上取引のリスト |
transactions 配列のデータ構造
| キー | 型 | 説明 |
|---|---|---|
| transaction_id | string | 決済トランザクションID |
| item | string | アイテムID |
| item_name | string | 購入アイテムの名称（例；ジェム100個パック） |
| price | integer | 購入金額（円） |
| quantity | integer | 購入したアイテムの個数（例：100） |
| fee | integer | 手数料（円） |
| net_amount | integer | 純売上（購入金額 - 手数料） |
| timestamp | string (ISO8601) | 購入日時 |
レスポンス例（成功）
4.エラーハンドリング
4.1. エラーコード一覧
| エラーコード | 説明 | 対応策 |
|---|---|---|
| 成功 | - | |
| 不正なリクエストフォーマット | リクエストの構造や必須パラメータを確認し、正しい形式で送信する | |
| 認証情報が不足している | ヘッダーに正しい を設定する | |
| 無効なアクセストークン | アクセストークンの有効期限を確認し、必要に応じて再発行する | |
| アクセス権限が不足している | APIエンドポイントへの適切な権限があるか確認する | |
| 署名内容が不一致 | 署名に利用している秘密鍵のシークレットが正しいことを確認する | |
| 処理済みのリクエスト | 重複した を送信しないようにする | |
| 必須パラメータが不足している | 必須パラメータを確認し、リクエストを修正する | |
| パラメータの型が無効 | 例: に を渡している場合、整数値に修正する | |
| パラメータの値が不正 | 許可されていない値や範囲外の値を送信していないか確認する | |
| 該当するデータが存在しない | 存在する や を指定しているか確認する | |
| 購入制限の上限に達している | の値を確認し、制限を超えていないか確認する | |
| 年齢制限により購入不可 | を確認し、制限を超えないようにする | |
| アイテム販売中止 | ストア側の販売アイテムの調整を営業・開発チームへ問い合わせる | |
| 無効な取引ID | が正しいか確認する | |
| 指定されたユーザーが存在しない | が正しいか確認する | |
| 指定されたアイテムが存在しない | を確認し、正しいものを指定する | |
| 登録済み取引ID | が正しいか確認する | |
| サーバー内部エラー | サーバー側の問題の可能性があるため、一定時間後に再試行する | |
| 一時的なシステム障害 | 再試行する（推奨: 5秒後にリトライ） | |
| 不明なエラー | 詳細なエラーメッセージを確認し、開発チームへ問い合わせる | |
| メンテナンス中 | サービス停止中として一定時間後に再試行する |
4.2. エラーハンドリングの推奨フロー
- を確認
- （成功）であれば正常処理。
- それ以外の場合、エラーの種類を判定。
- クライアント側で修正可能なエラーか確認
- 系, 系はリクエスト内容の修正で対応可能。
- 系はデータの整合性を確認。
- リトライ可能なエラーか確認
- , は一時的なエラーの可能性があるため、数秒後にリトライ。
- エラーメッセージを記録・通知
- 不明なエラー（）はログを残し、開発チームに報告。
4.3. リトライポリシー
| エラーコード | リトライ間隔 | 最大リトライ回数 | 備考 |
|---|---|---|---|
| 5秒後 | 3回 | サーバー内部エラーのため、短時間で解消する可能性あり | |
| 10秒後 | 5回 | 一時的なシステム障害のため、長めの間隔を空ける | |
| なし | 0回 | 不明なエラーは即時報告 |
このエラーハンドリングリストを参考に、適切なエラーハンドリングを実装してください。