REST API
以下是面向游戏服务端的 REST API，预期由游戏服务端发起调用。
这些 REST API 都是必接的。
API 端点
服务端 REST API 的端点，参见术语表中的 API Endpoint。
API 规范
HTTP Protocol
服务端 REST API 支持 HTTP/2 和 HTTP/1.1，建议游戏侧优先使用支持 HTTP/2 的网络库。
Content-Type
服务端 REST API 的请求和响应，Content-Type 均使用 application/json。
游戏侧应当判断响应的 Content-Type 为 application/json 时，才解析 response body 为 JSON。
HTTP Status Code
服务端 REST API 将 HTTP status code 分为三类，分别为 200, 4xx, 5xx。
为了有利于服务监控、日志分析与问题排查，API 会尽可能地使得 status code 贴合 HTTP 协议中的语义。
4xx 和 5xx 对应业务流程的错误场景，此时 response body 对应 ErrorResponse。
200
API 调用成功时，会返回 HTTP 200 OK。
此时 response body 的结构对应每个 API 的 Response 部分。
200 对应业务流程的 happy path，即正常业务流程中需要考虑的场景。
4xx
对应问题根源在客户端侧的错误。
4xx 的错误，通常是不可重试的（429 除外）。
API 会返回以下 4xx 的 status code：
| Status Code | Retryable | Description |
|---|---|---|
| 400 Bad Request | False | 请求不合法，例如请求格式不正确、缺少必需的 header 或字段等等。 |
| 401 Unauthorized | False | 对 Authorization header 中的信息验证不通过。 |
| 403 Forbidden | False | 身份验证不通过，例如登录 token 已失效，或账号被封禁、充值达到限额。 |
| 405 Method Not Allowed | False | HTTP method 不正确，例如需要用 POST 却用了 GET。 |
| 415 Unsupported Media Type | False | 没有指定正确的 Content-Type。 |
| 429 Too Many Requests | True | 请求过于频繁，被服务端限流了。 |
5xx
对应问题根源在服务端侧的错误。
5xx 的错误，通常是可重试的。
API 会返回以下 5xx 的 status code：
| Status Code | Retryable | Description |
|---|---|---|
| 500 Internal Server Error | True | API 内部遇到了预期之外的错误，例如程序内部的 bug，访问数据库/缓存失败，调用外部第三方服务失败等等。 |
| 503 Service Unavailable | True | API 当前无法提供服务，例如停服维护，所依赖的其他服务当前不可用等等。 |
ErrorResponse
API 调用失败时（即非 HTTP 200），HTTP response body 中返回的统一数据结构，是一个 JSON Object，包含以下属性：
| Property | Type | Description |
|---|---|---|
| error | string | 业务错误类型，可用于记录日志或数据埋点。 例如 internal_error |
| message | string | 错误描述信息。 例如 服务器内部错误，请稍后再试 |
请求鉴权
服务端 REST API 对请求进行鉴权的方式，是 HTTP Request Signing。
签名方式请阅读 签名算法。
签名过程中使用的 Game ID 由世游分配。签名使用的私钥，使用世游为每个游戏项目生成的 Secret Key。
如果请求的签名验证不通过，世游的 API 端点会返回 HTTP 401 Unauthorized。
游戏侧应当重视 Secret Key 的安全性，将其妥善保管，严格控制密钥的访问权限，并安全地分发至游戏服务器的运行环境。
请注意，Secret Key 一定不能放在客户端。
内购与支付
创建订单
POST /v1/server/create-order创建游戏内购的订单，发起一个购买 + 支付的流程。
Request
| Property | Type | Required | Description |
|---|---|---|---|
| reference_id | string[8,64] | True | 用于标识创建订单请求的唯一 ID。建议使用游戏侧的订单号。 |
| combo_id | string[1,64] | False | 发起购买的用户的唯一标识。参见术语表中的 Combo ID。 当 platform != weixin 时，该字段必传。 |
| product_id | string[1,64] | True | 在世游 SDK 管理后台配置的商品 ID。参见术语表中的 Product。 |
| platform | string[1,32] | True | 客户端的运行平台。取值见术语表中的 Platform。 |
| notify_url | string[14,255] | True | 游戏侧异步接收发货通知的地址。参见术语表中的 Notify URL。 |
| quantity | integer[1,100] | False | 要购买的商品的数量，默认为 1 。 |
| meta | object | False | 订单的元数据。是一个 JSON object。 |
| context | string[1,255] | False | 订单上下文，在发货通知中透传回游戏。 |
meta
通常情况下，订单元数据 meta 并非订单支付的主流程中所必需的。
meta 可包含以下字段，主要用于数据分析与查询，游戏服务端应当尽量提供。
| Property | Type | Required | Description |
|---|---|---|---|
| zone_id | string[1,64] | False | 游戏大区 ID。 |
| server_id | string[1,64] | False | 游戏服务器 ID。 |
| role_id | string[1,64] | False | 游戏角色 ID。 |
| role_name | string[1,64] | False | 游戏角色名。 |
| role_level | integer | False | 游戏角色的等级。 |
| weixin_openid | string[1,128] | False | 微信用户在商户对应 appid 下的唯一标识，当 platform 为 weixin 时，该字段必传。 |
| weixin_appid | string[1,32] | False | 微信小游戏的 appid，当 platform 为 weixin 时，该字段必传。 |
如果 platform == "weixin" 则 meta.weixin_openid、meta.weixin_appid 必须有值。
如果 platform != "weixin" 则 combo_id 必须有值。
Response
| Property | Type | Description |
|---|---|---|
| order_id | string[1,64] | 世游服务端创建的，标识订单的唯一 ID。 |
| order_token | string[1,1024] | 世游服务端创建的订单 token，用于游戏客户端调用 Combo SDK 发起购买流程。 |
| expires_at | integer | 订单失效时间。Unix timestamp in seconds。 |
中宣部防沉迷
以下接口仅用于中宣部防沉迷系统的上下线数据上报，以满足监管合规的要求。
session_id 由游戏侧自行生成，每个 session_id 只要能够标识一次上下线就可以，不要复用。
最简单的生成 session_id 的方式，就是在玩家上线时生成一个 UUID。
进入游戏
POST /v1/server/enter-game通知世游服务端玩家进入游戏世界（上线）。
Request
| Property | Type | Required | Description |
|---|---|---|---|
| combo_id | string[1,64] | True | 聚合用户标识。 |
| session_id | string[1,64] | True | 游戏会话标识。单次游戏会话的上下线动作必须使用同一会话标识上报。 |
Response
仅返回一个 empty JSON object。示例：
{}
离开游戏
POST /v1/server/leave-game通知世游服务端玩家离开游戏世界（下线）。
Request
| Property | Type | Required | Description |
|---|---|---|---|
| combo_id | string[1,64] | True | 聚合用户标识。 |
| session_id | string[1,64] | True | 游戏会话标识。单次游戏会话的上下线动作必须使用同一会话标识上报。 |
Response
仅返回一个 empty JSON object。示例：
{}