API仕様書

本ドキュメントでは、Game8 Storeと連携するためのAPI仕様を説明します。

API一覧

パブリッシャー様側で実装いただくAPI

Game8 Store からリクエストが送信されます。

Game8 Store側で提供するAPI

パブリッシャー様からGame8 Storeへリクエストを送信します。

1. 共通仕様

1.1. リクエスト仕様

リクエストヘッダー

1.2. レスポンス仕様

共通レスポンスヘッダー

共通レスポンスボディ

1.3. X-Signatureの設定

リクエストが正規のものか判定するため、ゲームごとに発行された秘密鍵を使って署名し、リクエストヘッダーに設定します。

署名の設定方法

1. GETの場合はクエリ文字列、POSTの場合はリクエストボディの内容でダイジェストを計算します。ダイジェストは、秘密鍵のシークレットを利用してHMAC-SHA256で算出します。

1. 算出したダイジェストをBase64エンコードして、リクエストヘッダーのX-Signatureに設定します。

署名の検証方法

1. GETの場合はクエリ文字列、POSTの場合はリクエストボディの内容でダイジェストを計算します。ダイジェストは、秘密鍵のシークレットを利用してHMAC-SHA256で算出します。

1. 算出したダイジェストをBase64エンコードして、リクエストヘッダーのX-Signatureの内容と一致するか検証します。
   1. 一致する場合は、正規なリクエストとして処理を実施します。
   2. 不一致の場合は、不正なリクエストとしてエラー返却します。

秘密鍵の取得方法

秘密鍵はGame8, Inc.にて作成し、共有いたします。

2. パブリッシャー様側で実装いただくAPI詳細

2.1. アイテム購入可否チェック（GET /check）必須

概要

ゲーム内アイテムが購入可能かどうかを確認し、年齢制限や購入上限を考慮した結果を返す。
また、数量限定などのアイテム購入時に決済までのタイムラグによる購入停止を避けるために、transaction id を設定することで対象アイテムを確保。

リクエスト仕様

リクエストヘッダー

クエリパラメータ

リクエスト例

GET /check HTTP/1.1
Host: <パブリッシャー任意>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?game=game123&user=user456&transaction_id=txn_123456&item=item789&item_category=paid&price=500

レスポンス仕様

レスポンスボディ

account_limitの構造

stockの構造

レスポンス例（購入可能）

