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] | True | 发起购买的用户的唯一标识。参见术语表中的 Combo ID。 |
| 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 | 游戏角色的等级。 |
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。 |
Errors
| Error | Description |
|---|---|
| internal_error | API 内部遇到了预期之外的错误，例如程序内部的 bug，访问数据库失败，调用外部第三方服务失败等等。 |
| invalid_request | 请求参数缺失或错误。具体错误原因，请检查错误信息。 |
| game_iap_disabled | 游戏内购功能已关闭。 |
中宣部防沉迷
以下接口仅用于中宣部防沉迷系统的上下线数据上报，以满足监管合规的要求。
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。示例：
{}
Errors
| Error | Description |
|---|---|
| invalid_request | 请求参数缺失或错误。具体错误原因，请检查错误信息。 |
离开游戏
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。示例：
{}
Errors
| Error | Description |
|---|---|
| invalid_request | 请求参数缺失或错误。具体错误原因，请检查错误信息。 |
短信验证码
以下接口用于发送并验证世游通行证验证码，适用于游戏内敏感操作的确认场景（例如设置安全密码）。验证码会发送至玩家世游通行证账号绑定的手机号。
短信验证码 API 是可选接入的，并非必接。接入前需要联系世游为游戏配置发送验证码的 action。
发送验证码
POST /v1/server/send-otp发送世游通行证验证码。
Request
| Property | Type | Required | Description |
|---|---|---|---|
| combo_id | string[1,64] | True | 世游服务端生成的聚合用户标识。参见术语表中的 Combo ID。 |
| channel | string[1,64] | False | 发送验证码通道，不传时默认为 sms。目前仅支持 sms（手机短信通道），未来可能增加 email 通道。 |
| action | string[1,64] | True | 发送验证码的目标行为，由世游发行平台创建并管理。 |
| meta | object | False | 发送方元数据。是一个 JSON object。 |
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 | 游戏角色的等级。 |
示例：
{
"combo_id": "1260206621270001",
"channel": "sms",
"action": "change_security_password",
"meta": {
"zone_id": "1",
"server_id": "1",
"role_id": "129142716",
"role_name": "又槑了耶",
"role_level": 3
}
}
Response
| Property | Type | Description |
|---|---|---|
| mobile | string[1,64] | 掩码后的手机号，仅当 channel 为 sms 时有值。 |
| otp_ttl | integer | 验证码有效期，单位秒。 |
| otp_cooldown | integer | 重新发送验证码的冷却时间，单位秒。 |
示例：
{
"mobile": "138******88",
"otp_ttl": 300,
"otp_cooldown": 60
}
Errors
| Error | Description |
|---|---|
| internal_error | API 内部遇到了预期之外的错误，例如程序内部的 bug，访问数据库失败，调用外部第三方服务失败等等。 |
| invalid_request | 请求参数缺失或错误。具体错误原因，请检查错误信息。 |
| invalid_tenant | 游戏尚未开通短信验证码功能，或已被停用。 |
| invalid_channel | 未定义或被禁用的 channel。 |
| invalid_action | 未定义或被禁用的 action。 |
| combo_id_not_found | combo_id 不存在。 |
| account_not_found | 未找到与 combo_id 对应的世游通行证账号。 |
| send_otp_rate_limited | 发送验证码请求的频率超出了通行证系统限制。 |
| rate_limited | 操作过于频繁，一般是因为重复提交导致。 |
验证验证码
POST /v1/server/verify-otp验证世游通行证验证码。
验证成功后验证码立即失效，不可重复使用。
Request
| Property | Type | Required | Description |
|---|---|---|---|
| combo_id | string[1,64] | True | 世游服务端生成的聚合用户标识。参见术语表中的 Combo ID。 |
| channel | string[1,64] | False | 发送验证码通道，需与发送时一致，不传时默认为 sms。目前仅支持 sms（手机短信通道），未来可能增加 email 通道。 |
| action | string[1,64] | True | 发送验证码的目标行为，需与发送时一致。 |
| otp | string[6] | True | 验证码，6 位数字。 |
示例：
{
"combo_id": "1260206621270001",
"channel": "sms",
"action": "change_security_password",
"otp": "658741"
}
Response
| Property | Type | Description |
|---|---|---|
| valid | bool | 是否验证通过。true 验证通过。false 验证失败，用户输入的验证码与系统生成的验证码不匹配，可能是由于输入错误或验证码已过期，建议用户重新检查输入的验证码。 |
示例：
{
"valid": true
}
Errors
| Error | Description |
|---|---|
| internal_error | API 内部遇到了预期之外的错误，例如程序内部的 bug，访问数据库失败，调用外部第三方服务失败等等。 |
| invalid_request | 请求参数缺失或错误。具体错误原因，请检查错误信息。 |
| invalid_tenant | 游戏尚未开通短信验证码功能，或已被停用。 |
| invalid_channel | 未定义或被禁用的 channel。 |
| invalid_action | 未定义或被禁用的 action。 |
| combo_id_not_found | combo_id 不存在。 |
| account_not_found | 未找到与 combo_id 对应的世游通行证账号。 |
| verify_otp_limited | 验证码验证失败次数已达到上限，需重新获取新的验证码进行验证。 |
| rate_limited | 操作过于频繁，一般是因为重复提交导致。 |
微信小游戏
以下接口仅适用于微信小游戏。更多微信小游戏相关功能，参见 微信小游戏 专栏。
获取接口调用凭证
POST /v1/server/minigame-weixin-access-token获取微信小游戏的接口调用凭证，供游戏服务端调用微信服务端 API 使用。
接口调用凭证由世游服务端统一维护和刷新，游戏侧无需自行调用微信接口获取。
游戏服务端应当缓存接口调用凭证，缓存时间 1 分钟，按照 1 次/分钟 的频率请求该 API 获取并刷新缓存。
Request
| Property | Type | Required | Description |
|---|---|---|---|
| app_id | string[1,32] | True | 微信小游戏的 AppID。必须是当前游戏配置的微信小游戏应用。 |
Response
| Property | Type | Description |
|---|---|---|
| app_id | string | 微信小游戏的 AppID，与请求中的 app_id 一致。 |
| access_token | string | 微信小游戏的接口调用凭证。 |
示例：
{
"app_id": "wx1234567890abcdef",
"access_token": "89_hFEUOJEqvA9WM1JJVdyDApVA1E1ldlXBjEBQxxxxxxxx"
}
Errors
| Error | Description |
|---|---|
| invalid_request | 请求参数缺失或错误。具体错误原因，请检查错误信息。 |
| invalid_weixin_app_id | 无效的 app_id。该应用不存在，或未配置为当前游戏的微信小游戏应用。 |
| internal_error | API 内部遇到了预期之外的错误，例如程序内部的 bug，访问数据库/缓存失败等等。 |