page icon

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. リクエスト仕様

リクエストヘッダー

キー内容
AuthorizationBearer 認証情報
Content-Typeapplication/jsonコンテンツタイプ

1.2. レスポンス仕様

共通レスポンスヘッダー

キー
Content-Typeapplication/json

共通レスポンスボディ

キー内容
request_id一意のリクエストID
timestampレスポンスのタイムスタンプ
result_code結果コード
messageメッセージ

2. APIエンドポイント


2.1. アイテム購入可否チェック(GET /check)

概要

ゲーム内アイテムが購入可能かどうかを確認し、年齢制限や購入上限を考慮した結果を返します。

リクエスト仕様

項目内容
メソッドGET
エンドポイント
プロトコルHTTPS
コンテンツタイプapplication/json

リクエストヘッダー

キー内容
AuthorizationBearer 認証情報
Content-Typeapplication/jsonコンテンツタイプ

リクエストパラメータ(Query Parameters)

キー必須説明
gamestringGame8Store内で発番された、ゲームのユニークID
userstringゲーム内で発番された、ゲーム内のユーザーユニークID
itemstringゲーム内で発番された、購入対象のアイテムID
priceinteger購入対象アイテムのGame8Store内での販売価格(円)

リクエスト例


レスポンス仕様

レスポンスボディ

キー説明
request_idstring一意のリクエストID
timestampstring (ISO8601)レスポンスのタイムスタンプ
result_codestring結果コード
messagestringメッセージ
purchasableboolean購入可能なら 、購入不可なら
age_categorystringユーザーの年齢区分 ( / / )
monthly_limitinteger月額購入制限額(円)、 の場合は制限なし
remaining_limitinteger残り購入可能額(円)、 の場合は制限なし
requested_priceintegerリクエストされたアイテムの価格(円)

レスポンス例(購入可能)

レスポンス例(購入不可 - 年齢制限)

レスポンス例(購入不可 - 購入制限オーバー)


 
 

2.2. アイテム購入実績登録(POST /register)

概要

購入完了後、ゲーム内アイテムを増加させるための処理。

リクエスト仕様

項目内容
メソッドPOST
エンドポイント
プロトコルHTTPS
コンテンツタイプapplication/json

リクエストヘッダー

キー内容
AuthorizationBearer 認証情報
Content-Typeapplication/jsonコンテンツタイプ

リクエストボディ(JSON)

キー必須説明
gamestringGame8Store内で発番された、ゲームのユニークID
userstringゲーム内で発番された、ゲーム内のユーザーユニークID
itemstringゲーム内で発番された、購入対象のアイテムID
transaction_idstring購入時の決済トランザクションID
item_namestring購入アイテムの名称(例;ジェム100個パック)
priceinteger購入金額(円)
quantityinteger購入したアイテムの個数(例:100)

リクエスト例


レスポンス仕様

レスポンスボディ

キー説明
request_idstring一意のリクエストID
timestampstring (ISO8601)レスポンスのタイムスタンプ
result_codestring結果コード
messagestringメッセージ
item_grantedbooleanゲーム内アイテムが付与されたか ( / )

レスポンス例(成功)

レスポンス例(失敗 - ユーザー不明)


 

2.3. 購入履歴取得(GET /history)

概要

ユーザーの過去の購入履歴を取得する。

リクエスト仕様

項目内容
メソッドGET
エンドポイント
プロトコルHTTPS
コンテンツタイプapplication/json

リクエストヘッダー

キー内容
AuthorizationBearer 認証情報
Content-Typeapplication/jsonコンテンツタイプ

リクエストパラメータ(Query Parameters)

キー必須説明
gamestringGame8Store内で発番された、ゲームのユニークID
userstringゲーム内で発番された、ゲーム内のユーザーユニークID
limitinteger取得する履歴の最大件数(デフォルト: 10)

リクエスト例


レスポンス仕様

レスポンスボディ

キー説明
request_idstring一意のリクエストID
timestampstring (ISO8601)レスポンスのタイムスタンプ
result_codestring結果コード
messagestringメッセージ
historyarray購入履歴のリスト

