接口说明

本接口是智能风控服务的在线检测接口，需配合智能风控SDK使用，当SDK获取token后，将token传入该接口获取风险识别结果，详情请参考使用教程。该接口为实时检测接口，同步返回检测结果，当前接口为V6，version: 600。 V6接口其他版本链接以及详细变更参考。 V6版本接口更新日志。
老版本参考在线检测接口V5和在线检测接口V4。

鉴权说明

易盾智能风控服务使用签名认证方法对接口进行鉴权，所有接口每一次请求都需要包含签名信息（signature 参数），以验证用户身份，防止信息被恶意篡改。目前支持MD5签名算法，详细信息请参见接口鉴权。

接入须知

1. 如果您没有从客户端智能风控SDK获取到token或者获取到的token是null值，依然建议在业务场景节点（SDK埋点位置，如注册场景）调用检测接口。
2. 请根据接口返回的风险等级进行相应业务处置，为了保障处置动作依据完备，如需对用户进行封号，建议结合用户/玩家的业务数据进行二次判断，或者与易盾技术人员进行二次确认，以确保准确无误。
3. 请控制接口调用频率，默认qps为1000，频率过高，可能会超过频率限制，导致接口调用失败。上线前有需要提升qps需要可以联系易盾商务。

请求说明

请求地址

名称	值
HTTP URL	http://ir-open.dun.163.com/v6/risk/check
HTTP Method	POST

请求头

名称	类型	必填	描述
Content-Type	String	是	固定值："Content-Type:application/json"

 

请求参数

部分产品相关参数请用账号登陆易盾官网控制台获取参考

请求参数包括：公共参数和私有参数。其中，公共参数如下：

参数	类型	必填	参与签名计算	最小长度	最大长度	描述
businessId	String	是	是	10	32	每个业务接入时，会分配唯一的业务 ID。
secretId	String	是	是	32	36	产品密钥，每个应用接入时，会分配secretId和私钥secretKey。
timestamp	Long	是	是	13	13	接口调用时的UNIX时间戳，单位：毫秒，用于判断请求是否过期
nonce	String	是	是	32	32	随机码，用于防止重放，固定长度32个字符，不能重复，建议使用UUID
version	String	是	是	3	3	当前页面接口版本号：600
signature	String	是	否	32	32	使用 secretKey 生成的签名，用于身份验证，生成方法见接口鉴权

私有参数如下：

