1. 概述

卓信服务为CP提供卓信ID校验、群对群更新转换等服务,用于实现跨CP的数据应用。

2. 服务端API参考

接口域名: zxid-api.mobileservice.cn(生产环境)、sandbox-zxid-api.mobileservice.cn(沙盒环境)
接口协议: HTTPS、JSON
接口列表:

  • /data/ConvertZIDGroup 群对群转换
  • /verify/VerifyZIDs 验证 ZID 接口

公共请求参数:

参数名 类型 说明
Access-Key-Id string 通过管理后台申请分配的密钥标识。 该参数必须先向卓信官方申请才能使用,申请流程见“使用指南 -> 申请流程”
Partner-Id string 当前用户的 PartnerId 。 该参数必须先向卓信官方申请才能使用,申请流程见“使用指南 -> 申请流程”
Signature string 信息签名字符串,参考签名方式。
Signature-Method string 信息签名方法,目前固定为 HMAC-SHA256 。
Signature-Nonce string 64 字节以内的随机串,用于防止重放攻击,每次请求必须提供不同的值。
Timestamp string UTC时间戳,从UTC1970年1月1日0时0分0秒起至现在的总秒数。如 1632634877。
注:公共请求参数放置于 HTTP Request Header 请求头中,参数名与值大小写敏感。

签名方式:

  1. 使用请求参数构造标准请求字符串(Standard Query String),包括文档中的“公共请求参数”,但不包括“公共请求参数”中的 Signature 参数。将标准请求字符串进行排序,此排序是大小写敏感的,请使用标准文档中的大小写格式。
    具体排序示例: Access-Key-Id, Partner-Id, Signature-Method, Signature-Nonce, Timestamp 。
    将参数值使用英文等号 & 进行连接,即得到标准请求字符串。
    示例:accesskeyid&partnerid&HMAC-SHA256&67a4ac92-c53e-440d-b777-2b14f7a61a5c&1632634877

  2. 按照 RFC2104 对上面的 StringToSign 字符串计算签名 HMAC 值。计算签名时使用的 Key 就是用户持有的 AccessKeySecret ( 该参数必须先向卓信官方申请才能使用,申请流程见“使用指南 -> 申请流程”),使用的哈希算法为 SHA256 。

  3. 按照标准 Base64 编码规则,把上面的 HMAC 值编码为字符串,得到签名值(Signature)。
  4. 将得到的签名值作为 Signature 请求头的值,即完成请求签名的过程。

注意事项:
时间戳 Timestamp 不能偏差过多,目前允许误差为 5 分钟。

1 ConvertZIDGroup : 群对群转换

群对群更新转换为各 CP 方提供了一种批量地将失效卓信 ID 转换为最新卓信 ID 的方法,目前限定单次转换的卓信ID数量不少于 1000 个、不大于 10w 个(建议先在沙盒环境测试,沙盒环境限制为单次转换的卓信ID数量不少于 2 个、不大于 10w 个,沙盒环境与正式环境数据不互通)。服务端接受请求后会对收到的卓信 ID 进行合法性和是否过期进行检查,要求 99% 以上的 ID 应当为合法且过期的(考虑合作方服务器时间不同步,存在合作方判断过期,实际未过期的小概率可能性),才会认为此次请求有效。

最大响应时间:1w ZID 条件下 2s 内返回、10w ZID 条件下 10s 内返回。

接口名 ConvertZIDGroup
路径 /data/ConvertZIDGroup
请求参数 zids List<String> 待查询 ZID 群数组,数量范围:[1000, 10w]
返回参数 zids

jointDebugRemaining
List<String>

int
查询后最新的 ZID 群数组,按过期时间排序。

当该请求为正式环境联调模式请求时,将返回该值,表明用户还剩余多少次联调请求限额。

请求 / Request :