history 配列のデータ構造

キー説明
transaction_idstring決済トランザクションID
itemstringアイテムID
item_namestring購入アイテムの名称(例;ジェム100個パック)
priceinteger購入金額(円)
quantityinteger購入したアイテムの個数(例:100)
timestampstring (ISO8601)購入日時

レスポンス例(成功)


 
 

2.4. 売上確認(GET /sales)

概要

指定された期間内の売上情報を取得する。

リクエスト仕様

項目内容
メソッドGET
エンドポイント
プロトコルHTTPS
コンテンツタイプapplication/json

リクエストヘッダー

キー内容
AuthorizationBearer 認証情報
Content-Typeapplication/jsonコンテンツタイプ

リクエストパラメータ(Query Parameters)

キー必須説明
gamestringGame8Store内で発番された、ゲームのユニークID
start_datestring (YYYY-MM-DD)取得開始日
end_datestring (YYYY-MM-DD)取得終了日

リクエスト例


レスポンス仕様

レスポンスボディ

キー説明
request_idstring一意のリクエストID
timestampstring (ISO8601)レスポンスのタイムスタンプ
result_codestring結果コード
messagestringメッセージ
total_salesinteger期間内の総売上額(円)
total_feesinteger期間内の総手数料(円)
net_salesinteger期間内の純売上額(売上 - 手数料)
transactionsarray売上取引のリスト

transactions 配列のデータ構造

キー説明
transaction_idstring決済トランザクションID
itemstringアイテムID
item_namestring購入アイテムの名称(例;ジェム100個パック)
priceinteger購入金額(円)
quantityinteger購入したアイテムの個数(例:100)
feeinteger手数料(円)
net_amountinteger純売上(購入金額 - 手数料)
timestampstring (ISO8601)購入日時

レスポンス例(成功)


3.エラーハンドリングリスト

3.1. エラーコード一覧

エラーコード説明対応策
成功-
不正なリクエストフォーマットリクエストの構造や必須パラメータを確認し、正しい形式で送信する
認証情報が不足している ヘッダーに正しい を設定する
無効なアクセストークンアクセストークンの有効期限を確認し、必要に応じて再発行する
アクセス権限が不足しているAPIエンドポイントへの適切な権限があるか確認する
必須パラメータが不足している必須パラメータを確認し、リクエストを修正する
パラメータの型が無効例: を渡している場合、整数値に修正する
パラメータの値が不正許可されていない値や範囲外の値を送信していないか確認する
該当するデータが存在しない存在する を指定しているか確認する
購入制限の上限に達している の値を確認し、制限を超えていないか確認する
年齢制限により購入不可 を確認し、制限を超えないようにする
無効な取引ID が正しいか確認する
指定されたユーザーが存在しない が正しいか確認する
指定されたアイテムが存在しない を確認し、正しいものを指定する
サーバー内部エラーサーバー側の問題の可能性があるため、一定時間後に再試行する
一時的なシステム障害再試行する(推奨: 5秒後にリトライ)
不明なエラー詳細なエラーメッセージを確認し、開発チームへ問い合わせる

3.2. エラーハンドリングの推奨フロー

  1. を確認
      • (成功)であれば正常処理。
      • それ以外の場合、エラーの種類を判定。
  1. クライアント側で修正可能なエラーか確認
      • 系, 系はリクエスト内容の修正で対応可能。
      • 系はデータの整合性を確認。
  1. リトライ可能なエラーか確認
      • , は一時的なエラーの可能性があるため、数秒後にリトライ。
  1. エラーメッセージを記録・通知
      • 不明なエラー()はログを残し、開発チームに報告。

3.3. リトライポリシー

エラーコードリトライ間隔最大リトライ回数備考
5秒後3回サーバー内部エラーのため、短時間で解消する可能性あり
10秒後5回一時的なシステム障害のため、長めの間隔を空ける
なし0回不明なエラーは即時報告
このエラーハンドリングリストを参考に、適切なエラーハンドリングを実装してください。