创建免授权用户

创建免授权用户

简要描述

通过商户侧用户唯一标识 third_uid 在盟主平台创建或获取对应的盟主用户，并返回盟主平台用户 uid 和免授权访问凭证 atom。

适用于商户已有自己的用户体系，希望将商户用户和盟主平台用户建立映射关系，再进入盟主播放页或查询该用户观看数据的场景。

接口信息

项目	内容
接口 URL	`https://api.zmengzhu.com/business/v1/user/createThirdUser`
请求方式	`POST`
请求 Content-Type	`application/x-www-form-urlencoded`
返回格式	`JSON`
访问权限	主账号可用，子账号不可用

请使用表单方式提交 POST Body，不要使用 raw JSON。当前接口按表单参数读取请求体，使用 JSON 可能导致服务端读取不到参数，或导致签名字符串和实际请求不一致。

公共 Query 参数

参数名	是否必须	类型	说明
`appid`	是	string	商户应用 ID，由盟主平台提供
`expired`	建议	int	请求过期时间，10 位秒级 Unix 时间戳，建议设置为当前时间后 5 到 10 分钟
`sign`	是	string	请求签名，32 位 MD5 字符串

expired 如果传入，必须大于服务端当前时间。expired、URL query 或 POST 表单参数发生变化后，都需要重新生成 sign。

POST 表单参数

参数名	是否必须	类型	说明
`third_uid`	是	string	商户侧用户唯一标识。同一个 `appid` 下建议保持唯一，例如商户自己的用户 ID、会员 ID、openid 等
`nickname`	是	string	用户昵称，长度 1 到 16 个字符
`avatar`	是	string	用户头像完整 URL

注意：昵称字段名是 nickname，不是 name。旧文档中的 name 是错误字段。

签名关键点

本接口属于 api.zmengzhu.com 下的业务 API，使用业务 API 签名规则。

签名时需要注意：

待签名 URL 从域名开始，不包含 http:// 或 https://。
URL query 中不包含 sign，例如 appid=10000001&expired=1999999999。
POST 表单参数按参数名升序排序后，直接拼接 key + value。
POST 参数参与签名时使用原始值，不使用 URL encode 后的值。
sign 不参与签名，生成后再追加到最终请求 URL。
最终请求 Body 请使用 application/x-www-form-urlencoded 表单提交。

示例签名过程：

urlSuffix:
api.zmengzhu.com/business/v1/user/createThirdUser?appid=10000001&expired=1999999999

POST 表单参数:
nickname=微信用户
third_uid=user-001
avatar=https://example.com/avatar.png

POST 参数按 key 升序排序:
avatar
nickname
third_uid

sortString:
avatarhttps://example.com/avatar.pngnickname微信用户third_uiduser-001

secret_key:
secret

signSource:
api.zmengzhu.com/business/v1/user/createThirdUser?appid=10000001&expired=1999999999avatarhttps://example.com/avatar.pngnickname微信用户third_uiduser-001secret

sign:
ff3ed927e8c800ce843f38ba7d1d6f59

请求示例

POST https://api.zmengzhu.com/business/v1/user/createThirdUser?appid=10000001&expired=1999999999&sign=ff3ed927e8c800ce843f38ba7d1d6f59
Content-Type: application/x-www-form-urlencoded

nickname=%E5%BE%AE%E4%BF%A1%E7%94%A8%E6%88%B7&third_uid=user-001&avatar=https%3A%2F%2Fexample.com%2Favatar.png

返回示例

成功返回：

{
  "code": 200,
  "msg": "ok",
  "data": {
    "uid": 12345678,
    "atom": "xxxxxx"
  }
}

错误返回示例：

{
  "code": 20001,
  "msg": "签名校验失败",
  "data": {}
}

返回字段说明

字段	类型	说明
`code`	int	状态码，`200` 表示成功
`msg`	string	返回信息
`data.uid`	int	盟主平台用户 UID
`data.atom`	string	免授权访问凭证，可用于播放页免授权访问

使用说明

third_uid 是商户侧用户标识，盟主平台会根据 appid + third_uid 建立或查找对应的盟主用户。后续商户可使用同一个 third_uid 获取同一个盟主平台用户 uid。

atom 可用于免授权进入播放页。播放页地址通常为：

https://播放域名/play/{ticket_id}?atom=xxxxxx&mzuid=12345678&i=12345678

其中 mzuid 和 i 使用本接口返回的 uid。

常见问题

可以使用 JSON Body 吗

不建议。请使用 application/x-www-form-urlencoded 表单提交。使用 JSON Body 时，服务端可能读取不到 POST 参数，导致签名校验失败或参数校验失败。

nickname 可以写成 name 吗

不可以。接口实际校验字段为 nickname，不是 name。

avatar 中的空格会影响签名吗

会。签名使用的参数值必须和实际请求提交的参数值完全一致。比如 https:// 被写成 https: //，会被视为不同内容，导致签名失败或头像地址错误。

返回 auth failed 怎么排查

auth failed 通常表示 appid 未通过认证、API 服务被禁用、商户账号状态异常或权限不匹配。请先确认 appid 和 secret_key 是否匹配，并确认该 appid 在线上处于启用状态。

返回签名校验失败怎么排查

请重点检查：

URL query 是否和签名时完全一致，尤其是 appid、expired。
签名时是否误把 sign 放进待签名内容。
POST 参数是否按 key 升序排序后拼接。
POST 参数名是否为 nickname、third_uid、avatar。
POST 参数值是否和实际请求 Body 完全一致。
请求 Body 是否使用 application/x-www-form-urlencoded。

免授权-创建免授权用户