参数名	类型	必填	最大长度	描述
token	String	是	15000	在客户端调用getToken服务后返回给客户端的检测凭证：token。 - 客户端到易盾网络正常情况时生成短token，长度根据平台不同有所区别： 32byte（web/小程序sdk）或40byte（android/ios/pc）。 - 网络质量不好或者域名被屏蔽情况下，生成离线token，平均长度在4k-8kb左右，长token和短token具有相同的检测效果，请勿对token进行截断。 详情请查看客户端接入说明文档。
account	String	是	256	用户账号标识，建议使用业务方用户的UID，标记用户的唯一身份。
roleId	String	是	256	用户角色ID，适用于支持同一个账号下创建不同角色的业务（如游戏不同区服的角色）。 如无roleId，可传入固定值“1”，或与account相同的值。
nickname	String	否	256	用户账号/角色的昵称。
server	String	否	32	用户/玩家的角色服务器名称
ip	String	是	64	用户的IP，或当前客户端业务事件发生时的客户端请求IP地址（ipv4格式），若无法拿到ip，可以传入一个定值，为了效果准确考虑，建议传入真实ip。
phone	String	否	64	用户账号关联的手机号码（部分业务，账号名=手机号码），默认为国内手机号码。 如有海外手机号码，需要包含国家地区代码，格式为“+447410xxx186”（+44即为国家码）。 支持数据加密，请传入hash值（hash算法：md5(phone)）。
email	String	否	64	用户账号关联的电子邮箱地址，必须是有效的电子邮件格式，传入格式要求为： xx@××。
target	String	否	256	活动操作的目标，比如：A给B点赞，则target为B。如果target是手机号或邮箱，请提供hash值，hash算法：md5(target)。如没有，可传空
registerTime	Long	否	13（参数长度必须是13位）	用户/角色注册、创建时间点。请传入时间戳，单位：毫秒。 注意：若传入该字段，系统会进行参数格式强校验，参数长度必须是13位，如：1689733747268。
registerIp	String	否	64	用户/角色注册、创建时的IP地址，如有记录，可传入辅助进行风险判断。
level	String	否	32	用户账号等级、财富等级等，有助于对不同等级用户设置分层策略，方便业务进行精细化安全运营。 注意：level 由业务自定义，风控系统除长度外不会有任何其他校验手段，请业务需要自行管理、维护 level 字典。
gameVersion	String	否	32	游戏类型应用的版本号
assetVersion	String	否	32	游戏类型应用的资源版本号
activityId	String	否	256	事件的细分标记，用于标记场景事件下的细分类别，如同样是促销活动，可用于区分：双十一促销、618促销；再如同样是邀请拼团活动，activityId标记本次邀请的唯一识别ID
deviceId	String	否	128	当前用户的设备ID。 注意：如果通过SDK模式接入，则可不传，优先使用SDK生成的设备ID，API模式下强烈建议传入。
sceneData	String	是	-	请登陆易盾官网后台风控引擎-服务管理查看当前业务的场景类型，请求不同业务场景下，需要传入的场景数据存在差异，具体请看下述场景参数描述。不同场景接入说明 注意：如果接入场景为“其他”（即不指定某个具体的场景，或规范中的标准场景），则sceneData可传空"{ }"。
extData	String	否	2048	根据业务定制需求，额外需要传入系统的信息，可用于配置业务定制的检测规则。

 

请求参数示例

{
    "businessId": "a0bcmo3aa617x1n62tlhtragdd009wy1",
    "secretId": "b0bcmo3aa617x1n62tlhtragdd009wy2",
    "timestamp": 1701837991081,//传入时以当前时间为准
    "nonce": "c0bcmo3aa617x1n62tlhtragdd009wy3",
    "version": "600",
    "signature": "d0bcmo3aa617x1n62tlhtragdd009wy4",
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",//以客户端传递的token为准
    "ip":  "1.1.1.1",
    "roleId":  "xxxxxxx",
    "account":  "yyyyyyy",
    "nickname":  "zzzzzzz",
    "level":  "150",
    "identity":  "visitor",
    "payUser":  true,
    "verified":  false,
    "deviceId":  "381xfu028f2083u230fuc2",
    "sceneData": "{\"loginType\":\"userPassword\",\"appChannel\":\"app_store\",\"registerDay\":999,\"hashPassword\":\"adfdafjk123kjfkljdaf\",\"identity\":\"visitor\",\"paidUser\":false,\"verifiedUser\":false}"
    "extData": "{\"otherInfo\":\"其他字段信息\"}"
}

响应

响应结果

响应数据格式为：JSON。

响应头为：Content-Type:application/json，具体如下：

参数	类型	描述
code	Integer	响应码，正常情况下为200，异常时，见 附录响应码定义
msg	String	响应码说明，正常情况下返回“ok”，异常时，见 附录响应码定义
desc	String	响应信息描述，非必返，常见错误情况下会返回错误说明或错误参考文档
data	JSONObject	返回数据，格式下表说明

检测结果的数据格式：

