在线检测接口V4

2023.07.26 16:01:12

    接口说明

    本接口用于智能风控嫌疑数据在线检测,并且接口会同步返回检测结果。

    鉴权说明

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

    接入须知

    1. 因取证信息场景复杂,为了保障封禁动作依据完备,如需封号,建议结合用户/玩家的业务数据进行二次判断,或者与易盾技术人员进行二次确认,以确保准确无误;
    2. 请控制接口调用频率,频率过高,可能会超过频率限制,导致查询失败。

    请求说明

    请求地址

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

    请求头

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

     

    请求参数

    请求参数分为:公共参数,接口参数。其中,公共参数请见公共请求参数;接口参数如下:

    参数 类型 必填 参与签名计算 描述
    token String 风控SDK上报的数据后回参获取到的 token,应用方需要从智能风控客户端SDK获取该数据。详情请查看客户端接入文档。
    ip String 用户/ 玩家的IP,或当前客户端业务事件发生时的公网IP地址(ipv4)
    roleId String 用户/玩家的角色 ID,非游戏类型应用,roleId 可以与 roleAccount 相同
    roleName String 用户/玩家的角色名称,非游戏类型应用,roleName 可以是当前用户昵称相同
    roleServer String 用户/玩家的角色的服务器名称
    account String 用户/玩家的账号
    phone String 用户用于登录的手机号码或者关联的手机号码,默认国内手机号。如有海外手机,需包含国家地区代码,格式为“+447410xxx186(+44即为国家码)”。如果需要加密,支持传入hash值,hash算法:md5(phone)
    activityId String 活动的唯一标识,用于标记场景下的细分类别,如:注册-自主注册、注册-受邀请注册;再如:登录- app登录、登录-web登录等
    target String 活动操作的目标,比如:A给B点赞,则target为B。如果target是手机号或邮箱,请提供hash值,hash算法:md5(target)。如没有,可传空
    email String 用户的邮箱,如果需要加密,支持传入hash值,hash算法:md5(email)
    registerTime Long 用户的注册时间,单位:毫秒
    registerIp String 用户的注册IP
    roleLevel String 用户/玩家的等级
    gameVersion String 游戏类型应用的版本号
    assetVersion String 游戏类型应用的资源版本号
    extData String 额外/拓展的信息,应用 / 游戏方可以自己构建json结构,最大长度:2048。不同场景构建信息见分场景extData接入说明

     

    请求参数示例

    {
        "businessId": "xxx966f73yyy59440583zzz9bfcc79df",
        "secretId": "nnn966f73yyy59440583zzz9bfcc79dc",
        "timestamp": ${currentTime},
        "nonce": "mmm888f73yyy59440583zzz9bfcc79de",
        "version": "400",
        "signature": "lll888f73yyy59440583zzz9bfcc79da",
        "token": "${riskDataToken}",
        "ip":  "1.1.1.1",
        "roleId":  "yyyyyyy",
        "roleName":  "yyyyyyy",
        "roleServer":  "yyyyyyy",
        "account":  "zzzzzzz",
        "roleLevel":  "150",
        "gameVersion":  "1.0.2",
        "assetVersion":  "0.2.1",
        "extData": "..."
    }
    
    //其中,在线检测接口,参与签名验证计算的参数如下
    {
        //公共参数
        "businessId": "xxx966f73yyy59440583zzz9bfcc79df",
        "secretId": "nnn966f73yyy59440583zzz9bfcc79dc",
        "timestamp": ${currentTime},
        "nonce": "mmm888f73yyy59440583zzz9bfcc79de",
        "version": "400",
        //私有参数
        "token": "${riskDataToken}",
        "ip":  "1.1.1.1"
    }
    

    响应

    响应结果

    响应数据格式为:JSON。

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

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

    检测结果的数据格式:

    参数 类型 说明
    riskLevel Integer 风险等级:0 正常,4 可信源,10 高风险,20 中风险,30 低风险。 风险等级只会返回一个,取本次命中的最高风险等级,
    hitInfos List 命中风险信息,例如:[{"type":"12401067","name":"环境风险-ROOT-通用","desc":"风险描述"}]。其中:type类型为String,含义为命中的风险标签type;name类型为String,含义为命中的风险标签对应的名称,命中的标签的上下级名称采用‘-’进行拼接;desc类型为String,含义为风险标签的描述信息,可为空。如果同时命中多个类型,则会返回全部命中风险信息。详细风险标签参考智能风控风险标签
    taskId String 检测任务 ID,建议记录存储,便于后续数据查询验证。
    sdkRespData String 风控检测结果加密数据,应用/游戏方可转交给风控 sdk 解析处理。
    deviceId String 购买设备指纹功能后,check结果中才会包含deviceId。

    响应结果示例

    • 识别结果正常时:
    {
        "code": 0,
        "msg": "ok!",
        "data": {
            "riskLevel": 0,
            "hitInfos": null,
            "taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
            //购买设备指纹功能后,check结果中才会包含deviceId
            "deviceId":"389xfu028f2083u230fuc2"
      },
      "ok":true
    }
    
    • 识别结果异常时:
    {
        "code": 200,
        "msg": "ok!",
        "data": {
            "riskLevel": 10,
            "hitInfos": [
                {
                    "type": "...",
                    "name": "xx风险-xxx-xxx",
                    "desc": "..."
                },
                {
                    "type": "...",
                    "name": "xx风险-xxx-xxx",
                    "desc": "..."
                }
            ],
            "taskId":"b0bcmo3aa617x1n62tlhtragdd009wyr",
            "sdkRespData":"...",
            //购买设备指纹功能后,check结果中才会包含deviceId
            "deviceId":"389xfu028f2083u230fuc2"    
      },
      "ok":true
    }
    

    注意事项

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

    响应返回码

    响应返回码见:响应返回码

    Online Chat Tel:95163223 Free trial