# 兰溪-流水分析对接文档

## 概述

本文档描述与**见知现金流尽调系统**的对接接口，用于拉取银行流水数据。

---

## 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请求  |
