概览

以下是面向合作方的 Hub REST API，预期由合作方服务端发起调用。

API 端点

Hub API 的端点为：

https://hub-api.seayoo.com

提示

仅提供 HTTPS 端点，不提供 HTTP 端点。

Hub API 的请求和响应，Content-Type 均使用 application/json，字符编码为 UTF-8。

所有 API 请求必须携带 Authorization header，使用 SEAYOO-HMAC-SHA256 签名算法进行身份认证。

Hub API 将 HTTP Status Code 分为三类：

API 调用成功。Response Body 的结构对应每个 API 的 Response 部分。

对应问题根源在客户端侧的错误，通常不可重试（409 / 429 除外）。

Status Code	Retryable	Description
400 Bad Request	False	请求不合法，例如请求格式不正确、缺少必需的字段等。
401 Unauthorized	False	签名验证不通过。
403 Forbidden	False	合作方已禁用或无权限访问该资源。
404 Not Found	False	请求的资源不存在。
405 Method Not Allowed	False	HTTP 方法不正确。
409 Conflict	True	并发冲突，例如同一角色与奖励包上有其他发放请求正在处理中，可稍后重试。
429 Too Many Requests	True	请求过于频繁，被限流。

对应问题根源在服务端侧的错误，通常可重试。

Status Code	Retryable	Description
500 Internal Server Error	True	服务端内部错误。
503 Service Unavailable	True	服务当前不可用。

API 调用失败时（非 HTTP 200），Response Body 返回统一的 JSON 结构：

Property	Type	Description
error	`string`	错误类型标识，可用于程序判断和日志记录。
message	`string`	错误的描述信息，便于排查问题。

示例：

{
  "error": "binding_not_found",
  "message": "No binding found for the specified partner user and game"
}

所有 API 响应都会在 HTTP Header X-Trace-Id 中包含一个请求跟踪 ID，便于联调时定位问题。如遇到异常情况，请将此跟踪 ID 提供给世游技术对接人。