设备风险查询API
Updated at：2025-08-20
概述
设备风险查询API是基于百度昊天镜-设备指纹服务，提供查询设备指纹ID，以及设备设备风险标签。
如果您是初次调用百度智能云产品的API，可以观看API入门视频指南，快速掌握调用API的方法。
接口规范
URL
| 项目 | 解释 |
|---|---|
| 地址 | https://afd.baidubce.com/rcs/factor-saas |
| 说明 | 根据输入参数给出设备指纹ID和设备风险标签。 |
| 请求方式 | Https POST |
认证机制
所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成，均为字符串。 对于每个HTTP请求，使用下面所描述的算法生成一个认证字符串，提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为：
bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}
- version是正整数。
- timestamp是生成签名时的UTC时间。
- expirationPeriodInSeconds表示签名有效期限。
- signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号（;）分隔，如host;x-bce-date。列表按照字典序排列。（本API签名仅使用host和x-bce-date两个header）
- signature是256位签名的十六进制表示，由64个小写字母组成。
当百度智能云接收到用户的请求后，系统将使用相同的SK和同样的认证机制生成认证字符串，并与用户请求中包含的认证字符串进行比对。如果认证字符串相同，系统认为用户拥有指定的操作权限，并执行相关操作；如果认证字符串不同，系统将忽略该操作并返回错误码。
鉴权认证机制的详细内容请参见鉴权认证机制。
接入参数（JSON格式）
| 参数 | 说明 | 类型 | 是否必选 |
|---|---|---|---|
| z | 通过百度昊天镜风控指纹SDK获取的ztoken | String | app为android、ios时必填 |
| app | 设备系统类型：android、ios、universe | String | 必选 |
| js_env | 端类型：swan（小程序）、wx（微信小程序）、h5、h5n（带有端能力的h5，集成端sdk的h5，如手百的webview） | String | 如果为小程序、h5接入时必填；swan、h5、wx时app需要填universe；h5n时由于具有端能力app需要填android或ios |
| jt | 通过百度昊天镜风控JS系列SDK获取，含：H5、百度小程序JS SDK | String | app为universe或填入js_env时，jt必填；集成了js sdk时，jt必填 |
接入参数举例
Plain Text
1 {
2 "z":"at8TermQ1qVdEokgqxb1LpiGdDDIHv258FKGKh9U3liFHWQhyC_1NsXRYV6avhaUjvaAWmYs4agXcnG1T8jvMuA",
3 "app":"android"
4 }响应结果
正常返回结果（正常返回结果是一个JSON）
| 字段名 | 类型 | 描述 |
|---|---|---|
| request_id | String | 服务端请求ID |
| ret_code | String | 0 |
| ret_msg | String | 操作成功 |
| ret_data | Map | 风险详情 |
| x | String | 百度昊天镜设备指纹ID |
| t | Array | 设备风险标签。若无风险则返回为空。详细标签枚举，请您联系商务对接人员获取 |
| jid | String | H5设备指纹ID，传入jt时获取 |
| jtag | Array | H5设备风险标签，传入jt时获取 |
正常返回示例：
Plain Text
1 {
2 "request_id":"14875f59-0417-41cb-a31d-0d814db9b4ec",
3 "ret_code":"0",
4 "ret_msg":"操作成功",
5 "ret_data":{
6 "x":"HOCN12b7Mlw6KpTg77HqX8qFeLDorPkhlalD8BC210k="
7 "t":["jailbreak","inject","repkg"]
8 }
9}异常返回结果
| 字段名 | 类型 | 描述 |
|---|---|---|
| request_id | String | 服务端请求ID |
| ret_code | String | 错误码：1000-签名验证错误1001-认证失败1002-请求格式错误2000-参数不合法2001-消息体不正确2002-服务超过最大QPS/服务超过最大调用次数/服务已过期3000-系统内部错误其他错误码请参见：鉴权认证机制错误码 |
| ret_msg | String | 出错信息 |
异常返回示例：
Plain Text
1 {
2 "request_id":"4017678614",
3 "ret_code":"1001",
4 "ret_msg":"认证失败"
5}超时建议
超时时间建议： 当风控接口响应时间过长时，为保障业务顺利运行，业务需要默认放行该次请求，建议超时时间设为200-500ms；
超时重试频次建议： 针对重要业务场景，可增加超时重试逻辑。依旧超时情况下放行处理，优先保障业务正常运行。