REST API 仕様書 0.0.2
本ドキュメントでは、Game8 Storeと連携するためのAPI仕様を説明します。
APIを利用することで、ゲーム内アイテムの購入可否チェック、購入登録、購入履歴の取得、売上データの取得などを行えます。
パブリッシャー様からのご要望は積極的に取り入れていく方針ですので、改善点や追加機能のリクエストがあればお気軽にお知らせください。
また、すでにパブリッシャーAPIが存在する場合は、可能な限りその仕様に合わせる形で調整を行います。
目次
API一覧1. 共通仕様1.1. リクエスト仕様リクエストヘッダー1.2. レスポンス仕様共通レスポンスヘッダー共通レスポンスボディ2. APIエンドポイント2.1. アイテム購入可否チェック（GET /check）概要リクエスト仕様リクエストヘッダーリクエストパラメータ（Query Parameters）リクエスト例レスポンス仕様レスポンスボディレスポンス例（購入可能）レスポンス例（購入不可 - 年齢制限）レスポンス例（購入不可 - 購入制限オーバー）2.2. アイテム購入実績登録（POST /register）概要リクエスト仕様リクエストヘッダーリクエストボディ（JSON）リクエスト例レスポンス仕様レスポンスボディレスポンス例（成功）レスポンス例（失敗 - ユーザー不明）2.3. 購入履歴取得（GET /history）概要リクエスト仕様リクエストヘッダーリクエストパラメータ（Query Parameters）リクエスト例レスポンス仕様レスポンスボディhistory 配列のデータ構造レスポンス例（成功）2.4. 売上確認（GET /sales）概要リクエスト仕様リクエストヘッダーリクエストパラメータ（Query Parameters）リクエスト例レスポンス仕様レスポンスボディtransactions 配列のデータ構造レスポンス例（成功）3.エラーハンドリングリスト3.1. エラーコード一覧3.2. エラーハンドリングの推奨フロー3.3. リトライポリシー
API一覧
| API名 / API Name | エンドポイント / Endpoint | メソッド / Method | 必須 / Required | 説明 / Description |
|---|---|---|---|---|
| アイテム購入可否チェック / Purchase Eligibility Check | 必須 | ユーザーが指定アイテムを購入可能かを確認 | ||
| アイテム購入登録 / Register Purchase | 必須 | 購入完了後、ゲーム内アイテムを付与 | ||
| 購入履歴取得 / Get Purchase History | 任意 | 指定ユーザーの過去の購入履歴を取得 | ||
| 売上確認 / Get Sales Data | 任意 | 指定期間内の売上情報を取得 |
1. 共通仕様
| 項目 | 内容 |
|---|---|
| ホスト | |
| プロトコル | HTTPS |
| 文字コード | UTF-8 |
1.1. リクエスト仕様
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
1.2. レスポンス仕様
共通レスポンスヘッダー
| キー | 値 |
|---|---|
| Content-Type | application/json |
共通レスポンスボディ
| キー | 値 | 内容 |
|---|---|---|
| request_id | 一意のリクエストID | |
| timestamp | レスポンスのタイムスタンプ | |
| result_code | 結果コード | |
| message | メッセージ |
2. APIエンドポイント
2.1. アイテム購入可否チェック（GET /check）
概要
ゲーム内アイテムが購入可能かどうかを確認し、年齢制限や購入上限を考慮した結果を返します。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
リクエストパラメータ（Query Parameters）
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| item | string | ✅ | ゲーム内で発番された、購入対象のアイテムID |
| price | integer | ✅ | 購入対象アイテムのGame8Store内での販売価格（円） |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| purchasable | boolean | 購入可能なら 、購入不可なら |
| age_category | string | ユーザーの年齢区分 ( / / ) |
| monthly_limit | integer | 月額購入制限額（円）、 の場合は制限なし |
| remaining_limit | integer | 残り購入可能額（円）、 の場合は制限なし |
| requested_price | integer | リクエストされたアイテムの価格（円） |
レスポンス例（購入可能）
レスポンス例（購入不可 - 年齢制限）
レスポンス例（購入不可 - 購入制限オーバー）
2.2. アイテム購入実績登録（POST /register）
概要
購入完了後、ゲーム内アイテムを増加させるための処理。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | POST |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
リクエストボディ（JSON）
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| game | string | ✅ | Game8Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| item | string | ✅ | ゲーム内で発番された、購入対象のアイテムID |
| transaction_id | string | ✅ | 購入時の決済トランザクションID |
| item_name | string | ✅ | 購入アイテムの名称（例；ジェム100個パック） |
| price | integer | ✅ | 購入金額（円） |
| quantity | integer | ✅ | 購入したアイテムの個数（例：100） |
リクエスト例
レスポンス仕様
レスポンスボディ
| キー | 型 | 説明 |
|---|---|---|
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| item_granted | boolean | ゲーム内アイテムが付与されたか ( / ) |
レスポンス例（成功）
レスポンス例（失敗 - ユーザー不明）
2.3. 購入履歴取得（GET /history）
概要
ユーザーの過去の購入履歴を取得する。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
リクエストパラメータ（Query Parameters）
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| 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) | 購入日時 |
レスポンス例（成功）
2.4. 売上確認（GET /sales）
概要
指定された期間内の売上情報を取得する。
リクエスト仕様
| 項目 | 内容 |
|---|---|
| メソッド | GET |
| エンドポイント | |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |
リクエストヘッダー
| キー | 値 | 内容 |
|---|---|---|
| Authorization | Bearer | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
リクエストパラメータ（Query Parameters）
| キー | 型 | 必須 | 説明 |
|---|---|---|---|
| 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) | 購入日時 |
レスポンス例（成功）
3.エラーハンドリングリスト
3.1. エラーコード一覧
| エラーコード | 説明 | 対応策 |
|---|---|---|
| 成功 | - | |
| 不正なリクエストフォーマット | リクエストの構造や必須パラメータを確認し、正しい形式で送信する | |
| 認証情報が不足している | ヘッダーに正しい を設定する | |
| 無効なアクセストークン | アクセストークンの有効期限を確認し、必要に応じて再発行する | |
| アクセス権限が不足している | APIエンドポイントへの適切な権限があるか確認する | |
| 必須パラメータが不足している | 必須パラメータを確認し、リクエストを修正する | |
| パラメータの型が無効 | 例: に を渡している場合、整数値に修正する | |
| パラメータの値が不正 | 許可されていない値や範囲外の値を送信していないか確認する | |
| 該当するデータが存在しない | 存在する や を指定しているか確認する | |
| 購入制限の上限に達している | の値を確認し、制限を超えていないか確認する | |
| 年齢制限により購入不可 | を確認し、制限を超えないようにする | |
| 無効な取引ID | が正しいか確認する | |
| 指定されたユーザーが存在しない | が正しいか確認する | |
| 指定されたアイテムが存在しない | を確認し、正しいものを指定する | |
| サーバー内部エラー | サーバー側の問題の可能性があるため、一定時間後に再試行する | |
| 一時的なシステム障害 | 再試行する（推奨: 5秒後にリトライ） | |
| 不明なエラー | 詳細なエラーメッセージを確認し、開発チームへ問い合わせる |
3.2. エラーハンドリングの推奨フロー
- を確認
- （成功）であれば正常処理。
- それ以外の場合、エラーの種類を判定。
- クライアント側で修正可能なエラーか確認
- 系, 系はリクエスト内容の修正で対応可能。
- 系はデータの整合性を確認。
- リトライ可能なエラーか確認
- , は一時的なエラーの可能性があるため、数秒後にリトライ。
- エラーメッセージを記録・通知
- 不明なエラー（）はログを残し、開発チームに報告。
3.3. リトライポリシー
| エラーコード | リトライ間隔 | 最大リトライ回数 | 備考 |
|---|---|---|---|
| 5秒後 | 3回 | サーバー内部エラーのため、短時間で解消する可能性あり | |
| 10秒後 | 5回 | 一時的なシステム障害のため、長めの間隔を空ける | |
| なし | 0回 | 不明なエラーは即時報告 |
このエラーハンドリングリストを参考に、適切なエラーハンドリングを実装してください。