参数	类型	说明
riskLevel	Integer	风险等级：0 正常，1 低风险，2 中风险，3 高风险，4 可信源。 风险等级只会返回一个，取本次命中的最高风险等级
hitInfos	List	命中风险信息，例如：[{"type":"12401067","name":"环境风险-ROOT-通用","riskLevel":"风险等级"}]。 如果同时命中多个类型，则会返回全部命中风险信息。详细风险标签参考智能风控风险标签
∟ type	String	风险标签type
∟ name	String	命中的风险标签对应的名称，命中的标签的上下级名称采用‘-’进行拼接
taskId	String	检测任务 ID，建议记录存储，便于后续数据查询验证。
sdkRespData	String	风控检测结果加密数据，仅在token数据能成功解析时返回该字段，应用/游戏方可转交给风控 sdk 解析处理。
deviceId	String	购买设备指纹功能后，check结果中才会包含deviceId。
matchedRules	List	命中规则编号列表
matchedCustomRules	List	命中自定义规则编号列表
deviceInfo	JSONObject	设备信息, Android设备返回的字段见Androd设备信息，IOS设备返回字段见IOS设备信息
evidences	List	证据信息

Androd设备信息

字段名称	类型	说明
screenInfo	String	屏幕信息
appVersion	String	app版本号
bootCount	Integer	设备启动次数
chargeState	String	充电状态
macRandom	Integer	是否开启mac随机化，0:未随机化，1:随机化，2:未知，3:mac地址存在错误
screenBright	Integer	屏幕亮度
checkAdb	Integer	adb是否开启，0:否，1:是
upTime	String	手机已启动时间
osVersion	String	Android版本，如7.0，8.1.0
carrierName	String	运营商
lockTime	Integer	手机总锁屏时间
isFakeCam	Integer	是否是虚拟摄像头，0:不是，1:是
phoneBrand	String	手机品牌
firstSetupTime	String	第一次安装时间
hasSim	Integer	是否存在sim卡,0:无，1:有
model	String	型号
isShareScreen	Integer	投屏状态判断，0:不是，1:是
networkType	Integer	网络连接类型，1:wifi,2:2g,3:3g,4:4g,5:5g
batteryLevel	Integer	当前电量信息

IOS设备信息

字段名称	类型	说明
bootTime	String	开机时间
totalDiskSpace	String	硬盘大小，单位字节
auxo	Integer	非完美越狱失效状态，0:未越狱，1:越狱，2:越狱失效
macSerialnumber	String	mac序列号
chargeStatus	String	0:未开启电池权限，1:未充电，2:充电中，电池电量小于100，3:充电中，电池电量充满
deviceId	String	客户端本地生产的设备 ID
isCydiaSubstrate	Integer	是否安装CydiaSubstrate，0:否，1:是
isAntiJailbreak	Integer	是否有反越狱插件，0:否，1:是
totalMemory	String	总内存，单位字节
osVersion	String	手机操作系统版本
carrierName	String	运营商名称
model	String	手机型号
cpuUseRate	String	cpu 使用率
networkType	Integer	网络连接类型，1:wifi,2:2g,3:3g,4:4g,5:5g
batteryLevel	String	当前电量信息

响应结果示例

• 识别结果正常时：

{
    "code": 200,
    "msg": "ok!",
    "data": {
        "riskLevel": 0,
        "hitInfos": null,
        "taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
	"sdkRespData":"CGgBEgbmiJDlip5aIKrJEIBN123NwfiE1gVma8U8Fv+hPCzbH9W1gVIVhWDs"
        //购买设备指纹功能后，check结果中才会包含deviceId
        "deviceId":"389xfu028f2083u230fuc2"
        //设备信息
        "deviceInfo": {
            "screenInfo": "1080x1920",
            "appVersion": "4.3.5",
            "bootCount": 11,
            "chargeState": 2,
            "macRandom": 0,
            "screenBright": 40,
            "checkAdb": 1,
            "upTime": "50461",
            "osVersion": "8.1.0",
            "carrierName": "",
            "lockTime": "27246",
            "isFakeCam": 0,
            "phoneBrand": "vivo",
            "firstSetupTime": "1702177115487",
            "hasSim": -1,
            "model": "vivo X9s",
            "isShareScreen": 0,
            "networkType": 1,
            "batteryLevel": 47
        }
  },
  "ok":true
}

• 识别结果异常时：

