risk query

2024-01-17 01:01

概览

API URL：/api/v1/zoloz/idnetwork/risk/query
API 描述：该接口用于查询一条记录存在的风险。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务，建议开启商户服务器，并确保业务ID的唯一性。	"1658905294198"
itemId	String	64	否	null	待查询的记录ID，该ID是入库时IDN返回的数据记录ID。说明：如果传入了itemId字段的值，会自动从库中提取详细数据，不再使用本次imageInfo和basicInfo字段中传入的内容。	"AIN20220707717226249562"
checkAllianceRisk	String	-	否	N	是否查询联盟风险。取值如下： `Y`：同时查询联盟商户。 `N`：仅查询当前商户。	"N"
riskDetection	RiskDetection	-	否	null	待查询的风险。详细信息，请参见RiskDetection。	{ "riskTypes":[ "IDFAKE", "DUPLICATE", "BATCH_REGISTER" ], "timeWindow":{ "startTime":1651882535687, "endTime":1658902665000 } }
imageInfo	ImageInfo	-	否	null	待查询的图片信息。详细信息，请参见ImageInfo。说明：目前只支持faceImage字段，docImage字段系统暂不支持。图片格式为Base64编码字符串，且图片大小不超过5MB。	{ "docImage":"eA3AW/6dxn6QAAAABJRU5ErkJggg==...", "faceImage":"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..." }
basicInfo	BasicInfo	-	否	null	待查询的用户的基本信息。详细信息，请参见BasicInfo。	{ "idType":"00000001003", "idNumber":"46082119870811896X", "certName":"李四", "dateOfBirth":"19870811" }

RiskDetection字段说明

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

riskTypes

List<String>

否

[]

待查询的风险类型。支持以下三大类风险，系统会自动查询其包含的子风险。

IDFAKE：身份冒用。
DUPLICATE：重复认证。
BATCH_REGISTER：批量注册。

[

"IDFAKE", "DUPLICATE", "BATCH_REGISTER" ]

timeWindow

TimeWindow

否

null

风险查询时间窗口。详细信息，请参见TimeWindow。

{ "startTime":1651882535687, "endTime":1658902665000 }

TimeWindow字段说明

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
startTime	Long	-	否	null	风险查询起始时间，采用14位时间戳。	1651882535687
endTime	Long	-	否	null	风险查询结束时间，采用14位时间戳。	1658902665000

ImageInfo字段说明

说明：
目前只支持faceImage字段，docImage字段系统暂不支持。
图片格式为Base64编码字符串，且图片大小不超过5MB。

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
docImage	String	-	否	null	待传入的证件图片（暂不支持该字段）。	"eA3AW/6dxn6QAAAABJRU5ErkJggg==..."
faceImage	String	-	否	null	待传入的人脸图片。	"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

BasicInfo字段说明

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
idType	String	32	否	null	证件类型。支持的证件类型，请参见支持的证件类型和返回的OCR结果。	"00000001003"
certName	String	32	否	null	姓名。	"李四"
idNumber	String	32	否	null	证件号码。	"46082119870811896X"
dateOfBirth	String	-	否	null	出生日期，格式为`yyyyMMdd`。	"19870811"

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果消息。	{ "resultStatus":"S", "resultCode":"SUCCESS", "resultMessage":"Success" }
transactionId	String	IDN生成的唯一业务ID。	"G00000000817636816"
hasRisk	Boolean	是否存在风险。 `true`：存在风险。 `false`：不存在风险。	true
riskDetails	List<RiskDetail>	当前商户存在的风险详情。详细信息，请参见RiskDetail。	[ { "type":"IDFAKE", "subType":"SameFaceDifferentIdNumber", "riskData":[ "AIN20220727890199220364" ] }
allianceRiskDetails	List<RiskDetail>	联盟风险详情。详细信息，请参见RiskDetail。	[ { "type":"IDFAKE", "subType":"SameFaceDifferentIdNumber", "riskData":[ "AIN20220727890976220364" ] }

RiskDetail字段说明

字段名称	数据类型	描述	示例值
type	String	风险类型。	"IDFAKE"
subType	String	子风险类型。	"SameFaceDifferentIdNumber"
riskData	List<String>	风险数据，内容为itemId数组。	["AIN20220727890199220364"]

代码示例

请求示例

copy
POST /api/v1/zoloz/idnetwork/risk/query HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2023-05-05T15:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx

# 使用itemId查询风险
{
    "bizId":"1658905294198",
    "itemId":"AIN20220707717226249562",
    "riskDetection":{
        "riskTypes":[
            "IDFAKE",
            "DUPLICATE",
            "BATCH_REGISTER"
        ]
    }
}

# 使用本地数据查询风险
{
    "bizId":"1658904703520",
    "riskDetection":{
        "riskTypes":[
            "IDFAKE",
            "DUPLICATE",
            "BATCH_REGISTER"
        ]
    },
    "imageInfo":{
      "docImage":"eA3AW/6dxn6QAAAABJRU5ErkJggg==...",
      "faceImage":"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."
    },
    "basicInfo":{
      "idType":"00000001003",
      "idNumber":"46082119870811896X",
      "certName":"李四",
      "dateOfBirth":"19870811"
    }
}

返回示例

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2023-05-05T15:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
    "result":{
        "resultStatus":"S",
        "resultCode":"SUCCESS",
        "resultMessage":"Success"
    },
    "transactionId":"G00000000xxxxxxx",
    "hasRisk":true,
    "riskDetails":[
        {
            "type":"IDFAKE",
            "subType":"SameFaceDifferentIdNumber",
            "riskData":[
                "AIN20220727890199220364"
            ]
        },
        {
            "type":"IDFAKE",
            "subType":"SameIdDifferentFace",
            "riskData":[
                "AIN20220727890199220387",
                "AIN20220727890222174163"
            ]
        },
        {
            "type":"BATCH_REGISTER",
            "subType":"SameFaceBackgroundDifferentFace",
            "riskData":[
                "AIN20220727890862716253",
                "AIN20220727899872658271"
            ]
        }
    ],
    "allianceRiskDetails":[
        {
            "type":"IDFAKE",
            "subType":"SameFaceDifferentIdNumber",
            "riskData":[
                "AIN20220727890976220364"
            ]
        },
        {
            "type":"IDFAKE",
            "subType":"SameIdDifferentFace",
            "riskData":[
                "AIN20220727890199220387",
                "AIN20220727890222174163"
            ]
        },
        {
            "type":"BATCH_REGISTER",
            "subType":"SameFaceBackgroundDifferentFace",
            "riskData":[
                "AIN20220727890862716253",
                "AIN20220727899872658271"
            ]
        }
    ]
}