562 lines
18 KiB
Markdown
562 lines
18 KiB
Markdown
# 兰溪-流水分析对接文档
|
||
|
||
## 概述
|
||
|
||
本文档描述与**见知现金流尽调系统**的对接接口，用于拉取银行流水数据。
|
||
|
||
---
|
||
|
||
## 1. 新建项目并获取Token
|
||
|
||
### 1.1 接口请求地址
|
||
|
||
- **测试环境**: `http://158.234.196.5:82/c4c3/account/common/getToken`
|
||
- **请求方法**: POST
|
||
|
||
### 1.2 请求参数说明
|
||
|
||
> 接口备注：第三方系统中，点击需要查看的项目向见知现金流尽调系统请求访问token，每个项目的token不同。现金流尽调系统根据 ProjectNo为唯一标识查找项目，如果对应的项目不存在则自动创建项目。注意token使用一次后即失效，再次访问项目需要重新申请。（支持拉取金综和行内流水）
|
||
|
||
| 参数名 | 示例值 | 参数类型 | 是否必填 | 参数描述 |
|
||
|--------|--------|----------|----------|----------|
|
||
| projectNo | test-zjnx-1204 | String | 是 | 项目编号 |
|
||
| entityName | 浙江农信test1204 | String | 是 | 项目名称 |
|
||
| userId | test001 | String | 是 | 操作人员编号 |
|
||
| userName | 测试001 | String | 是 | 操作人员姓名 |
|
||
| appId | remote_app | String | 是 | 见知提供appId |
|
||
| appSecretCode | 6ee87a361f29234ad25d7893da9975a9 | String | 是 | 安全码 md5(projectNo + "_" + entityName + "_" + appSecret) |
|
||
| role | VIEWER | String | 否 | 人员角色（VIEWER：普通用户，READER：只读用户）默认值：VIEWER |
|
||
| orgCode | 800000 | String | 是 | 行社机构号 |
|
||
| entityId | ZJNX1234567890 | String | 否 | 企业统信码或个人身份证号 |
|
||
| xdRelatedPersons | [{"relatedPerson":"上海上水纯净水有限公司","relation":"董事长"}] | String | 否 | 信贷关联人信息 |
|
||
| jzDataDateId | 0 | String | 否 | 拉取指定日期推送过来的金综链流水，为0时标识不需要拉取金综链流水 |
|
||
| innerBSStartDateId | 0 | String | 否 | 拉取行内流水开始日期，0:不需要拉取行内流水。流水分析系统根据entityId到数仓中查询行内流水 |
|
||
| innerBSEndDateId | 0 | String | 否 | 拉取行内流水结束日期，0:不需要拉取行内流水。流水分析系统根据entityId到数仓中查询行内流水 |
|
||
| analysisType | -1 | String | 是 | 固定值 |
|
||
| departmentCode | 800111 | String | 是 | 客户经理所属营业部/分理处的机构编码 |
|
||
|
||
### 1.3 返回参数说明
|
||
|
||
#### 成功响应 (200)
|
||
|
||
| 参数名 | 示例值 | 参数类型 | 参数描述 |
|
||
|--------|--------|----------|----------|
|
||
| code | 200 | String | 返回码 |
|
||
| data.token | eyJ0eXAi... | String | token |
|
||
| data.projectId | 77 | Integer | 见知项目Id |
|
||
| data.projectNo | test-zjnx-1204 | String | 项目编号 |
|
||
| data.entityName | 浙江农信test1204 | String | 项目名称 |
|
||
| data.analysisType | 0 | Integer | 分析类型 |
|
||
| message | create.token.success | String | 消息 |
|
||
| status | 200 | String | 状态 |
|
||
| successResponse | true | Boolean | 成功标识 |
|
||
|
||
#### 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 40100 | 未知异常 |
|
||
| 40101 | appId错误 |
|
||
| 40102 | appSecretCode错误 |
|
||
| 40104 | 可使用项目次数为0，无法创建项目 |
|
||
| 40105 | 只读模式下无法新建项目 |
|
||
| 40106 | 错误的分析类型，不在规定的取值范围内 |
|
||
| 40107 | 当前系统不支持的分析类型 |
|
||
| 40108 | 当前用户所属行社无权限 |
|
||
|
||
### 1.4 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||
"projectId": 77,
|
||
"projectNo": "test-zjnx-1204",
|
||
"entityName": "浙江农信test1204",
|
||
"analysisType": 0
|
||
},
|
||
"message": "create.token.success",
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 上传文件接口
|
||
|
||
### 2.1 接口请求地址
|
||
|
||
- **测试环境**: `158.234.196.5:82/c4c3/watson/api/project/remoteUploadSplitFile`
|
||
- **请求方法**: POST
|
||
- **请求头**: `X-Xencio-Client-Id: c2017e8d105c435a96f86373635b6a09`
|
||
|
||
### 2.2 请求参数说明
|
||
|
||
| 参数 | 类型 | 参数名称 | 是否必填 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| groupId | Int | 项目id | 是 | - |
|
||
| files | File | 上传的文件 | 是 | - |
|
||
|
||
### 2.3 响应结果信息
|
||
|
||
| 字段 | 类型 | 备注 |
|
||
|------|------|------|
|
||
| code | String | 200成功，其他状态码失败 |
|
||
| data | Object | 列表 |
|
||
| accountName | - | 主体名称 |
|
||
| accountNo | - | 账号 |
|
||
| uploadFileName | - | 文件名称 |
|
||
| fileSize | - | 文件大小，单位Byte |
|
||
| status | - | 状态值 |
|
||
| uploadStatusDesc | - | 文件状态描述 |
|
||
| bank | - | 所属银行 |
|
||
| currency | - | 币种 |
|
||
| accountId | - | 账号id |
|
||
| logId | - | 文件id |
|
||
|
||
> **注意**: `status`等于-5且`uploadStatusDesc`等于`data.wait.confirm.newaccount`表示当前流水文件上传后解析成功。反之则没有成功。
|
||
|
||
### 2.4 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"accountsOfLog": {
|
||
"13976": [
|
||
{
|
||
"bank": "BSX",
|
||
"accountName": "",
|
||
"accountNo": "虞海良绍兴银行流水",
|
||
"currency": "CNY"
|
||
}
|
||
]
|
||
},
|
||
"uploadLogList": [
|
||
{
|
||
"accountNoList": [],
|
||
"bankName": "BSX",
|
||
"dataTypeInfo": ["CSV", ","],
|
||
"downloadFileName": "虞海良绍兴银行流水.csv",
|
||
"enterpriseNameList": [],
|
||
"filePackageId": "14b13103010e4d32b5406c764cfe3644",
|
||
"fileSize": 46724,
|
||
"fileUploadBy": 448,
|
||
"fileUploadByUserName": "admin@support.com",
|
||
"fileUploadTime": "2025-03-12 18:53:29",
|
||
"leId": 10724,
|
||
"logId": 13976,
|
||
"logMeta": "{\"lostHeader\":[],\"balanceAmount\":true}",
|
||
"logType": "bankstatement",
|
||
"loginLeId": 10724,
|
||
"realBankName": "BSX",
|
||
"rows": 0,
|
||
"source": "http",
|
||
"status": -5,
|
||
"templateName": "BSX_T240925",
|
||
"totalRecords": 280,
|
||
"trxDateEndId": 20240905,
|
||
"trxDateStartId": 20230914,
|
||
"uploadFileName": "虞海良绍兴银行流水.csv",
|
||
"uploadStatusDesc": "data.wait.confirm.newaccount"
|
||
}
|
||
],
|
||
"uploadStatus": 1
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 拉取行内流水接口
|
||
|
||
### 3.1 接口请求地址
|
||
|
||
- **测试环境**: `158.234.196.5:82/c4c3/watson/api/project/getJZFileOrZjrcuFile`
|
||
- **请求方法**: POST
|
||
- **请求头**: `X-Xencio-Client-Id: c2017e8d105c435a96f86373635b6a09`
|
||
|
||
### 3.2 请求参数说明
|
||
|
||
| 参数 | 类型 | 参数名称 | 是否必填 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| groupId | Int | 项目id | 是 | - |
|
||
| customerNo | String | 客户身份证号 | 是 | - |
|
||
| dataChannelCode | String | 校验码 | 是 | 固定值: ZJRCU |
|
||
| requestDateId | Int | 发起请求的时间 | 是 | 当天请求时间 |
|
||
| dataStartDateId | Int | 拉取开始日期 | 是 | - |
|
||
| dataEndDateId | Int | 拉取结束日期 | 是 | - |
|
||
| uploadUserId | int | 柜员号 | 是 | - |
|
||
|
||
### 3.3 响应结果信息
|
||
|
||
| 序号 | 字段 | 类型 | 备注 |
|
||
|------|------|------|------|
|
||
| 1 | code | String | 200成功，其他状态码失败 |
|
||
| 2 | data | Object | 列表 |
|
||
|
||
### 3.4 返回示例（无行内流水）
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"code": "501014",
|
||
"message": "无行内流水文件"
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 判断文件是否解析结束
|
||
|
||
### 4.1 接口请求地址
|
||
|
||
- **测试环境**: `http://158.234.196.5:82/c4c3/watson/api/project/upload/getpendings`
|
||
- **请求方法**: POST
|
||
- **请求头**: `X-Xencio-Client-Id: c2017e8d105c435a96f86373635b6a09`
|
||
|
||
### 4.2 请求参数说明
|
||
|
||
| 参数 | 类型 | 参数名称 | 是否必填 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| groupId | Int | 项目id | 是 | - |
|
||
| inprogressList | String | 文件id | 是 | - |
|
||
|
||
### 4.3 响应结果信息
|
||
|
||
| 序号 | 字段 | 类型 | 备注 |
|
||
|------|------|------|------|
|
||
| 1 | code | String | 200成功，其他状态码失败 |
|
||
| 2 | data | Object | 列表 |
|
||
| 3 | uploadFileName | - | 上传文件名称 |
|
||
| 4 | status | - | 文件解析后状态值 |
|
||
| 5 | uploadStatusDesc | - | 文件解析后状态描述 |
|
||
| 6 | parsing | - | 文件解析状态，true表示解析中，false表示解析结束 |
|
||
|
||
> **注意**: 文件解析有个处理过程，`parsing`为false表示解析结束，可以轮询调用此接口，`status`等于-5且`uploadStatusDesc`等于`data.wait.confirm.newaccount`表示文件解析成功。
|
||
|
||
### 4.4 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"parsing": false,
|
||
"pendingList": [
|
||
{
|
||
"accountNoList": [],
|
||
"bankName": "ZJRCU",
|
||
"dataTypeInfo": ["CSV", ","],
|
||
"downloadFileName": "230902199012261247_20260201_20260201_1772096608615.csv",
|
||
"enterpriseNameList": [],
|
||
"filePackageId": "cde6c7cf5cab48e8892f0c1c36b2aa7d",
|
||
"fileSize": 53101,
|
||
"fileUploadBy": 448,
|
||
"fileUploadByUserName": "admin@support.com",
|
||
"fileUploadTime": "2026-02-27 09:50:18",
|
||
"isSplit": 0,
|
||
"leId": 16210,
|
||
"logId": 19116,
|
||
"logMeta": "{\"lostHeader\":[],\"balanceAmount\":true}",
|
||
"logType": "bankstatement",
|
||
"loginLeId": 16210,
|
||
"lostHeader": [],
|
||
"realBankName": "ZJRCU",
|
||
"rows": 0,
|
||
"source": "http",
|
||
"status": -5,
|
||
"templateName": "ZJRCU_T251114",
|
||
"totalRecords": 131,
|
||
"trxDateEndId": 20240228,
|
||
"trxDateStartId": 20240201,
|
||
"uploadFileName": "230902199012261247_20260201_20260201_1772096608615.csv",
|
||
"uploadStatusDesc": "data.wait.confirm.newaccount"
|
||
}
|
||
]
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 生成尽调报告接口
|
||
|
||
### 5.1 接口请求地址
|
||
|
||
- **测试环境**: `158.234.196.5:82/c4c3/watson/api/project/confirmStageUploadLogs`
|
||
- **请求方法**: POST
|
||
- **请求头**: `X-Xencio-Client-Id: c2017e8d105c435a96f86373635b6a09`
|
||
|
||
### 5.2 请求参数说明
|
||
|
||
| 参数 | 类型 | 参数名称 | 是否必填 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| groupId | Int | 项目id | 是 | - |
|
||
| logIds | Array | 文件id数组 | 是 | 上传几个文件就用几个 |
|
||
| userLogin | Int | 登录柜员号 | 是 | - |
|
||
|
||
### 5.3 响应结果信息
|
||
|
||
| 序号 | 字段 | 类型 | 备注 |
|
||
|------|------|------|------|
|
||
| 1 | Code | String | 200成功，其他状态码失败 |
|
||
| 2 | Data | Object | 列表 |
|
||
|
||
### 5.4 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"message": "upload.confirm.ok"
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 判断尽调报告是否生成
|
||
|
||
### 6.1 接口请求地址
|
||
|
||
- **测试环境**: `158.234.196.5:82/c4c3/watson/api/project/upload/getallpendings?groupId=#{groupId}`
|
||
- **请求方法**: GET
|
||
- **请求头**: `X-Xencio-Client-Id: c2017e8d105c435a96f86373635b6a09`
|
||
|
||
### 6.2 请求参数说明
|
||
|
||
| 参数 | 类型 | 参数名称 | 是否必填 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| groupId | Int | 项目id | 是 | - |
|
||
|
||
### 6.3 响应结果信息
|
||
|
||
| 序号 | 字段 | 类型 | 备注 |
|
||
|------|------|------|------|
|
||
| 1 | code | String | 200成功，其他状态码失败 |
|
||
| 2 | data | Object | 列表 |
|
||
|
||
> **注意**: 生成尽调报告有个处理过程，`pendingList`为[]表示处理结束，可以轮询调用此接口。
|
||
|
||
### 6.4 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"pendingList": []
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 获取流水列表并存储到兰溪本地
|
||
|
||
### 7.1 接口请求地址
|
||
|
||
- **测试环境**: `158.234.196.5:82/c4c3/watson/api/project/upload/getBankStatement`
|
||
- **请求方法**: POST
|
||
- **请求头**: `X-Xencio-Client-Id: c2017e8d105c435a96f86373635b6a09`
|
||
|
||
### 7.2 请求参数说明
|
||
|
||
| 参数 | 类型 | 参数名称 | 是否必填 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| groupId | Int | 项目id | 是 | - |
|
||
| logId | Int | 文件id | 是 | - |
|
||
| pageNow | Int | 当前页码 | 是 | - |
|
||
| pageSize | Int | 查询条数 | 是 | - |
|
||
|
||
### 7.3 响应结果信息
|
||
|
||
| 序号 | 字段 | 类型 | 备注 |
|
||
|------|------|------|------|
|
||
| 1 | code | String | 200成功，其他状态码失败 |
|
||
| 2 | data | Object | 列表 |
|
||
| 3 | bankStatementList | - | 流水列表 |
|
||
| 4 | pageable | - | 分页参数 |
|
||
| 5 | searchable | - | 查询参数 |
|
||
|
||
### 7.4 流水字段说明
|
||
|
||
| 字段名 | 说明 | 示例值 |
|
||
|--------|------|--------|
|
||
| accountId | 账户ID | 0 |
|
||
| accountMaskNo | 账号 | 6228580199062321798 |
|
||
| accountingDate | 记账日期 | 2025-02-03 |
|
||
| accountingDateId | 记账日期ID | 20250203 |
|
||
| balanceAmount | 余额 | 85688.37 |
|
||
| bank | 银行代码 | AI |
|
||
| bankComments | 银行备注 | - |
|
||
| bankStatementId | 流水ID | 4585279 |
|
||
| catalogName | 交易名称 | 收单收入 |
|
||
| crAmount | 贷方金额 | 290 |
|
||
| currency | 币种 | CNY |
|
||
| customerAccountMaskNo | 客户账号 | 80100001471621000100 |
|
||
| customerAccountName | 客户账户名 | 系统内清算资金往来-全渠道收单平台 |
|
||
| customerName | 客户名称 | 系统内清算资金往来-全渠道收单平台 |
|
||
| drAmount | 借方金额 | 0 |
|
||
| leName | 企业名称 | 徐设华 |
|
||
| transAmount | 交易金额 | 290 |
|
||
| transFlag | 交易标志 | R |
|
||
| transTypeName | 交易名称 | 收单收入 |
|
||
| trxDate | 交易日期 | 2025-02-03 00:00:00 |
|
||
| userMemo | 用户备注 | 收单 |
|
||
|
||
### 7.5 返回示例
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"bankStatementList": [
|
||
{
|
||
"accountId": 0,
|
||
"accountMaskNo": "6228580199062321798",
|
||
"accountingDate": "2025-02-03",
|
||
"accountingDateId": 20250203,
|
||
"archivingFlag": 0,
|
||
"attachments": 0,
|
||
"balanceAmount": 85688.37,
|
||
"bank": "AI",
|
||
"bankComments": "",
|
||
"bankStatementId": 4585279,
|
||
"bankTrxNumber": "",
|
||
"cashType": "",
|
||
"catalogName": "收单收入",
|
||
"commentsNum": 0,
|
||
"crAmount": 290,
|
||
"currency": "CNY",
|
||
"customNoteCount": 0,
|
||
"customerAccountMaskNo": "80100001471621000100",
|
||
"customerAccountName": "系统内清算资金往来-全渠道收单平台",
|
||
"customerId": 0,
|
||
"customerName": "系统内清算资金往来-全渠道收单平台",
|
||
"customerReference": "",
|
||
"downPaymentFlag": 0,
|
||
"drAmount": 0,
|
||
"hasCustomNote": 0,
|
||
"internalFlag": 0,
|
||
"isMarked": 0,
|
||
"leId": 16260,
|
||
"leName": "徐设华",
|
||
"sourceCatalogId": 405625,
|
||
"split": 0,
|
||
"subBankstatementId": 0,
|
||
"toDoFlag": 0,
|
||
"transAmount": 290,
|
||
"transFlag": "R",
|
||
"transTypeId": 405625,
|
||
"transTypeName": "收单收入",
|
||
"transformAmount": 290,
|
||
"transformCrAmount": 290,
|
||
"transformDrAmount": 0,
|
||
"transfromBalanceAmount": 85688.37,
|
||
"trxBalance": 0,
|
||
"trxDate": "2025-02-03 00:00:00",
|
||
"trxFlag": "R",
|
||
"userMemo": "收单"
|
||
}
|
||
],
|
||
"pageable": {
|
||
"hasNext": true,
|
||
"hasPre": false,
|
||
"isFirst": true,
|
||
"isLast": false,
|
||
"pageNow": 1,
|
||
"pageSize": 1,
|
||
"startPos": 0,
|
||
"totalCount": 3392,
|
||
"totalPageCount": 3392
|
||
},
|
||
"searchable": {
|
||
"appInput": 0,
|
||
"dayFromId": 0,
|
||
"dayToId": 0,
|
||
"endDateId": 0,
|
||
"enterpriseId": 0,
|
||
"groupTypeId": 0,
|
||
"logId": 19060,
|
||
"pageNow": 1,
|
||
"pageSize": 1,
|
||
"showDownPayment": 0,
|
||
"startDateId": 0,
|
||
"trxAmount": 0,
|
||
"trxTypeId": 0,
|
||
"uploadFromDateId": 0,
|
||
"uploadToDateId": 0,
|
||
"useForBsSearch": 0,
|
||
"useNameExactMatching": 0,
|
||
"withOrderBy": true
|
||
}
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口调用流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 1. 初始化调用 /account/common/getToken 接口创建项目 │
|
||
│ ↓ │
|
||
│ 2. 调用 /remoteUploadSplitFile 接口上传文件 │
|
||
│ 或调用 /getJZFileOrZjrcuFile 拉取行内流水 │
|
||
│ ↓ │
|
||
│ 3. 调用 /getpendings 获取文件解析状态 │
|
||
│ - parsing=true 时，间隔1s轮询 │
|
||
│ - parsing=false 且 status=-5 表示解析成功 │
|
||
│ ↓ │
|
||
│ 4. 调用 /confirmStageUploadLogs 接口生成尽调报告 │
|
||
│ ↓ │
|
||
│ 5. 调用 /getallpending 检查尽调报告生成状态 │
|
||
│ - pendingList 不为空时，间隔1s轮询 │
|
||
│ - pendingList=[] 表示生成完成 │
|
||
│ ↓ │
|
||
│ 6. 调用 /getBankStatement 接口获取流水数据存储到兰溪本地 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 生产环境配置
|
||
|
||
| 配置项 | 值 |
|
||
|--------|-----|
|
||
| 生产IP | 64.202.32.176 |
|
||
| 生产X-Xencio-Client-Id | 通过接口获取 |
|
||
|
||
### 获取生产环境 Client-Id
|
||
|
||
```
|
||
GET http://64.202.32.176/c4c3/watson/api/common/GenerateAccessKey?userLogin={流水分析平台登录柜员号}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：公共请求头
|
||
|
||
| 请求头 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| X-Xencio-Client-Id | c2017e8d105c435a96f86373635b6a09 | 测试环境固定值 |
|
||
| Content-Type | application/json | POST请求 |
|