{
  "request_id": "abc123",
  "timestamp": "2025-02-04T12:34:56Z",
  "result_code": "PUB0000",
  "message": "購入可能",
  "purchasable": "available",
  "age_category": "under_15",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

レスポンス例（購入不可 - 年齢確認未提出）

{
  "request_id": "abc124",
  "timestamp": "2025-02-04T12:35:00Z",
  "result_code": "PUB2006",
  "message": "年齢確認が行われていないため購入できません。",
  "purchasable": "unavailable",
  "age_category": "unset",
  "account_limit": null,
  "stock": null,
  "requested_price": 500
}

レスポンス例（購入不可 - 購入制限オーバー）

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB2005",
  "message": "購入制限の上限に達しています。",
  "purchasable": "unavailable",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 0,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

レスポンス例（購入不可 - アイテム未販売）

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB2007",
  "message": "対象アイテムは販売不可になっています。",
  "purchasable": "unavailable",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

レスポンス例（購入不可 - メンテナンス中）

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB6000",
  "message": "サービスメンテナンス中です。",
  "purchasable": "maintenance",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

2.2. アイテム購入実績登録（POST /register）必須

概要

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

リクエスト仕様

リクエストヘッダー

リクエストボディ

contents 配列の構造

リクエスト例

POST /register HTTP/1.1
Host: <パブリッシャー任意>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>

{
  "game": "game123",
  "user": "user456",
  "transaction_id": "txn789",
  "item": "pack001",
  "item_category": "paid",
  "item_name": "ジェム1000個",
  "price": 5000,
  "selling_price": 5000,
  "billing_amount": 5000,
  "purchased_at": "2025-02-04T12:36:00Z",
  "ref": "game8.jp",
  "payment_method": "Card",
  "contents": [
    {
      "content_id": "pack001-1",
      "content_name": "ジェム",
      "quantity": 1000
    },
    {
      "content_id": "pack001-2",
      "content_name": "おまけ金貨",
      "quantity": 100
    }
  ]
}

レスポンス仕様

レスポンスボディ

レスポンス例（成功）

{
  "request_id": "def456",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB0000",
  "message": "購入実績を登録しました。",
  "item_granted": true
}

レスポンス例（失敗 - ユーザー不明）

{
  "request_id": "def458",
  "timestamp": "2025-02-04T12:38:00Z",
  "result_code": "PUB3002",
  "message": "指定されたユーザーは存在しません。",
  "item_granted": false
}

レスポンス例（失敗 - 登録済み）

{
  "request_id": "def458",
  "timestamp": "2025-02-04T12:38:00Z",
  "result_code": "PUB3004",
  "message": "指定されたTransactionIDはすでに登録済みです。",
  "item_granted": false
}

2.3. プレイヤー情報取得（GET /user_info）必須

概要

ユーザーが入力したゲーム内IDをもとに、プレイヤー名とレベルの情報を取得する。取得した情報を購入確認画面で表示することで、ユーザーは入力したIDの正確性と、ゲームとの接続が正常であることの確認ができる。

リクエスト仕様

リクエストヘッダー

クエリパラメータ

リクエスト例

GET /user_info HTTP/1.1
Host: <パブリッシャー任意>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?game=game123&user=Player5678

レスポンス仕様

レスポンスボディ

user_name のマスク例

レスポンス例（成功）

{
  "request_id": "abc123",
  "timestamp": "2025-03-12T14:30:00Z",
  "result_code": "PUB0000",
  "message": "取得成功",
  "user_name": "****rX",
  "user_level": 45
}

レスポンス例（失敗 - プレイヤーIDが見つからない）

{
  "request_id": "abc124",
  "timestamp": "2025-03-12T14:31:00Z",
  "result_code": "PUB2004",
  "message": "プレイヤーIDが見つかりません。"
}

レスポンス例（失敗 - アカウントがBANなどにより非アクティブ状態）

{
  "request_id": "abc124",
  "timestamp": "2025-03-12T14:31:00Z",
  "result_code": "PUB2008",
  "message": "アカウント停止により購入不可。"
}

レスポンス例（失敗 - サーバーメンテナンス中）

{
  "request_id": "abc125",
  "timestamp": "2025-03-12T14:32:00Z",
  "result_code": "PUB6000",
  "message": "サービスメンテナンス中です。"
}

2.4. 在庫チェック（GET /stock）推奨

概要

指定されたアイテムの在庫状況を確認し、購入可能な残数量を返す。
数量限定商品やキャンペーン商品などの在庫管理が必要なアイテムに対して、ユーザーへの在庫状況表示や、購入フロー開始前の事前チェックに使用する。

リクエスト仕様

リクエストヘッダー

クエリパラメータ

リクエスト例

GET /stock HTTP/1.1
Host: <パブリッシャー任意>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
	?game=game123&user=user456&transaction_id=txn_123456&items=item789,item012

レスポンス仕様

レスポンスボディ

stockの構造

レスポンス例（在庫あり）

{
	"request_id": "abc123",
	"timestamp": "2025-02-04T12:34:56Z",
	"result_code": "PUB0000",
	"message": "成功",
	"stock": [
	  {
		  "item": "item789",
		  "total": 10,
		  "remaining": 8,
		  "restock_at": null
	  }
	]
}

レスポンス例（在庫なし）

{
	"request_id": "abc124",
	"timestamp": "2025-02-04T12:35:00Z",
	"result_code": "PUB2009",
	"message": "アイテムの購入数制限の上限に達している",
	"stock": [
	  {
		  "item": "item789",
		  "total": 10,
		  "remaining": 0,
		  "restock_at": null
	  }
	]
}

レスポンス例（無制限在庫）

{
	"request_id": "abc124",
	"timestamp": "2025-02-04T12:36:00Z",
	"result_code": "PUB0000",
	"message": "成功",
	"stock": [
	  {
	    "item": "item789",
		  "total": -1,
		  "remaining": -1,
		  "restock_at": null
	  }
	]
}

3. Game8 Store側で提供するAPI詳細

3.1. 注文照会（GET /orders/verify）利用任意

概要

/register APIで通知した注文の状態を、paid_transaction_id を使って照会するためのAPIです。
/register APIで使用した transaction_id と同一の値を paid_transaction_id として指定してください。
以下のユースケースを想定しています：

• /register 受信後の注文状態の確認
• API呼び出し失敗時の再照会

これにより、通知（/register）+ 照会（/orders/verify）の二重確認が可能になります。

本APIはGame8 Store側で常時稼働しており、事前の申請は不要です。パブリッシャー様側でエンドポイントを用意する必要はなく、利用する場合は本APIを呼び出す処理のみ実装いただきます。決済フローに組み込んでいない場合でも、リクエストを送信すれば注文の決済ステータスを確認できます（利用は任意）。

リクエスト仕様

リクエストヘッダー

クエリパラメータ

リクエスト例

GET /api/public/marketplace/publishers/example-publisher/games/example-game/orders/verify HTTP/1.1
Host: <Game8が指定>
Authorization: Bearer <ACCESS_TOKEN>
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?paid_transaction_id=txn_123456

レスポンス仕様

レスポンスボディ（成功時）

statusの値

レスポンス例（成功 - 完了済み注文）

{
  "request_id": "abc123",
  "timestamp": "2025-04-01T12:00:00+09:00",
  "result_code": "PUB0000",
  "message": "成功",
  "paid_transaction_id": "txn_123456",
  "status": "completed",
  "item_id": "item789",
  "price": 1000,
  "selling_price": 900,
  "billing_amount": 800,
  "purchased_at": "2025-04-01T12:00:00+09:00"
}

レスポンス例（成功 - 決済処理中）

{
  "request_id": "abc124",
  "timestamp": "2025-04-01T12:00:01+09:00",
  "result_code": "PUB0000",
  "message": "成功",
  "paid_transaction_id": "txn_123456",
  "status": "pending",
  "item_id": "item789",
  "price": 1000,
  "selling_price": 1000,
  "billing_amount": 1000,
  "purchased_at": null
}

エラーレスポンス

エラー時は共通レスポンスボディのみが返却されます：

{
  "request_id": "<リクエストID>",
  "timestamp": "<タイムスタンプ>",
  "result_code": "<エラーコード>",
  "message": "<エラーメッセージ>"
}

レスポンス例（エラー - 認証失敗）

{
  "request_id": "abc125",
  "timestamp": "2025-04-01T12:00:02+09:00",
  "result_code": "PUB1002",
  "message": "認証または署名検証に失敗しました"
}

レスポンス例（エラー - 注文未発見）

{
  "request_id": "abc126",
  "timestamp": "2025-04-01T12:00:03+09:00",
  "result_code": "PUB3001",
  "message": "指定された注文が見つかりません"
}

4. エラーハンドリング

4.1. エラーコード一覧

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

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

4.3. リトライポリシー

このエラーハンドリングリストを参考に、適切なエラーハンドリングを実装してください。