第四章 接口参数(4) - 签约流程
## 4. 签约流程
## 4.1 提交在线签约信息接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/sign/contract
#### 请求方式：POST
>d 该接口不可频繁无限请求。同一个手机号每天至多五次请求。如果查过了则需要24小时候才可重试。务必确认信息正确在提交。不可随便提交测试。
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|realName|真实姓名|是||
|cardNo|银行卡号|是|当签约状态选择是2：为银行卡4要素时为必填项，反之为选填项|
|mobile|手机号|是||
|idCard|身份证号码|是||
|signingType|签约类型|是|2:银行卡四要素 3:运营商三要素|
>d 备注：银行卡四要素 ：姓名，身份证，银行卡，手机号码。运营商三要素 ：姓名，身份证，手机号码
#### 响应参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|personAccountId|签约账户ID|String|是|该值用于下个接口签约使用|
## 4.2 验证码确认签约接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/sign/contract/submit
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|code|验证码|是||
|personAccountId|签约账户ID|是||
|mobile|手机号|是||
#### 响应参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|url|签约成功的合同链接|String|是||
## 4.3 签约结果查询接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/sign/result
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|无参数名称|需要查询的身份证号码|是|例如：[身份证号码 1,身份证号码 2]|
>d 该接口参数无需参数名称只需将身份证号码拼接处json数组即可
示例：String data = [\"idCard1\",\"idCard2\"... ,\"idCard10\"];
一次性最多查询10条记录
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|idName|姓名|String|是||
|idCard| 身份证号|String| 是||
|status| 结果状态|int| 是|详情请参考[签约状态码](doc:nD2opxYu)|
|url| 签约成功协议地址|String|否| |只是签约成功的状态才会有该值|
>d该返回结果data解密后为List 集合json字符串。
结果示例
[{"idCard":"idCard1","status":xx,"url":"xxxx"},
{"idCard":"idCard2","status":xx,"url":"xxxx"}]
## 4.4 签约成功后回调接口
>d 该接口需要第三方自行编写提供接口到发放平台 接口编写示例如下。
#### 请求方式：POST
```java
@PostMapping("signCallBack")
@ResponseBody
public String signCallBack(HttpServletRequest request, @RequestBody String data){
String publicKey = "该公钥由发放平台提供发放到贵司邮箱";
//解密
String decode = RSAHelper.decryptByPublicKey(data, publicKey);
/*贵公司处理业务逻辑*/
return "success";
}
```
解密工具类在 [JAVA_DEMO](https://gitee.com/xinfudblog/lxapi_java_demo) 的 RSAHelper 类中
>d
> 1.贵司写完后提供到接口url给发放平台即可。回调成功必须返回success，不然会重复回调，至多重试8次。
> 2.每次回调的间隔时间2N次方分钟，比如第一次回调间隔时间为2分钟，第二次就为4分钟，依次往后推，最多重试8次；
postman中模拟接口是否正常接收数据如下操作
#### 传给回调接口参数data 解密结果json说明：
解密结果示例如下：
```json
{"idCard":"12456484","realName":"张三","bankCard":"54848484","mobile":"1888888888","protocolUrl":\"https://123.com"}";
```
|参数名称| 参数含义|数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|idCard| 身份证号|String| 是||
|realName| 真实姓名|String| 是||
|bankCard| 银行卡号|String| 否||
|mobile| 签约手机号|String| 是||
|protocolUrl| 签署成功的协议链接|String| 是||
## 4.5 身份证资料上传接口（身份证签约)
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/sign/certification/upload
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|name|签约姓名|String|是|需要签约人的姓名|
|idCard|签约身份证号码|String|是|需要签约人的身份证号码|
|mobile|手机号|String|是||
|frontIdCard|身份证正面照片URL|String|是||
|backIdCard|身份证反面照片URL|String|是||
|hatlessPhoto|自拍照片URL|String|是||
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|token| token|String |是||
|protocol|协议链接|String| 是|返回的协议的下载URL地址|
## 4.6 签署接口（身份证签约)
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/sign/face/sign
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|token|token信息|String|是||
>d 注意：
> 1. 签约的token有一定时效性，时间间隔是2个小时，超过时长会返回相应的错误提示；
> 2. 如果超过时效，需要重新调用 1.身份证资料上传接口 重新获取token信息
#### 接口响应参数data字段解密后的参数说明：
|参数名称| 参数含义| 数据类型| 是否必有| 参数备注|
|-|-|-|-|-|
|idCard|签约身份证号码|String|是|
|protocol|协议列表|String| 是|返回已签约的协议的URL地址|
## 5.上传文件接口（公共接口）
>d 该接口将需要上传的文件上传至发放平台服务器，获取到对应的地址用于其他接口作为入参
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/common/uploadFile
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|是否必填|参数备注|
|-|-|-|-|
|file|文件|是||
#### 响应参数说明：
|参数名称| 参数含义| 是否必有| 参数备注|
|-|-|-|-|
|url|文件地址|是||
java接口代码示例：
```json
@PostMapping(value = "/upload")
@ResponseBody
@NoPermission
public String upload(MultipartFile file) {
String url = baseUrl +"/open/api/v1/invoices/uploadFile";
final byte[] bytes ;
try {
bytes = file.getBytes();
String appKey = "";
String version = "1.0";
String secretkey = "";
String timestamp = String.valueOf(System.currentTimeMillis());
//注意此处签名无 body拼接
String localString = "&Timestamp=" + timestamp + "&AppKey=" + appKey + "&Version=" + version + "&SecretKey" + secretkey;
String sigin = Md5Util.getMd5(localString);
MultipartBody body = new MultipartBody.Builder()
.setType(MediaType.parse("multipart/form-data"))
.addFormDataPart("file", file.getOriginalFilename(), okhttp3.RequestBody.create(MediaType.parse("image/" + "打款凭证"), bytes))
.build();
Request request = new Request.Builder()
.post(body)
.addHeader("AppKey", appKey)
.addHeader("Timestamp", timestamp)
.addHeader("Version", "1.0")
.addHeader("Sign", sigin)
.url(url)
.build();
Call call = HttpUtil.getOkHttpClient().newCall(request);
try {
Response response = call.execute();
String res = response.body().string();
log.info("res====" + res);
return res;
} catch (IOException e) {
log.error("HttpUtil.post网络请求失败：{}", e.getMessage());
return "网络请求失败";
}
} catch (IOException e) {
log.warn("fail to read file", file.getOriginalFilename(), e);
}
return null;
}
```
postman 直接请求示例：
