抖音开放平台Logo
开发者文档
控制台
  • 接入前准备
  • SPI签名机制说明
  • 生成 client-token
  • 生活服务消息推送
  • 加密字段解密方法
  • 通用能力
  • 餐饮
  • 大交通
  • 酒旅
  • 综合
  • 历史版本文档(不推荐)
  • SPI签名机制说明

    收藏
    我的收藏

    签名机制​

    请求到服务商的接口中存在两套签名,这两套签名服务商任选其中一种进行校验都可以,推荐校验 header 中的签名,因为安全性会更高一些。两个签名的计算方式有些微差别。​

    签名规则(new)​

    url 中的参数
    参数名称
    参数类型
    参数描述
    必需
    client_key
    string
    服务商的client_key
    timestamp
    string
    时间戳, 单位毫秒
    sign
    string
    生成签名时无视该字段
    header 中的 sign 参数
    调用路径为抖音 调用 服务商的接口,会传递以下内容在header中​
    参数名称
    参数类型
    参数描述
    必需
    x-life-clientkey
    string
    服务商的client_key
    是 无用处 仅作应用标识用
    x-life-sign
    string
    新签名
    是 验签用
    该 sign 的生成方式:​
    1、以三方服务商的 client_secret 开头; 然后将除 sign 之外的 URL 参数以 key=value 的形式按 key 的字典升序排列; 若为 POST 请求, 还需要加上 HTTP 的 BODY, key 固定为 http_body(http_body 的内容不参与排序,加到最后)。最后所有的这些项以字符'&'串联起来即为待签名内容 str1. 发码接口的示例如下(假设 client_secret 为 yyyyyy):​
    2、str1 的内容是 yyyyyy&client_key=xxxxxx&timestamp=1624293280123&http_body=zzzzzz 【注意:client_key是URL参数中动态获取,请不要直接固定写死,以免造成验签失败】​
    3、然后将待签名内容 str1计算 sha256 的值, 得到的结果即为 sign。​
    4、抖音将用于签名生成的 httpBody 以[]byte 类型请求服务商,服务商请不要将[]byte 反序列化成 object 再序列化 string 用于签名校验。这样会导致 json 中的字段顺序与抖音不符,同时若抖音侧将 httpBody 进行改动,也会导致签名校验不通过。​

    签名规则(old)​

    说明:​

    1、旧签名规则是指之前从抖音开放平台(open.douyin.com)接入网页应用及接口所使用的签名规则,迁移至服务商平台(partner.open-douyin.com)后,需要改成上方新的签名规则,
    2、如不涉及迁移,可忽略该部分。​
    url 中的 sign 参数(之前的签名方式)
    如果服务商是新入驻/新接入的服务商,不需要关注该签名方法。​
    调用路径为抖音 调用 服务商的接口,会传递签名&公共 url 参数​
    参数名称
    参数类型
    参数描述
    必需
    client_key
    string
    服务商的client_key
    timestamp
    string
    时间戳, 单位毫秒
    sign
    string
    签名
    sign 的生成方式:​
    1、以三方服务商的 client_secret 开头; 然后将除 sign 之外的 URL 参数以 key=value 的形式按 key 的字典升序排列; 若为 POST 请求, 还需要加上 HTTP 的 BODY, key 固定为 http_body(http_body 的内容不参与排序,加到最后)。最后所有的这些项以字符'&'串联起来即为待签名内容 str1. 发码接口的示例如下(假设 client_secret 为 yyyyyy):​
    2、str1 的内容是 yyyyyy&client_key=xxxxxx&timestamp=1624293280123&http_body=zzzzzz 【注意:client_key是URL参数中动态获取,请不要直接固定写死,以免造成验签失败】​
    3、然后将待签名内容 str1 计算 md5 值, 得到的结果即为 sign​
    4、抖音将用于签名生成的 httpBody 以[]byte 类型请求服务商,服务商请不要将[]byte 反序列化成 object 再序列化 string 用于签名校验。这样会导致 json 中的字段顺序与抖音不符,同时若抖音侧将 httpBody 进行改动,也会导致签名校验不通过。​

    选择校验哪个签名​

    服务商一开始使用的平台为服务商后台​
    两种签名都可以校验,从安全性的角度考虑,建议使用新的签名规则(header 中的签名)进行校验。​
    服务商一开始使用的企业号开放接口(飞书文档),且从未使用过新的服务商平台(当前在线平台)​
    只能校验老的签名(url 中的签名),​
    服务商一开始使用的企业号开放接口(飞书文档),且根据指引迁移到了新的服务商平台(当前在线平台),代码中使用的应用的 client_key 换成了新的本地生活应用的 app_id(client_key)​
    只能校验新的签名(header 中的签名)​

    为什么选择使用哪个签名存在上述规则?​

    服务商之前申请的应用都是在抖音开放平台直接申请的网站应用,迁移到服务商后台后新的本地生活应用的 app_id(client_key)和之前的 client_key 不相同。这一点在调用 spi 的场景里体现在 url 中的 client_key 和新的 client_key 中:​
    服务商未做过迁移:​
    url 中的 client_key 和 header 中的 x-life-clientkey 相同。​
    如果服务商不清楚迁移为什么动作,则也适用该规则。​
    服务商做过迁移:​
    url 中的 client_key 和 header 中的 x-life-clientkey 不同,header 中的 client_key 为迁移后的服务商平台上生活服务应用的 ck。​