{
    "zids": [
        "Z01-1631983930-YUYZOgAWp64tVh1b-3662",
        "Z01-1632005937-YUZvMQAM0O6M7zYx-CCA4",
        "Z01-1632047870-YUcS/gCxlxlLbzSB-B6BF",
        "Z01-1631983641-YUYYGQBcsunUsZvX-E1FB",
        "Z01-1631981930-YUYRagDuJV072tyx-E81D",
        "Z01-1632037734-YUbrZgAd3bZUfNmE-A1EC",
        "Z01-1631984838-YUYcxgArlLU3XB+6-F244",
        "Z01-1631989788-YUYwHAC6CkUtLDMj-34C5",
        "Z01-1632031977-YUbU6QDfWMMrI7+8-1EC2",
        // ...
    ]
}

返回 / Response :

{
    "zids": [
        "Z01-1642462621-YcLkjaIiuala89Az-J1ck",
        "Z01-1642421712-YcKJawklLa81jU-a-Pqkz",
        "Z01-1642169267-YcKjas71jNquaICP-2c1M",
        // ...
    ],
    "jointDebugRemaining": 1000
    // 当该请求为正式环境联调模式请求时,将返回该值,表明用户还剩余多少次联调请求限额。
}

注:

  1. POST 请求,请求参数使用 JSON 编码。
  2. 接口请求参数与值均为大小写敏感。
  3. 请求中待查询的有效 ZID 数组大小严格要求在范围内,不能过多或过少。
  4. 99% 以上的 ZID 应当是合法且过期的,在满足上述条件的情况下,未过期 ZID 在 Response 中原封不动返回。
  5. 在正式环境联调模式下,请求 ZID 数量最少 10 个,详细规则参考 正式环境联调模式

正式环境联调模式

考虑到有初期接入客户一开始正式环境的 ZID 不足 1000 个,无法通过常规手段调用群对群翻译接口。
为了保障初期接入,我们为客户开设一个短期的白名单:

  • 为期 7 天的正式环境联调模式
  • 为每个客户提供包含 100 个过期 ZID 包作为联调权益包,用于正式环境联调模式
  • 对于包含包内 ZID 的请求,降低查询 ID 数下限值 (10个)
  • 计次:针对特权包请求,只能调用有限次数(目前每个服务商 1000 次)

VerifyZIDs : 验证 ZID 接口

验证 ZID 接口接受一组 ZID 输入(输入数量 ≤ 10w ),按原顺序返回传入的 ZID 的验证结果。

接口名 VerifyZIDs
路径 /verify/VerifyZIDs
请求参数 zids List<String> 待验证 ZID 数组,大小范围:≤ 10w
返回参数 realZIDs

fakeZIDs
List<String>

List<String>
验证通过的 ZID 数组

验证未通过的 ZID 数组

请求 / Request :

{
    "zids": [
        "Z01-1631983930-YUYZOgAWp64tVh1b-3662",
        "Z01-1632005937-YUZvMQAM0O6M7zYx-CCA4",
        "Z01-1632047870-YUcS/gCxlxl12345-1234",
        "abcd1234",
        "",
        " ",
        "abcd1234",
        // ...
    ]
}

返回 / Response :

{
    "realZIDs": [
        "Z01-1631983930-YUYZOgAWp64tVh1b-3662",
        "Z01-1632005937-YUZvMQAM0O6M7zYx-CCA4",
        // ...
    ],
    "fakeZIDs": [
        "Z01-1632047870-YUcS/gCxlxl12345-1234",
        "abcd1234",
        "",
        " ",
        "abcd1234",
        // ...
    ]
}

3. 群对群转换

卓信ID群对群转换服务是为了便于各CP方维护基于卓信ID生成的用户群信息,支持数字营销、统计分析等应用场景而提供的失效卓信ID更新服务,该服务不可用于单个个体的卓信ID转换,各CP不得尝试通过变更单一ID来变相获取单一卓信ID的转换能力。卓信服务将通过定期巡检方式进行检查,对于违规CP,我们将停止提供相应的群对群转换服务。

开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询