发放奖励

POST /v1/grant-reward

向指定合作方用户已绑定的游戏角色发放活动奖励。奖励将通过游戏内邮件发送到角色的邮箱中。

警告

此接口为 同步接口，调用后即返回发放结果。合作方无需额外轮询或等待回调。

Request

Property	Type	Required	Description
game_id	`string`	True	游戏 ID。
event_id	`int`	True	活动 ID。由世游运营提供。
partner_user_id	`string`	True	合作方平台的用户唯一标识。
server_id	`int`	True	游戏服务器 ID。必须与绑定记录中的服务器一致。
role_id	`string`	True	角色 ID。必须与绑定记录中的角色一致。
reward_bundle_id	`string`	True	奖励包 ID。由世游运营提供，必须是该活动配置中已存在的礼包。
partner_grant_reward_id	`string`	True	合作方侧的奖励发放唯一标识。合作方需要保证其全局唯一，至少要保证在同一游戏下唯一。

示例：

{
  "game_id": "example_game",
  "event_id": 1001,
  "partner_user_id": "user_12345",
  "server_id": 10001,
  "role_id": "1054832",
  "reward_bundle_id": "bundle_spring_gift",
  "partner_grant_reward_id": "grant_67890"
}

Response

发放成功时返回空 JSON 对象：

{}

合作方通过 HTTP Status Code 为 200 即可确认发放成功。

失败场景以 ErrorResponse 返回，发放结果也可随时通过查询奖励确认。

提示

建议合作方为每笔奖励生成全局唯一的 partner_grant_reward_id，例如使用 UUID 或业务订单号。

警告

重试发放时必须使用相同的 partner_grant_reward_id。如果使用新的 partner_grant_reward_id，会被视为一笔新的发放请求，可能导致重复发放。

Errors

Error	Description
invalid_request	请求参数缺失或格式错误，或指定的活动 / 奖励包不存在。具体原因请查看 `message` 字段。
invalid_signature	签名验证不通过。
partner_disabled	合作方已被禁用。
binding_not_found	该用户在该游戏中未绑定角色。
event_not_active	活动不在有效期内或状态不是进行中。
event_in_testing	活动处于测试中，非内部测试员不可参与。
claim_limit_exceeded	该角色在该奖励包上的领取次数已达上限。
duplicate_grant	重复的发放请求（相同 `partner_grant_reward_id` 且已成功发放），不会重复发放，可视为已发放成功。
conflict_grant	当前有其他发奖请求正在处理中（同一角色与奖励包上的并发请求），可稍后重试。
failed_grant	奖励发放失败且不可重试，使用相同 `partner_grant_reward_id` 再次调用仍会返回此错误。
internal_error	服务端内部错误。

Request​

Response​

Errors​

Request

Response

Errors