第三章 模块接口(1) - 个体户注册
## 综合服务云平台 - API功能模块接口明细
## 2. 接口加解密
>d 接口调用细节流程：
◆ 参数RSA加密[接口签名，加解密说明](https://easydoc.net/doc/75132717/8V9YDbr8/kdZwDrFp)
◆ 将加密结果以及公共参数拼接成新的字符串通过MD5加密生成签名
◆ 将公共参数以及签名通过header传输，参数加密结果通过body传输，发起http请求
◆ 返回结果解密[接口签名，加解密说明](https://easydoc.net/doc/75132717/8V9YDbr8/kdZwDrFp)
## 接口响应参数都为如下固定json格式
|参数名称|参数含义|数据类型|是否必有|参数备注|
|-|-|-|-|-|
|resopnseType| 返回类型|int|是|无需关注此值|
|errorCode|错误码 |String|是|详情参考[系统错误码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|errorMessage| 错误信息|String|是|详情参考[系统错误码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|status|状态码|int|是|详情参考[系统错误码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|success|是否成功|boolean|是|true：成功 false：失败|
|data|返回结果数据|String|否|只有当success为true才会有该值，该值为RSA加密值，需解密使用,解密规则请看[接口签名，加解密说明](https://easydoc.net/doc/75132717/8V9YDbr8/kdZwDrFp)|
## 3. 个体工商户注册管理
## 3.1 个体工商户注册状态回调通知
>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","name":"张三","status":30,"mobile":"1888888888","refuseType":"","refuseReason":"","companyName":"xxxx","taxNumber":"xxxx","mobile":"xxxx","address":"xxxx","businessLicense":"xxxxx","realNameCollectionUrl":"xxxx"}";
```
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|name|法人姓名|String|是||
|idCard|法人身份证号码|String|是||
|status|状态|Integer|是|详情请看[个体户注册状态码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)（当状态变更到”经营中“后后就可以提交结算申请了）|
|taxStatus|税务状态|Integer|是|0：未实名，1：已实名。当该状态变为“已实名”后才可以进行开票申请操作||
|refuseType|拒绝类型|Integer|否|0：签名无法识别，请重新签名|
|refuseReason|审核拒绝原因|String|否||
|companyName|个体户公司名称|String|是||
|taxNumber|税号|String|否|个体户注册成功之后才会有税号|
|mobile|注册手机号码|String|是||
|address|注册地址|String|是||
|taxType|个税算法类型|String|是|0:累进制、1核定制、2、双定制|
|businessLicense|营业执照|String|否|个体户注册成功之后才会有|
## 3.2 获取企业合作主体，发票类目等信息
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/selfRegistered/queryCompanyInfo
#### 请求方式：POST
#### 请求参数说明：无需传任何参数
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|source|所属业务线|Integer|是|2:轻税业务 3:账管家业务|
|mainstayId|合作主体|Integer|是||
|name|合作主体名称|String|是||
|industryCode|所属行业code|String|是||
|industryName|所属行业名称|String|是||
|invoiceCode|发票编码|String|是||
|invoiceContent|发票内容|String|是||
>d 示例数据结构如下
```json
[{
"akMainstayOpResponses": [{
"invoiceOpResponseList": [{
"industryCode": "ZXBYFW",
"industryName": "装卸搬运服务",
"invoiceCode": "WLFZFWXSZXF",
"invoiceContent": "物流辅助服务**运输装卸费"
}],
"mainstayId": 主体ID,
"name": "主体2"
}, {
"invoiceOpResponseList": [{
"industryCode": "ZXBYFW",
"industryName": "装卸搬运服务",
"invoiceCode": "WLFZFWXSZXF",
"invoiceContent": "物流辅助服务**运输装卸费"
}],
"mainstayId": 主体Id,
"name": "主体3"
}, {
"invoiceOpResponseList": [{ //发票列表
"industryCode": "ZXBYFW",
"industryName": "装卸搬运服务",
"invoiceCode": "WLFZFWXSZXF",
"invoiceContent": "物流辅助服务**运输装卸费"
}, {
"industryCode": "ZXBYFW",
"industryName": "装卸搬运服务",
"invoiceCode": "WLFZFWZXBYFW",
"invoiceContent": "物流辅助服务*装卸搬运服务"
}],
"mainstayId": 主体ID,
"name": "主体1"
}],
"source": 3 //所属业务线 账管家
}, {
"akMainstayOpResponses": [{
"invoiceOpResponseList": [{
"industryCode": "YXTG_01",
"industryName": "营销推广",
"invoiceCode": "XDFWCHFWF",
"invoiceContent": "现代服务*策划服务费"
}, {
"industryCode": "YXTG_01",
"industryName": "营销推广",
"invoiceCode": "XDFWTGFWF",
"invoiceContent": "现代服务*推广服务费"
}, {
"industryCode": "YXTG_01",
"industryName": "营销推广",
"invoiceCode": "XDFWYXFWF",
"invoiceContent": "现代服务*营销服务费"
}, {
"industryCode": "KJHY_01",
"industryName": "科技行业",
"invoiceCode": "XXJSFWJSFWF",
"invoiceContent": "信息技术服务*技术服务费"
}],
"mainstayId": 主体ID,
"name": "主体1"
}, {
"invoiceOpResponseList": [{
"industryCode": "WLGW_02",
"industryName": "管理&顾问",
"invoiceCode": "JZZXFWZXFWF",
"invoiceContent": "鉴证咨询服务*咨询服务费"
}, {
"industryCode": "YXTG_02",
"industryName": "营销推广",
"invoiceCode": "XDFWCHFWF",
"invoiceContent": "现代服务*策划服务费"
}],
"mainstayId":主体Id,
"name": "主体2"
}, {
"invoiceOpResponseList": [{
"industryCode": "WHZB_03",
"industryName": "网红&直播",
"invoiceCode": "XDFWHLWXXFW",
"invoiceContent": "现代服务*互联网信息服务"
}],
"mainstayId": 主体Id,
"name": "主体3"
}],
"source": 2 //所属业务线 轻税
}]
```
## 3.3 个体工商户查询接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/qs/qsSelfEmployedQuery
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCard|个体户身份证号|String|是||
|mainstayId|注册地|String|是|该参数值由[3.2 获取企业合作主体，发票类目等信息](https://easydoc.net/doc/75132717/8V9YDbr8/F6qlESys) 获得|
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|status| 个体户状态|Integer|是|个体户状态请查阅：[4. 个体户查询状态码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|taxStatus|税务状态|Integer|是|0：未实名，1：已实名。当该状态变为“已实名”后才可以进行开票申请操作||
|isRefuse| 是否审核拒绝 0:未拒绝 1：审核拒绝|String|是|当个体户审核拒绝时候，该参数值为 1(表示审核拒绝)。个体户状态（status）参数依旧为 -1（待申请状态）。|
|name|个体户姓名|String|是|例：张三|
|idCard|个体户身份证号|String|是|例：410422199405051167|
|mainstayName|注册地|String|是|例：长兴|
|companyName|公司名|String|是|例：xxxx有限公司|
|taxNumber|纳税人识别号|String|否|例：91330100FS234（纳税人识别号）|
|phoneAddress|手机号、地址|String|否|例：浙江省杭州市滨江区网商路xx号 130xxxx3381|
|bankNameAccount|开户行及账户信息|String|否|例：中国工商银行杭州富春支行 330501164xxxxxxx|
|license| 营业执照|String|否|例：https://qiniu.lx-rhino.com/XXXX|
|failReason| 异常原因|String|否|该参数内容可能为空，成功的时候失败原因为空字符串|
|taxType|个税类型|Integer|是|0 累进制、1 核定制 2、双定制|
## 3.4 个体户工商户白名单创建
>d 注意：上传身份证正反面有两种方式(可选)：第一，传入图片的方式（参数fileIdCardFront文件、fileIdCardBack文件），第二，传入图片链接的方式（idCardFrontUrl、idCardBackUrl）。 当同时传入（fileIdCardFront文件、fileIdCardBack文件）和data参数中（idCardFrontUrl、idCardBackUrl）时，优先使用（fileIdCardFront文件、fileIdCardBack文件）
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/selfRegistered/qsSelfEmployedImport
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|fileIdCardFront|上传的身份证正面图片|MultipartFile|否|该参数值是身份证正面图片（注：不能仅传入该参数，应与身份证反面（fileIdCardBack）一起传）|
|fileIdCardBack|上传的身份证反面图片|MultipartFile|否|该参数值是身份证反面图片（注：不能仅传入该参数，应与身份证正面（fileIdCardFront）一起传）|
|data|该参数为个体户信息json加密后的值|String|是|说明示例如下 |
#### data数据中参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|name|个体户姓名|String|是|例：张三|
|idCard|个体户身份证号|String|是|例：410422199405051167|
|phone|个体户手机号|String|否|例：130xxxx3381|
|mainstayId|注册地|String|是|该参数值由 3.2 获取企业合作主体，发票类目等信息 获得|
|invoiceCode|开票编码|String|是|可多选（必须属于同一行业），用英文逗号隔开。该参数值由 3.2 获取企业合作主体，发票类目接口获得|
|industryCode|所属行业code|String|是|该参数值由 3.2 获取企业合作主体，发票类目等信息) 获得|
|idCardFrontUrl|身份证正面|String|否|该参数值由身份证正面图片的URL地址（注：不能仅传入该参数，应与身份证反面（idCardBackUrl）一起传）|
|idCardBackUrl|身份证反面|String|否|该参数值由身份证反面图片的URL地址（注：不能仅传入该参数，应与身份证正面（idCardFrontUrl）一起传）|
|taxType|个税算法类型|String|是|0:累进制、1核定制、2、双定制|
>d data参数示例如下
```java
String paramsJson = "{\"idCard\":\"xxxx\",\"idCardBackUrl\":\"https://xxxx/xxxx.jpeg\",\"idCardFrontUrl\":\"https://xxxx/xxxx.jpeg\",\"industryCode\":\"xxxx\",\"invoiceCode\":\"xxxx\",\"mainstayId\":\"xxxx\",\"name\":\"xxxx\",\"phone\":\"xxxx\"}"
String data= RSAHelper.encryptByPublicKey(paramsJson, publicKey);
```
#### 接口响应参数data字段解密后的参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|transNo|支付订单号|String|是||
|status|个体户状态|Integer|是|[4.个体户查询状态码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|paymentStatus|支付状态|Integer|是|[7.系统管理费 - 支付状态](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|amount|支付金额|BigDecimal|是||
|confType|付款类型|Integer|是|[8.系统管理费 - 付款方式状态码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)|
|balance|剩余金额|BigDecimal|是|平台的系统管理费账户的余额|
|failReason|失败原因|String|是|该参数内容可能为空，成功的时候失败原因为空字符串|
## 3.5 免密登录获取链接
>d 该接口适用场景
将综合服务平台个体户注册H5页面嵌入自己公司的APP，小程序或者公众号为了不让用户再次输入手机验证码进行登录操作。提升用户体验度。
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：
/open/api/v1/qs/getTokenUrl
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|mobile|手机号|String|是|请求示例:{"mobile":"xxxxx"}|
#### 接口响应参数data字段解密后的参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|url|个体户注册链接|String|是|该链接有效时间为两分钟，如果两分钟未使用则需要重新获取一下。使用过之后会失效，第二次重新进入需要重新获取|
```json
# 响应参数示例如下。只有当 success等于true的时候才会有data里面的值
{
"resopnseType": 0,
"errorCode": "",
"errorMessage": "",
"status": 0,
"data": "UXgTVjlGdO+ughW8ZGTn2gc4CTuJEY9oUxBjKm4YaMzcPiExl5OX7sfQuQzfjLrjVwvrT1kmp8mpan0WEw3mqwuMga3tT/kkUU8wb5/TpwjG6O68rgWrHlI5PEI+dy4jgBGiJhOd1ReuVYbDZQb/06cYD5WbELGQJIuBVjZF7RA=",
"ext": null,
"extMessage": null,
"success": true
}
data解密后的内容：
{
"url": "https://testh5.lanycee.com/nosecret-login?code=359530b9d80728d038c979656d31faa4"
}
```
## 3.6 个体户注销接口
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/selfRegistered/selfEmployedLogout
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCard|身份证号码|String|是|
|mainstayId|主体ID|Integer|是|
|source|业务线|Integer|是| 2：轻税,3：账管家,4：云纳税|
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|status|个体户状态|Integer|是|[3.个体户注册状态码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63) 状态码：40 注销中,注销中代表调用接口成功,等待系统处理即可|
|needPay|是否需要支付|boolean|是|ture:需要支付注销费，false:无需支付注销费|
|transNo|注销费支付订单号|String|否|只要当需要支付的时候该字段才有值|
|payAmount|注销费|BigDecimal|否|只要当需要支付的时候该字段才有值|
|agencyTransNos|季度服务费支付订单号|List<String>|否|只要当需要支付的时候该字段才有值|
|agencyPayAmount|季度服务费|BigDecimal|否|只要当需要支付的时候该字段才有值|
|totalPayAmount|总支付金额|BigDecimal|否|只要当需要支付的时候该字段才有值|
#### 注意：
（1）众包模式 - 个体工商户（超额累进）与众包模式 - 个体工商户（定期定额）是不需要支付注销服务费的所以needPay字段返回的就是false；
（2）payAmount 注销服务费是商户入准时合同约定的金额来判断（具体可以咨询商务人员），注销服务费这里指的是单个个体户的注销服务金额；
## 3.7 个体户信息批量查询
开发环境：https://pay-dev.lx-rhino.com
生产环境：https://api.lx-rhino.com
#### 接口地址：/open/api/v1/selfRegistered/qsSelfEmployedBatchQuery
#### 请求方式：POST
#### 请求参数说明：
|参数名称|参数含义|数据类型|是否必填|参数备注|
|-|-|-|-|-|
|idCards|身份证号码|List<String>|是|身份证号码数组，身份证个数不可超过100个|
|mainstayId|主体ID|Integer|是|
#### 接口响应参数说明：
|参数名称|参数含义| 数据类型|是否必有|参数备注|
|-|-|-|-|-|
|name|姓名|String|是||
|idCard|身份证号码|String|是||
|mainstayName|注册地|String|是||
|status|个体户状态|Integer|是|详情请看[3.个体户注册状态码](https://easydoc.net/doc/75132717/8V9YDbr8/6Riyzg63)（该值为经营中的时候才可进行结算）|
|taxStatus|税务状态|Integer|是|0:未实名，1:已实名。该状态为已实名才可进行开票操作|
|taxType|个税算法类型|String|是|0:累进制、1核定制、2、双定制|
|isRefuse|审核拒绝|Integer|0:未拒绝 1：审核拒绝||
|companyName|个体户公司名称|String|是||
|bankNameAccount|开户行及账户信息|String|是||
|taxNumber|税号|String|否|个体户注册成功之后才会有税号|
|phoneAddress|手机号、注册地|String|是||
|license|营业执照|String|否|个体户注册成功之后才会有|
|failReason|异常原因|
|selectStatus|是否查询到|boolean|false：未查询到 true：查询到了|
|source|所属业务线|Integer|2:轻税 3:账管家 4:云纳税|
#### 注意：
（1）selectStatus:返回true代表的能查到该个体户的数据，返回false代表的查询失败，没有查询到个体户的信息；