API接入指南

◆ 身份核验测试账号申请：云端测试服务环境，需在OA系统提交《身份核实服务测试资源申请流程》，申请接入环境服务账号，申请次数一般不超过100次。需填写项目信息，所需服务，所需次数。

◆ 测试账号：上一步流程审核通过后，运营人员会邮件分配服务端API接入配置参数，包括：

appId、deviceId、secret

◆ 注意：由于核验涉及成本，集成环境不允许做批量测试或压力测试！若发现违规操作导致公司损失，由批量测试用户承担。

◆ 生产环境账号申请：1、联系销售按照合同约定的产品下订单；2、对项目经理提供的服务开通申请表，确认内容后签字或盖章；3、有特殊策略要求的发邮件申请。

1. 访问地址

环境	地址
测试环境	https: //api-sit.isignet.cn:8082/ids/v1/outer/{核验接口地址}
正式环境	https: //api.isignet.cn/ids/v1/outer/{核验接口地址}

2. 请求报文格式

· 接口形式：HTTP服务resfulAPI的形式

· 报文编码格式为UTF-8

· 请求方式：POST

· POST请求头格式为Content-Type: application/json

3. 公共参数

3.1 公共请求参数

字段名称	字段描述	字段类型	必传
version	版本，默认为1.0	String	是
signAlgo	签名算法,目前只支持HMAC和HmacSHA256	String	是
deviceId	由BJCA分配的设备ID	String	是
appId	由BJCA分配的应用ID	String	是
userTransId	业务流水号。业务调用方随机生成的唯一标识，支持最大64位	String	是
signature	签名值。对请求报文进行签名计算得到，计算方法参考报文签名值signature计算方法	String	是

3.2 公共响应参数

字段名称	字段描述	字段类型	必传
status	响应码，200即为成功	String	是
message	响应信息	String	是
data	响应内容	String	否

3.3 参数校验响应参数

字段名称	字段描述	字段类型	必传	示例
data	errCode	参数校验错误码	String	是
errMsg	参数校验错误信息	String	是	姓名不能为空

3.4 示例报文

{

    "version":"1.0",

    "appId":"APP_52E0099A69414266B84DFAB4999E1299",

   "signAlgo":"HMAC",

    "data":"Q29zcyBTaWduIERhdGEgRm9yIFRlc3Qu"

}

3.5 报文签名值signature计算方法

3.6 签名值signature生成的通用步骤

第一步

设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

特别注意以下重要规则：

◆ 参数名ASCII码从小到大排序（字典序）；

◆ 如果参数的值为空不参与签名，且请求报文中也不要带此参数；

◆ 参数名区分大小写；

第二步

对stringA对进行HMAC运算，得到hmac的值后再做Base64编码，最后得到sign值signature。

String signTemp = hmac(stringA, secret); //secret由BJCA分配

String signature = Base64(signTemp);

3.7 报文请求及响应示例

接口请求响应示例：

◆ 以调用添加签名任务接口为例（公共参数标记红色，业务参数标记蓝色），请求报文如下：

{

    "version":"1.0",

    "appId":"APP_52E0099A69414266B84DFAB4999E1299",

   "signAlgo":"HMAC",

    "data":"Q29zcyBTaWduIERhdGEgRm9yIFRlc3Qu"

}

其中：

◆ 对示例请求的参数按照key=value的格式，并按照参数名ASCII字典序排序后字符串如下：

stringA=SM3withSM2&appId=APP_52E0099A69414266B84DFAB4999E1299&
data=Q29zcyBTaWduIERhdGEgRm9yIFRlc3Qu &signAlgo=HMAC&transId=20190531001&version=1.0

◆ 计算签名值signature：

String signTemp = hmac(stringA, secret); //对字符串用secret进行HMAC加密

String signature = Base64(signTemp); //加密后结果进行Base64

◆ 对上述待签名原文进行HMAC-SHA256签名的签名值结果如下：

wyLPhb2JwrcT6WPMDxa/61BMKdSVZc5gpaU21n/bfgA=

◆ 待发送报文如下：

{
    "version":"1.0","appId":"APP_52E0099A69414266B84DFAB4999E1299",
    "signAlgo":"HMAC","title":"测试长签名",
    "description":"签名任务描述",
    "dataType":"DATA",
    "algo":"SM3withSM2",
    "data":"Q29zcyBTaWduIERhdGEgRm9yIFRlc3Qu",
    "signature":"P2yQKZuDdFFoatgBXlMSsBttnczNuDAGWyTSu/U4pwM="
}

◆ 响应报文如下：

{

    "status": 200,

    "message": "SUCCESS",

    "data": {

        "signDataId": "SD_56770b9f-80b6-4efd-a4b2-c7305cc16f82",

        "qrCode": "KHE0DgQEUHoQY3VneGVkZ18SXBRtCgBTDmBnNjYLXQRGIgAdUg9+Y2YzDEFTFHgAEh0aOSojNU1KRyEJdX4TFG8mITxNSkdQbBBGVEo+Ojw+TUpHQ24CEkw="

    }

}

4. 相关接口

核验模式	产品编号	API接口集成	计费点
两项实名信息核验	SF-SM02	三、个人核验服务接口 1、两项信息实名	两项信息实名
四项实名信息核验	SF-SM04	三、个人核验服务接口 3、四项信息实名	四项信息实名
两项及人像信息核验	SF-SR02	三、个人核验服务接口 2、两项信息实人	两项信息实人
四项及人像信息核验	SF-SR04	三、个人核验服务接口 4、四项信息实人	四项信息实人
手机号三要素信息核验	SF-SJ	三、个人核验服务接口 5、手机号三要素	手机号三要素
银行卡三要素信息核验	SF-YHK3	三、个人核验服务接口 6、银行卡三要素	银行卡三要素
银行卡四要素信息核验	SF-YHK4	三、个人核验服务接口 7、银行卡四要素	银行卡四要素
企业信息核验	SF-E-HY	四、企业核验服务接口 1、企业信息核验	企业信息核验
企业四要素核验	SF-E-HY4	四、企业核验服务接口 2、企业四要素核验	企业四要素核验
企业账号核验	SF-E-FK	四、企业核验服务接口 4、企业账号核验 5、企业打款通知 6、获取银行名称 7、获取银行地址编码 8、查询打款结果 9、校验验证码	企业账号核验/企业打款通知
证照OCR服务	SF-OCR	五、核验增值服务接口 1、身份证OCR正面 2、身份证OCR反面 3、银行卡OCR 4、营业执照OCR	OCR
人像比对服务	SF-IRT-FACE	五、核验增值服务接口 5、人像比对	人像比对
企业信息查询	SF-E-CX	四、企业核验服务接口 3、企业信息查询	企业信息查询
短信服务	SF-SMS	四、短信发送服务接口	短信发送
出入境两项实名信息核验+出入境证件身份核验密码设备租赁模式	SF-CRJSM02	出入境身份信息2项实名接口	出入境身份信息2项实名
出入境两项及人像信息核验+出入境证件身份核验密码设备租赁模式	SF-CRJSR02	出入境身份信息2项实人接口	出入境身份信息2项实人