---
title: "API仕様書"
site: "Game8 Store – Developer Center"
lang: "ja"
category: "技術仕様 & API"
canonical: "https://developers.store.game8.jp/ja/api-v5/"
---

# API仕様書

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

## API一覧

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

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

| API名 / API Name | エンドポイント / Endpoint | メソッド / Method | 必須 / Required | 説明 / Description |
| --- | --- | --- | --- | --- |
| **アイテム購入可否チェック** / Purchase Eligibility Check | `/check` | `GET` | 必須 | ユーザーが指定アイテムを購入可能かを確認 |
| **アイテム購入登録** / Register Purchase | `/register` | `POST` | 必須 | 購入完了後、ゲーム内アイテムを付与 |
| **プレイヤー情報取得 / Retrieve Player Information** | `/user_info` | `GET` | 必須 | ゲーム内IDをもとに、プレイヤー名とレベルの情報を取得。 |
| 在庫チェック / Inventory Check | `/stock` | `GET` | 推奨 | 指定アイテムの在庫状況を確認 |

#### Game8 Store側で提供するAPI

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

| API名 / API Name | エンドポイント / Endpoint | メソッド / Method | 必須 / Required | 説明 / Description |
| --- | --- | --- | --- | --- |
| **注文照会** / Order Verify | `/orders/verify` | `GET` | 任意 | `paid_transaction_id` を指定して注文の状態を照会 |

## 1. 共通仕様

| 項目 | 内容 |
| --- | --- |
| ホスト | Game8提供API: `<Game8が指定>`<br>パブリッシャー提供API:`<パブリッシャーが指定>` |
| プロトコル | HTTPS |
| 文字コード | UTF-8 |

### 1.1. リクエスト仕様

#### リクエストヘッダー

| キー | 値 | 内容 |
| --- | --- | --- |
| Authorization | Bearer `<ACCESS_TOKEN>` | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | `<SIGNED_DATA>` | 署名検証用の署名 |

> アクセストークンは、ゲームごとに発行された英数字（大文字・小文字を含む）を含む16〜36文字のランダムな文字列である必要があります。
>
> Game8, Inc.にて作成してお渡しします。ご自身で作成いただくことも可能ですのでご希望の場合はお問い合わせください。

### 1.2. レスポンス仕様

#### 共通レスポンスヘッダー

| キー | 値 |
| --- | --- |
| Content-Type | application/json |

#### 共通レスポンスボディ

| キー | 値 | 内容 |
| --- | --- | --- |
| request_id | `string` | 一意のリクエストID。トラブルシューティングなどでリクエストの追跡をする際に使用。 |
| timestamp | `string (ISO8601)` | レスポンスのタイムスタンプ |
| result_code | `string` | 結果コード |
| message | `string` | メッセージ |