{
    "code": 200,
    "msg": "ok!",
    "data": {
        "riskLevel": 2,
        "hitInfos": [
            {
                "type": "...",
                "name": "xx风险-xxx-xxx",
            },
            {
                "type": "...",
                "name": "xx风险-xxx-yyy",
            }
        ],
        "taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
        "sdkRespData":"CGgBEgbmiJDlip5aIKrJEIBN123NwfiE1gVma8U8Fv+hPCzbH9W1gVIVhWDs",
        //购买设备指纹功能后，check结果中才会包含deviceId
        "deviceId":"389xfu028f2083u230fuc2",
        //命中规则编号列表
        "matchedRules": ["R20230228205054395", "R20230228211555767"],
        // 命中自定义规则列表
        "matchedCustomRules": ["R20230228205054395", "R20230228211555767"],
        //设备信息
        "deviceInfo": {
            "bootTime": "2023-12-18 09:23:21",
            "totalDiskSpace": "127870980096",
            "auxo": 0,
            "macSerialnumber": "",
            "chargeStatus": "1",
            "deviceId": "8b7be3bbd89417ae0167e08fdf4aaaaa",
            "isCydiaSubstrate": 0,
            "isAntiJailbreak": 0,
            "totalMemory": "3849175040",
            "osVersion": "16.5.1",
            "carrierName": "--",
            "model": "iPhone13,2",
            "cpuUseRate": "0.21",
            "networkType": 1,
            "batteryLevel": "59"
        }
        // 证据信息
        "evidences": ["证据", "证据"]
  },
  "ok":true
}

注意事项

• 当返回无数据时，可能原因包括数据处理延时、数据不存在；
• 自动封禁有风险，操作请谨慎，建议参考其他因素综合考虑。

响应返回码

响应返回码见：响应返回码

接入示例代码

开发工具集（SDK）接入

为方便 JAVA 开发者调试和接入API，我们提供了配套的开发工具集（SDK），用于简化API接入流程。SDK中各接口调用方式基本相同，接入方式统一，并提供了一些接口调用过程中常见的异常处理方案。以下介绍了SDK的使用流程，以及使用SDK的简单示例。

• 准备工作

准备步骤详见通用步骤

• 使用方法

该接口的使用方法可参考SDK demo

sceneData数据构建规范说明

不同场景接入说明

易盾智能风控系统支持客户给予业务，不同场景下，回传给风控系统不同的检测数据，以期达到更好的检测效果。基于不同类型场景，易盾提供以下 sceneData 数据构建规范：

• 游戏反外挂
• 注册登录保护
• 社交互动场景
• 运营/营销活动保护
• 支付安全保护
• 其他

 

游戏反外挂

当前版本暂未支持，后续601版本开始支持，可以参考V6版本接口更新日志。

 

注册登录保护

注册

参数名	类型	必填	最大长度	描述
registerType	String	是	-	注册方式，可选参数内容如下： - userPassword：用户名密码注册 - phoneAuth：手机号一键注册（包含短信验证码方式注册方式） - otherPlatformAuth：第三方平台授权注册（如微信授权注册等） - unknown：未知注册方式
registerChannel	String	否	-	如果是“第三方平台授权注册”，可传入注册渠道，可选参数内容如下： - qq：qq授权注册 - weixin：微信授权注册 - alipay：支付宝授权注册 - weibo：微博授权注册 - other：未知/其他平台授权注册
inviterId	String	否	128	如为邀请注册制，可填写邀请人的邀请码、账号ID等唯一标识信息
hashPassword	String	否	128	加密后的用户密码
registerChannelMark	String	否	128	如可获取注册流量来源平台/渠道（特别适用于通过web、小程序方式进行的注册），可传入平台/渠道的唯一识别码。如： - 腾讯平台：传入点击回调中的 click_id - 巨量平台：传入点击回调中的 CALLBACK_PARAM 可根据业务是否获取相关信息及是否需要根据表示进行检测决定是否传入此参数
gender	String	否	-	注册用户的性别，如应用注册时有明确的性别信息，可通过此处传入。可选参数内容如下： - male - female

