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时根据请求体的内容计算摘要。摘要使用密钥的secret通过HMAC-SHA256算出。

1. 将算出的摘要进行Base64编码，并设置到请求头的X-Signature中。

签名的验证方法

1. GET时根据查询字符串、POST时根据请求体的内容计算摘要。摘要使用密钥的secret通过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。"
}

响应示例（失败 - 账号因封禁等原因处于非活跃状态）

{
  "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通知的订单状态可通过本API进行查询，查询时使用paid_transaction_id 。
/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. 重试策略

请参考此错误处理列表，实现适当的错误处理。