> [エラーコード一覧](https://developers.store.game8.jp/ja/api-v5/#337bef2a-13a2-8102-b2d0-c0c36f98ad7e) に記載されているエラーが発生した場合、共通レスポンスボディの項目のみを返却。

### X-Signatureの設定

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

#### 署名の設定方法

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

> ダイジェストの計算に使用するメッセージ例
>
> GETの場合：game=game123&user=user456&…
>
> POSTの場合：{\”game\”:\”game123\”,\”user\”:\”user456\”,…}

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

#### 署名の検証方法

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

> ダイジェストの計算に使用するメッセージ例
>
> GETの場合：game=game123&user=user456&…
>
> POSTの場合：{\”game\”:\”game123\”,\”user\”:\”user456\”,…}

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

#### 秘密鍵の取得方法

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

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

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

#### 概要

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

> プレゼントキャンペーンを実施する際には、0円の商品について、年齢認証なしでもアイテムを購入可能と判定いただく対応をお願いする場合がございます。

#### リクエスト仕様

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

#### リクエストヘッダー

| キー | 値 | 内容 |
| --- | --- | --- |
| Authorization | Bearer `<ACCESS_TOKEN>` | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | `<SIGNED_DATA>` | 署名検証用の署名 |

#### クエリパラメータ

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| game | string | ✅ | Game8 Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| transaction_id | string | ✅ | 取引を一意に特定する識別子 |
| item | string | ✅ | ゲーム内で発番された、購入対象のアイテムID （[？](https://developers.store.game8.jp/ja/faq/#acc-faq-523efe3d)） |
| item_category | string | ✅ | 購入対象アイテムの種別<br>`paid` : 有料商品（通常の課金アイテム）<br>`free` : 無料商品（プレゼント・キャンペーン配布品など、価格が0円の商品） |
| price | integer | ✅ | 購入対象アイテムの商品金額（税込・円）。割引適用前の定価。 |
| selling_price | integer | ✅ | パブリッシャー負担の割引適用後の購入代金（税込・円）。割引がない場合は price と同額。 |
| billing_amount | integer | ✅ | 購入代金からポイントやクーポン利用等を差し引いた最終的な決済金額（税込・円）。適用がない場合は selling_price と同額。 |

#### リクエスト例

```json
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
```

#### レスポンス仕様

#### レスポンスボディ

| キー | 型 | 説明 |
| --- | --- | --- |
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| purchasable | string | 購入可能：`available`<br>購入不可：`unavailable`<br>メンテナンス中：`maintenance` |
| age_category | string | ユーザーの年齢区分。例として `under_15` / `under_18` / `adult` / `under_17` / `over_17` などがありますが、必要に応じて他の値を設定できます。 |
| account_limit | Object \| null | アカウントの購入制限額。購入制限額がなければnull |
| stock | Object \| null | 在庫情報。無制限在庫の場合はnull |
| requested_price | integer | リクエストされたアイテムの価格（円） |

#### account_limitの構造

| キー | 型 | 説明 |
| --- | --- | --- |
| total | integer | 購入制限額（円） |
| remaining | integer | 残り購入可能額（円） |
| reset_at | string (ISO8601) \| null | 購入制限の解除予定日時。未定の場合は null |

#### stockの構造

| キー | 型 | 説明 |
| --- | --- | --- |
| total | integer | 総在庫数 |
| remaining | integer | 残り在庫数 |
| restock_interval | string | 日ごと：`daily`<br>週ごと：`weekly`<br>月ごと： `monthly`<br>入荷予定が未定の場合はnull |
| restock_at | string (ISO8601) \| null | 次回入荷予定日時（予定がある場合）。未定または無制限の場合は null |

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

```json
{
  "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
}
```

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

```json
{
  "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
}
```

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

```json
{
  "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
}
```

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

```json
{
  "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
}
```

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

```json
{
  "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）`必須`

#### 概要

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

> 購入実績登録をする前に、以下の処理を入れることを推奨します。
>
> - アイテム購入可否チェックAPIを通したtransaction_idを含むリクエストのみ受け付ける
> - 購入制限に抵触していないことを検証する

> プレゼントキャンペーンを実施する際には、0円の商品について、年齢認証なしでもアイテムを購入可能と判定いただく対応をお願いする場合がございます。

#### リクエスト仕様

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

#### リクエストヘッダー

| キー | 値 | 内容 |
| --- | --- | --- |
| Authorization | Bearer `<ACCESS_TOKEN>` | 認証情報 |
| Content-Type | application/json | コンテンツタイプ |
| X-Signature | `<SIGNED_DATA>` | 署名検証用の署名 |

#### リクエストボディ

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| game | string | ✅ | Game8 Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| item | string | ✅ | ゲーム内で発番された、購入対象のアイテムID （[？](https://developers.store.game8.jp/ja/faq/#acc-faq-523efe3d)） |
| transaction_id | string | ✅ | 取引を一意に特定する識別子 |
| item_category | string | ✅ | 購入対象アイテムの種別<br>`paid` : 有料商品（通常の課金アイテム）<br>`free` : 無料商品（プレゼント・キャンペーン配布品など、価格が0円の商品） |
| item_name | string | ✅ | 購入対象アイテムの名称（例；ジェム100個パック） |
| price | integer | ✅ | 購入対象アイテムの商品金額（税込・円）。割引適用前の定価。 |
| selling_price | integer | ✅ | パブリッシャー負担の割引適用後の購入代金（税込・円）。割引がない場合は price と同額。 |
| billing_amount | integer | ✅ | 購入代金からポイントやクーポン利用等を差し引いた最終的な決済金額（税込・円）。適用がない場合は selling_price と同額。 |
| purchased_at | string (ISO8601) | ✅ | 購入日時 |
| ref | string \| null | ✅ | 流入元のドメイン名（例: game8.jp）。流入元が不明な場合は null。 |
| payment_method | string \| null | ✅ | 決済方法。クレジットカードはCard、その他は決済サービス名（メルペイ、PayPal等）。全額ポイント払いなど決済サービスを経由しない場合はnull。 |
| contents | array | ✅ | アイテムに含まれる内容物のリスト |

#### contents 配列の構造

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| content_id | string | ✅ | `item` にサフィックスをつけたアイテム内内容物のIDを自動付与（例：`pack001-1`） |
| content_name | string | ✅ | アイテム内の内容物の名称（例：ジェム） |
| quantity | integer | ✅ | アイテム内の内容物の個数（例：1000） |

#### リクエスト例

```json
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 | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| item_granted | boolean | ゲーム内アイテムが付与されたか (`true` / `false`) |

#### レスポンス例（成功）

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

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

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

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

```json
{
  "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` |
| プロトコル | HTTPS |
| コンテンツタイプ | `application/json` |

#### リクエストヘッダー

| キー | 値 | 内容 |
| --- | --- | --- |
| Authorization | `Bearer <ACCESS_TOKEN>` | 認証情報 |
| Content-Type | `application/json` | コンテンツタイプ |
| X-Signature | `<SIGNED_DATA>` | 署名検証用の署名 |

#### クエリパラメータ

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| game | string | ✅ | Game8 Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |

#### リクエスト例

```json
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
```

#### レスポンス仕様

#### レスポンスボディ

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| 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 |

#### レスポンス例（成功）

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

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

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

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

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

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

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

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

#### 概要

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

#### リクエスト仕様

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

#### リクエストヘッダー

| キー | 値 | 内容 |
| --- | --- | --- |
| Authorization | `Bearer <ACCESS_TOKEN>` | 認証情報 |
| Content-Type | `application/json` | コンテンツタイプ |
| X-Signature | `<SIGNED_DATA>` | 署名検証用の署名 |

#### クエリパラメータ

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| game | string | ✅ | Game8 Store内で発番された、ゲームのユニークID |
| user | string | ✅ | ゲーム内で発番された、ゲーム内のユーザーユニークID |
| transaction_id | string | ✅ | 取引を一意に特定する識別子 |
| items | string | ✅ | ゲーム内で発番された、購入対象のアイテムID （[？](https://developers.store.game8.jp/ja/faq/#acc-faq-523efe3d)）<br>カンマ区切りで複数指定 |

#### リクエスト例

```json
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
```

#### レスポンス仕様

#### レスポンスボディ

| キー | 型 | 説明 |
| --- | --- | --- |
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| stock | Object[] | 在庫情報 |

#### stockの構造

| キー | 型 | 説明 |
| --- | --- | --- |
| item | string | ゲーム内で発番された、購入対象のアイテムID （[？](https://developers.store.game8.jp/ja/faq/#acc-faq-523efe3d)） |
| total | integer | 総在庫数。無制限の場合は -1 を返す |
| remaining | integer | 残り在庫数。無制限の場合は -1 を返す |
| restock_at | string (ISO8601) \| null | 次回入荷予定日時（予定がある場合）。未定または無制限の場合は null |

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

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

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

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

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

```json
{
	"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詳細

### 注文照会（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/{publisher_slug}/games/{game_slug}/orders/verify` |
| プロトコル | HTTPS |
| コンテンツタイプ | application/json |

> `{publisher_slug}` はパブリッシャーの識別子、`{game_slug}` はゲームの識別子です。Game8, Inc.よりお伝えします。

#### リクエストヘッダー

| キー | 値 | 内容 |
| --- | --- | --- |
| Authorization | Bearer `<ACCESS_TOKEN>` | 認証情報 |
| X-Signature | `<SIGNED_DATA>` | 署名検証用の署名 |

> 署名の生成方法は「1.3. X-Signatureの設定」と同様です。GETリクエストのため、クエリ文字列を署名対象とします。

#### クエリパラメータ

| キー | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| paid_transaction_id | string | ✅ | `/register` APIで使用した `transaction_id` と同一の値。英数字・ハイフン・アンダースコアのみ使用可能。 |

#### リクエスト例

```
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
```

#### レスポンス仕様

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

| キー | 型 | 説明 |
| --- | --- | --- |
| request_id | string | 一意のリクエストID |
| timestamp | string (ISO8601) | レスポンスのタイムスタンプ |
| result_code | string | 結果コード |
| message | string | メッセージ |
| paid_transaction_id | string | 注文のトランザクションID |
| status | string | 注文ステータス（下記参照） |
| item_id | string | パブリッシャー側のアイテムID |
| price | integer | 購入対象アイテムの商品金額（税込・円）。割引適用前の定価。 |
| selling_price | integer | パブリッシャー負担の割引適用後の購入代金（税込・円）。割引がない場合は price と同額。 |
| billing_amount | integer | 購入代金からポイントやクーポン利用等を差し引いた最終的な決済金額（税込・円）。適用がない場合は selling_price と同額。 |
| purchased_at | string (ISO8601) \| null | 購入日時。決済処理中（`pending`）の場合は null |

#### statusの値

| 値 | 説明 |
| --- | --- |
| `pending` | 決済処理中 |
| `payment_confirmed` | 決済確認済み（決済は完了したがアイテム付与処理がまだ完了していない状態） |
| `completed` | 完了（アイテム付与済み） |
| `cancelled` | キャンセル済 |

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

```json
{
  "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"
}
```

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

```json
{
  "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
}
```

#### エラーレスポンス

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

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

| HTTPステータス | result_code | メッセージ | 説明 |
| --- | --- | --- | --- |
| 400 | `PUB2001` | 必須パラメータが不足しています / パラメータが不正です | `paid_transaction_id` が未指定、フォーマット不正、またはパス識別子が不正 |
| 401 | `PUB1002` | 認証または署名検証に失敗しました | アクセストークンまたは署名が不正 |
| 403 | `PUB1003` | 他パブリッシャー・他ゲームの注文にはアクセスできません | 自社以外の注文への照会 |
| 404 | `PUB3001` | 指定された注文が見つかりません | 該当する注文が存在しない |
| 429 | - | Rate limit exceeded. Please try again later. | レート制限超過（60リクエスト/分）。レスポンスボディは `{"error": "..."}` 形式 |
| 500 | `PUB4000` | 予期しないエラーが発生しました | サーバー内部エラー |
| 503 | `PUB4001` | サービスに接続できません | 一時的なネットワーク障害。時間をおいて再試行してください |

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

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

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

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

## 4. エラーハンドリング

### 4.1. エラーコード一覧

| エラーコード | 説明 | 対応策 |
| --- | --- | --- |
| `PUB0000` | 成功 | - |
| `PUB1000` | 不正なリクエストフォーマット | リクエストの構造や必須パラメータを確認し、正しい形式で送信する |
| `PUB1001` | 認証情報が不足している | `Authorization` ヘッダーに正しい `Bearer <ACCESS_TOKEN>` を設定する |
| `PUB1002` | 無効なアクセストークン | アクセストークンの有効期限を確認し、必要に応じて再発行する |
| `PUB1003` | アクセス権限が不足している | APIエンドポイントへの適切な権限があるか確認する |
| `PUB1004` | 署名内容が不一致 | 署名に利用している秘密鍵のシークレットが正しいことを確認する |
| `PUB1005` | 処理済みのリクエスト | 重複した`request_id` を送信しないようにする |
| `PUB2001` | 必須パラメータが不足している | 必須パラメータを確認し、リクエストを修正する |
| `PUB2002` | パラメータの型が無効 | 例: `price` に `string` を渡している場合、整数値に修正する |
| `PUB2003` | パラメータの値が不正 | 許可されていない値や範囲外の値を送信していないか確認する |
| `PUB2004` | 該当するデータが存在しない | 存在する `game` や `user` を指定しているか確認する |
| `PUB2005` | 年齢による購入金額制限の上限に達している | `account_limit.remaining` の値を確認し、制限を超えていないか確認する |
| `PUB2006` | 年齢確認が行われていない | ユーザーにゲーム内での年齢確認を促す |
| `PUB2007` | アイテム販売中止 | ストア側の販売アイテムの調整を営業・開発チームへ問い合わせる |
| `PUB2008` | アカウント停止により購入不可 | - |
| `PUB2009` | アイテムの購入数制限の上限に達している | 購入履歴を確認し、制限を超えていないか確認する |
| `PUB2010` | 前回の取引が未完了のため、一時的に購入できない状態 | 未完了の取引はGame8 Store側で一定時間後に自動的にキャンセルされ、購入可能な状態に戻る。ユーザーには時間をおいて再度購入するよう促す |
| `PUB3001` | 無効な取引ID | `transaction_id` が正しいか確認する |
| `PUB3002` | 指定されたユーザーが存在しない | `user` が正しいか確認する |
| `PUB3003` | 指定されたアイテムが存在しない | `item` を確認し、正しいものを指定する |
| `PUB3004` | 登録済み取引ID | `transaction_id` が正しいか確認する |
| `PUB4000` | サーバー内部エラー | サーバー側の問題の可能性があるため、一定時間後に再試行する |
| `PUB4001` | 一時的なシステム障害 | 再試行する（推奨: 5秒後にリトライ） |
| `PUB5000` | 不明なエラー | 詳細なエラーメッセージを確認し、開発チームへ問い合わせる |
| `PUB6000` | メンテナンス中 | サービス停止中として一定時間後に再試行する |

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

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

### 4.3. リトライポリシー

| エラーコード | リトライ間隔 | 最大リトライ回数 | 備考 |
| --- | --- | --- | --- |
| `PUB4000` | 5秒後 | 3回 | サーバー内部エラーのため、短時間で解消する可能性あり |
| `PUB4001` | 10秒後 | 5回 | 一時的なシステム障害のため、長めの間隔を空ける |
| `PUB5000` | なし | 0回 | 不明なエラーは即時報告 |

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