登录

参数名	类型	必填	最大长度	描述
loginType	String	是	-	当前用户登录方式，可选参数如下： - userPassword：使用用户名、密码登录 - phoneAuth：使用手机号码授权登录（包含短信验证码方式登录方式） - qq：qq授权登录 - weixin：微信授权登录 - alipay：支付宝授权登录 - weibo：微博授权登录 - other：未知/其他平台授权登录
appChannel	String	是	32	用户使用的应用来源渠道（或者说是app的上架渠道），如用户是从GooglePlay下载应用，则可传入：googleplay。如业务无法获知当前应用的来源渠道，可传入：unknown
registerDay	Long	否	8	用户账号注册天数
hashPassword	String	否	128	加密后的用户密码
identity	String	是	-	区分用户在业务中的身份类型（通常可用于根据业务需要进行策略研究、布控），可传入参数包括： - visitor：游客身份 - commonUser：普通用户 - seniorUser：高级用户（如vip、主播、司机等） - other：未知/其他身份
paidUser	Boolean	否	-	用于标记是否付费用户，以方便实施策略布控： - true：付费客户 - false：非付费客户
verifiedUser	Boolean	否	-	用于标记是否经过实名/信息认证后的用户，以方便实施策略布控： - true：认证客户 - false：非认证客户

 

社交互动保护

 

运营/营销活动保护

 

支付安全保护

充值

参数名	类型	必填	最大长度	描述
payTime	Long	是	13	角色充值到账时间，UNIX 时间戳（毫秒值）
appChannel	String	是	32	客户端app的渠道，如：appstore、googleplay
money	Double	是	8	商店定价货币额度，50元（换算人民币）以下记录准确金额，50元（换算人民币）以上可都记录为50元
currency	String	是	16	商店定价货币类型，如：USD、EUR、CNY，参考货币代码表(ISO4217)
payMoney	Double	是	8	支付货币额度，50元（换算人民币）以下记录准确金额，50元（换算人民币）以上可都记录为50元
payCurrency	String	是	16	玩家实际支付货币类型，如：USD、EUR、CNY，参考货币代码表(ISO4217)
payChannel	String	是	32	支付渠道，如app_store、google、H5等）
orderId	String	是	128	app_store/google/其他渠道唯一订单号 app_store：iOS的transactionId，例如：160001456292965 google：Google订单号，例如：GPA.3329-6166-4658-28227
orderCreateTime	Long	是	13	订单创建时间，UNIX 时间戳（毫秒值）
orderPayTime	Long	是	13	订单支付时间，UNIX 时间戳（毫秒值）
orderFinishTime	Long	是	13	订单发货时间，UNIX 时间戳（毫秒值）
callbackUrl	String	否	256	回调接口地址，用于坏账治理结果回调通知业务方，如果您开通了坏账治理功能，请在此处填入回调接口，否则检测结果仅可通过页面查询获取。 仅检测到异常时会回调通知，正常订单不会调用回调接口。

消费

参数名	类型	必填	最大长度	描述
createTime	Long	是	13	用户账号/角色创建时间点，UNIX 时间戳（毫秒值）
cost	Long	是	8	消费货币数（可以是真实金额、应用/游戏中的货币数）

退款

参数名	类型	必填	最大长度	描述
refundTime	Long	是	13	订单退款时间，UNIX 时间戳（毫秒值）
orderId	String	是	128	app_store/google/其他渠道唯一订单号 app_store：iOS的transactionId，例如：160001456292965 google：Google订单号，例如：GPA.3329-6166-4658-28227
refundReason	String	否	64	用户退款原因
callbackUrl	String	否	256	回调接口地址，用于坏账治理结果回调通知业务方，如果您开通了坏账治理功能，请在此处填入回调接口，否则检测结果仅可通过页面查询获取。 仅检测到异常时会回调通知，正常订单不会调用回调接口。

 

其他

其他场景情况下，sceneData无强制要求，可传空串sceneData:"{ }"。