feat: 修复接口参数并改为form-data格式
- 添加缺失的认证参数：appId, appSecretCode, role - 修复 analysisType 和 departmentCode 参数 - 将所有接口改为使用 Form 参数（form-data 格式） - 更新服务层支持字典参数 - 更新所有测试代码 - 所有测试通过（7/7）
This commit is contained in:
415
接口调用示例.md
Normal file
415
接口调用示例.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# 📖 接口调用示例
|
||||
|
||||
## 测试日期
|
||||
2026-03-03
|
||||
|
||||
## 传输格式
|
||||
**所有接口使用 Form-Data 格式** (`application/x-www-form-urlencoded`)
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ 获取 Token
|
||||
|
||||
### Python requests
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8000/account/common/getToken",
|
||||
data={ # ✅ 使用 data 参数
|
||||
"projectNo": "test_001",
|
||||
"entityName": "测试企业",
|
||||
"userId": "902001",
|
||||
"userName": "902001",
|
||||
"appId": "remote_app",
|
||||
"appSecretCode": "your_secret_code",
|
||||
"role": "VIEWER",
|
||||
"orgCode": "902000",
|
||||
"departmentCode": "902000"
|
||||
}
|
||||
)
|
||||
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/account/common/getToken \
|
||||
-d "projectNo=test_001" \
|
||||
-d "entityName=测试企业" \
|
||||
-d "userId=902001" \
|
||||
-d "userName=902001" \
|
||||
-d "appId=remote_app" \
|
||||
-d "appSecretCode=your_secret_code" \
|
||||
-d "role=VIEWER" \
|
||||
-d "orgCode=902000" \
|
||||
-d "departmentCode=902000"
|
||||
```
|
||||
|
||||
### JavaScript fetch
|
||||
```javascript
|
||||
const formData = new FormData();
|
||||
formData.append('projectNo', 'test_001');
|
||||
formData.append('entityName', '测试企业');
|
||||
formData.append('userId', '902001');
|
||||
formData.append('userName', '902001');
|
||||
formData.append('appId', 'remote_app');
|
||||
formData.append('appSecretCode', 'your_secret_code');
|
||||
formData.append('role', 'VIEWER');
|
||||
formData.append('orgCode', '902000');
|
||||
formData.append('departmentCode', '902000');
|
||||
|
||||
fetch('http://localhost:8000/account/common/getToken', {
|
||||
method: 'POST',
|
||||
body: formData
|
||||
})
|
||||
.then(response => response.json())
|
||||
.then(data => console.log(data));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ 上传文件
|
||||
|
||||
### Python requests
|
||||
```python
|
||||
import requests
|
||||
|
||||
# 获取 token 后得到 project_id
|
||||
project_id = 10001
|
||||
|
||||
# 上传文件
|
||||
files = {'file': ('statement.csv', open('statement.csv', 'rb'), 'text/csv')}
|
||||
data = {'groupId': project_id}
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8000/watson/api/project/remoteUploadSplitFile",
|
||||
files=files,
|
||||
data=data
|
||||
)
|
||||
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/watson/api/project/remoteUploadSplitFile \
|
||||
-F "file=@statement.csv" \
|
||||
-F "groupId=10001"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ 拉取行内流水
|
||||
|
||||
### Python requests
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8000/watson/api/project/getJZFileOrZjrcuFile",
|
||||
data={
|
||||
"groupId": 10001,
|
||||
"customerNo": "330102199001011234",
|
||||
"dataChannelCode": "ZJRCU",
|
||||
"requestDateId": 20260303,
|
||||
"dataStartDateId": 20260101,
|
||||
"dataEndDateId": 20260303,
|
||||
"uploadUserId": 902001
|
||||
}
|
||||
)
|
||||
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/watson/api/project/getJZFileOrZjrcuFile \
|
||||
-d "groupId=10001" \
|
||||
-d "customerNo=330102199001011234" \
|
||||
-d "dataChannelCode=ZJRCU" \
|
||||
-d "requestDateId=20260303" \
|
||||
-d "dataStartDateId=20260101" \
|
||||
-d "dataEndDateId=20260303" \
|
||||
-d "uploadUserId=902001"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4️⃣ 检查文件解析状态
|
||||
|
||||
### Python requests
|
||||
```python
|
||||
import requests
|
||||
import time
|
||||
|
||||
log_id = 10001
|
||||
|
||||
# 轮询检查解析状态
|
||||
for i in range(10):
|
||||
response = requests.post(
|
||||
"http://localhost:8000/watson/api/project/upload/getpendings",
|
||||
data={
|
||||
"groupId": 10001,
|
||||
"inprogressList": str(log_id)
|
||||
}
|
||||
)
|
||||
|
||||
result = response.json()
|
||||
print(f"第{i+1}次检查: parsing={result['data']['parsing']}")
|
||||
|
||||
if not result['data']['parsing']:
|
||||
print("✅ 解析完成")
|
||||
break
|
||||
|
||||
time.sleep(1)
|
||||
```
|
||||
|
||||
### curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/watson/api/project/upload/getpendings \
|
||||
-d "groupId=10001" \
|
||||
-d "inprogressList=10001"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5️⃣ 删除文件
|
||||
|
||||
### Python requests
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8000/watson/api/project/batchDeleteUploadFile",
|
||||
data={
|
||||
"groupId": 10001,
|
||||
"logIds": "10001,10002,10003", # 逗号分隔的文件ID
|
||||
"userId": 902001
|
||||
}
|
||||
)
|
||||
|
||||
print(response.json())
|
||||
```
|
||||
|
||||
### curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/watson/api/project/batchDeleteUploadFile \
|
||||
-d "groupId=10001" \
|
||||
-d "logIds=10001,10002,10003" \
|
||||
-d "userId=902001"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6️⃣ 获取银行流水
|
||||
|
||||
### Python requests
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"http://localhost:8000/watson/api/project/getBSByLogId",
|
||||
data={
|
||||
"groupId": 10001,
|
||||
"logId": 10001,
|
||||
"pageNow": 1,
|
||||
"pageSize": 10
|
||||
}
|
||||
)
|
||||
|
||||
result = response.json()
|
||||
print(f"总记录数: {result['data']['totalCount']}")
|
||||
print(f"当前页数据: {len(result['data']['bankStatementList'])} 条")
|
||||
|
||||
for statement in result['data']['bankStatementList']:
|
||||
print(f"交易日期: {statement['trxDate']}, 金额: {statement['transAmount']}")
|
||||
```
|
||||
|
||||
### curl
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/watson/api/project/getBSByLogId \
|
||||
-d "groupId=10001" \
|
||||
-d "logId=10001" \
|
||||
-d "pageNow=1" \
|
||||
-d "pageSize=10"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 完整工作流程示例
|
||||
|
||||
### Python 完整示例
|
||||
```python
|
||||
import requests
|
||||
import time
|
||||
|
||||
BASE_URL = "http://localhost:8000"
|
||||
|
||||
# 1. 获取 Token
|
||||
print("1️⃣ 获取 Token...")
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/account/common/getToken",
|
||||
data={
|
||||
"projectNo": "test_001",
|
||||
"entityName": "测试企业",
|
||||
"userId": "902001",
|
||||
"userName": "902001",
|
||||
"appId": "remote_app",
|
||||
"appSecretCode": "your_code",
|
||||
"role": "VIEWER",
|
||||
"orgCode": "902000",
|
||||
"departmentCode": "902000"
|
||||
}
|
||||
)
|
||||
|
||||
token_data = response.json()
|
||||
project_id = token_data['data']['projectId']
|
||||
print(f"✅ Token 获取成功，项目ID: {project_id}")
|
||||
|
||||
# 2. 上传文件
|
||||
print("\n2️⃣ 上传文件...")
|
||||
files = {'file': ('test.csv', b'test data', 'text/csv')}
|
||||
data = {'groupId': project_id}
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/watson/api/project/remoteUploadSplitFile",
|
||||
files=files,
|
||||
data=data
|
||||
)
|
||||
|
||||
upload_data = response.json()
|
||||
log_id = upload_data['data']['uploadLogList'][0]['logId']
|
||||
print(f"✅ 文件上传成功，logId: {log_id}")
|
||||
|
||||
# 3. 轮询检查解析状态
|
||||
print("\n3️⃣ 检查解析状态...")
|
||||
for i in range(10):
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/watson/api/project/upload/getpendings",
|
||||
data={
|
||||
"groupId": project_id,
|
||||
"inprogressList": str(log_id)
|
||||
}
|
||||
)
|
||||
|
||||
result = response.json()
|
||||
if not result['data']['parsing']:
|
||||
print(f"✅ 解析完成（第{i+1}次检查）")
|
||||
break
|
||||
print(f"⏳ 解析中...（第{i+1}次检查）")
|
||||
time.sleep(1)
|
||||
|
||||
# 4. 获取银行流水
|
||||
print("\n4️⃣ 获取银行流水...")
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/watson/api/project/getBSByLogId",
|
||||
data={
|
||||
"groupId": project_id,
|
||||
"logId": log_id,
|
||||
"pageNow": 1,
|
||||
"pageSize": 5
|
||||
}
|
||||
)
|
||||
|
||||
statements = response.json()
|
||||
print(f"✅ 获取到 {statements['data']['totalCount']} 条流水记录")
|
||||
print(f" 当前页显示 {len(statements['data']['bankStatementList'])} 条")
|
||||
|
||||
# 5. 删除文件
|
||||
print("\n5️⃣ 删除文件...")
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/watson/api/project/batchDeleteUploadFile",
|
||||
data={
|
||||
"groupId": project_id,
|
||||
"logIds": str(log_id),
|
||||
"userId": 902001
|
||||
}
|
||||
)
|
||||
|
||||
print(f"✅ 文件删除成功")
|
||||
|
||||
print("\n🎉 完整流程测试完成！")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见错误
|
||||
|
||||
### ❌ 错误：使用 JSON 格式
|
||||
```python
|
||||
# ❌ 错误
|
||||
response = requests.post(
|
||||
"http://localhost:8000/account/common/getToken",
|
||||
json={ # 错误：使用了 json 参数
|
||||
"projectNo": "test_001",
|
||||
...
|
||||
}
|
||||
)
|
||||
# 返回: 422 Unprocessable Entity
|
||||
```
|
||||
|
||||
### ✅ 正确：使用 Form-Data
|
||||
```python
|
||||
# ✅ 正确
|
||||
response = requests.post(
|
||||
"http://localhost:8000/account/common/getToken",
|
||||
data={ # 正确：使用 data 参数
|
||||
"projectNo": "test_001",
|
||||
...
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Content-Type 对比
|
||||
|
||||
| 参数方式 | Content-Type | Swagger UI 显示 | requests 参数 |
|
||||
|---------|-------------|----------------|--------------|
|
||||
| JSON | `application/json` | JSON 编辑器 | `json={}` |
|
||||
| Form-Data | `application/x-www-form-urlencoded` | 表单字段 | `data={}` |
|
||||
| Multipart | `multipart/form-data` | 文件上传 | `files={}, data={}` |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 快速测试脚本
|
||||
|
||||
保存为 `test_api.py`:
|
||||
```python
|
||||
import requests
|
||||
|
||||
BASE_URL = "http://localhost:8000"
|
||||
|
||||
# 测试获取 Token
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/account/common/getToken",
|
||||
data={
|
||||
"projectNo": "test_001",
|
||||
"entityName": "测试企业",
|
||||
"userId": "902001",
|
||||
"userName": "902001",
|
||||
"appId": "remote_app",
|
||||
"appSecretCode": "test_code",
|
||||
"role": "VIEWER",
|
||||
"orgCode": "902000",
|
||||
"departmentCode": "902000"
|
||||
}
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
print("✅ 接口测试成功")
|
||||
print(response.json())
|
||||
else:
|
||||
print(f"❌ 接口测试失败: {response.status_code}")
|
||||
print(response.text)
|
||||
```
|
||||
|
||||
运行测试：
|
||||
```bash
|
||||
python test_api.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档创建日期**: 2026-03-03
|
||||
**适用版本**: v1.4.0
|
||||
Reference in New Issue
Block a user