1238 lines
39 KiB
YAML
1238 lines
39 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: 虚拟商品充值服务商系统 - 对外接口
|
||
description: |
|
||
服务商系统对外提供的接口，被邮储银行服务开放平台调用。
|
||
|
||
## 接口列表
|
||
- 服务预约接口：接收预约请求，获取券码链接
|
||
- 服务取消接口：接收取消请求，作废券码
|
||
- 订单过期积分查询接口：查询过期幸福点信息
|
||
- 服务详情查询接口：获取券码链接展示服务详情
|
||
- 对账文件查询接口：查询可用的对账文件列表
|
||
- 对账文件下载接口：根据文件ID下载对账文件
|
||
- 批量补推接口：手动批量触发服务完成通知
|
||
|
||
## 公共响应结构
|
||
所有接口统一使用以下响应结构：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "成功",
|
||
"traceId": "请求追踪ID",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
## 公共响应码
|
||
| 响应码 | 描述 |
|
||
|-------|------|
|
||
| 0 | 成功 |
|
||
| 1 | 系统异常 |
|
||
| 2 | 参数错误 |
|
||
| 3 | 签名错误 |
|
||
| 4 | 业务错误 |
|
||
|
||
## 时间格式
|
||
系统统一使用 `yyyyMMddHHmmss` 格式存储和传输时间字段。
|
||
version: 1.0.0
|
||
contact:
|
||
name: 服务商系统技术支持
|
||
|
||
servers:
|
||
- url: https://api.example.com
|
||
description: 生产环境
|
||
- url: https://api-test.example.com
|
||
description: 测试环境
|
||
|
||
tags:
|
||
- name: 服务预约
|
||
description: 服务预约相关接口
|
||
- name: 服务取消
|
||
description: 服务取消相关接口
|
||
- name: 积分查询
|
||
description: 积分查询相关接口
|
||
- name: 服务详情
|
||
description: 服务详情查询接口
|
||
- name: 对账管理
|
||
description: 对账管理相关接口
|
||
|
||
paths:
|
||
/api/v1/service/appointment:
|
||
post:
|
||
tags:
|
||
- 服务预约
|
||
summary: 服务预约接口
|
||
description: |
|
||
接收邮储银行服务开放平台的预约请求，为客户预约虚拟商品充值服务。
|
||
|
||
## 业务规则
|
||
1. 查询数据库验证服务编码(type)是否存在
|
||
2. 使用AES解密request参数，解析出type、code、mac
|
||
3. 基于权益码(code)获取分布式锁，防止重复请求
|
||
4. 对code(权益码)进行幂等验证
|
||
5. 验证权益码是否过期
|
||
6. 创建/更新订单记录
|
||
7. 请求邮储服务开放平台发起预约
|
||
8. 请求蓝色兄弟营销平台获取券码链接
|
||
operationId: serviceAppointment
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentRequest'
|
||
examples:
|
||
normal:
|
||
summary: 正常预约请求
|
||
value:
|
||
type: "310001"
|
||
request: "AES加密字符串"
|
||
channel: "12"
|
||
tranChnl: "12"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
instType: "01"
|
||
provinceInstNo: "100000"
|
||
responses:
|
||
'200':
|
||
description: 预约成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AppointmentResponse'
|
||
examples:
|
||
success:
|
||
summary: 预约成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000001"
|
||
data:
|
||
url: "https://lsb.example.com/redeem/abc123"
|
||
tranChnl: "12"
|
||
instType: "01"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
'400':
|
||
description: 参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误"
|
||
traceId: "26031314253001000002"
|
||
serviceNotFound:
|
||
summary: 服务编码不存在
|
||
value:
|
||
code: 4
|
||
msg: "暂不支持此服务"
|
||
traceId: "26031314253001000003"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "系统异常"
|
||
traceId: "26031314253001000004"
|
||
|
||
/api/v1/service/cancel:
|
||
post:
|
||
tags:
|
||
- 服务取消
|
||
summary: 服务取消接口
|
||
description: |
|
||
接收邮储银行服务开放平台的取消请求，取消已预约的服务。
|
||
|
||
## 业务规则
|
||
1. 对request进行AES解密，解析出type、code、mac
|
||
2. 基于权益码(code)获取分布式锁，防止重复请求
|
||
3. 检查订单状态必须是已预约状态才能取消
|
||
4. 调用邮储预约服务状态查询接口查询状态
|
||
5. 调用蓝色兄弟作废接口发起作废
|
||
6. 调用邮储接口发起预约取消
|
||
7. 订单状态更新为"已取消"(400)
|
||
operationId: serviceCancel
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CancelRequest'
|
||
examples:
|
||
normal:
|
||
summary: 正常取消请求
|
||
value:
|
||
type: "310001"
|
||
request: "AES加密字符串"
|
||
channel: "12"
|
||
tranChnl: "12"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
instType: "01"
|
||
provinceInstNo: "100000"
|
||
responses:
|
||
'200':
|
||
description: 取消成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CancelResponse'
|
||
examples:
|
||
success:
|
||
summary: 取消成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000005"
|
||
data:
|
||
tranChnl: "12"
|
||
instType: "01"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
'400':
|
||
description: 参数错误或业务错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误"
|
||
traceId: "26031314253001000006"
|
||
serviceNotFound:
|
||
summary: 服务编码不存在
|
||
value:
|
||
code: 4
|
||
msg: "暂不支持此服务"
|
||
traceId: "26031314253001000007"
|
||
serviceExpired:
|
||
summary: 服务已过期
|
||
value:
|
||
code: 4
|
||
msg: "服务已过期"
|
||
traceId: "26031314253001000008"
|
||
serviceCompleted:
|
||
summary: 服务已生效无法取消
|
||
value:
|
||
code: 4
|
||
msg: "服务已生效无法取消"
|
||
traceId: "26031314253001000009"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "系统异常"
|
||
traceId: "26031314253001000010"
|
||
|
||
/api/v1/order/expired-points:
|
||
post:
|
||
tags:
|
||
- 积分查询
|
||
summary: 订单过期积分查询接口
|
||
description: |
|
||
查询订单退还时已过期的幸福点信息，用于取消前提醒客户。
|
||
|
||
## 业务规则
|
||
1. 验证服务编码(type)，查询数据库获取AES解密密钥
|
||
2. 服务编码不存在返回"暂不支持此服务"
|
||
3. 解密request参数获取服务编码、权益码、客户ID
|
||
4. 调用邮储「高端客户权益订单退还时已过期积分查询」接口
|
||
5. 返回邮储接口查询结果
|
||
operationId: queryExpiredPoints
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpiredPointsRequest'
|
||
examples:
|
||
normal:
|
||
summary: 正常查询请求
|
||
value:
|
||
type: "310001"
|
||
request: "AES加密字符串"
|
||
channel: "12"
|
||
tranChnl: "12"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
instType: "01"
|
||
provinceInstNo: "100000"
|
||
responses:
|
||
'200':
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpiredPointsResponse'
|
||
examples:
|
||
success:
|
||
summary: 查询成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000011"
|
||
data:
|
||
tranIntglNum: 1000
|
||
ovdueIntglNum: 200
|
||
noticeMsg: "您有200幸福点已过期，取消后将无法退回"
|
||
'400':
|
||
description: 参数错误或业务错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误"
|
||
traceId: "26031314253001000012"
|
||
serviceNotFound:
|
||
summary: 服务编码不存在
|
||
value:
|
||
code: 4
|
||
msg: "暂不支持此服务"
|
||
traceId: "26031314253001000013"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "查询失败，请重试"
|
||
traceId: "26031314253001000014"
|
||
|
||
/api/v1/service/detail:
|
||
post:
|
||
tags:
|
||
- 服务详情
|
||
summary: 服务详情查询接口
|
||
description: |
|
||
提供给邮储银行跳转服务详情页面，根据参数获取上游券码链接展示服务详情。
|
||
|
||
## 业务规则
|
||
1. 验证服务编码(type)，查询数据库获取AES解密密钥
|
||
2. 服务编码不存在返回"暂不支持此服务"
|
||
3. 解密request参数获取服务编码、权益码、客户ID
|
||
4. 根据权益码查询订单获取券码链接
|
||
5. 返回券码链接用于页面展示
|
||
operationId: queryServiceDetail
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ServiceDetailRequest'
|
||
examples:
|
||
normal:
|
||
summary: 正常查询请求
|
||
value:
|
||
type: "310001"
|
||
request: "AES加密字符串"
|
||
channel: "12"
|
||
tranChnl: "12"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
instType: "01"
|
||
provinceInstNo: "100000"
|
||
responses:
|
||
'200':
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ServiceDetailResponse'
|
||
examples:
|
||
success:
|
||
summary: 查询成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000015"
|
||
data:
|
||
url: "https://lsb.example.com/redeem/abc123"
|
||
backUrl: "https://mobile.psbc.com/back"
|
||
'400':
|
||
description: 参数错误或业务错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误"
|
||
traceId: "26031314253001000016"
|
||
serviceNotFound:
|
||
summary: 服务编码不存在
|
||
value:
|
||
code: 4
|
||
msg: "暂不支持此服务"
|
||
traceId: "26031314253001000017"
|
||
orderNotFound:
|
||
summary: 订单不存在
|
||
value:
|
||
code: 1
|
||
msg: "订单不存在"
|
||
traceId: "26031314253001000018"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "系统异常"
|
||
traceId: "26031314253001000019"
|
||
|
||
/api/v1/reconciliation/files:
|
||
post:
|
||
tags:
|
||
- 对账管理
|
||
summary: 对账文件查询接口
|
||
description: |
|
||
查询可用的对账文件列表，用于管理员或运营人员获取本地处理后的对账文件信息。
|
||
|
||
## 业务规则
|
||
1. 每月3号生成上月服务状态为「服务已完成(300)」的权益订单对账文件
|
||
2. 对账月份规则：服务完成时间所在月份为对账月份
|
||
3. 对账文件名称格式：RIGHTS_SERVICE_CHK_{providerCode}
|
||
4. 返回文件ID、文件名称等信息
|
||
operationId: queryReconciliationFiles
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ReconciliationFilesRequest'
|
||
examples:
|
||
normal:
|
||
summary: 正常查询请求
|
||
value:
|
||
accountingDate: "20251201"
|
||
fileIntfcName: "RIGHTS_SERVICE_CHK_A101"
|
||
responses:
|
||
'200':
|
||
description: 查询成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ReconciliationFilesResponse'
|
||
examples:
|
||
success:
|
||
summary: 查询成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000020"
|
||
data:
|
||
fileList:
|
||
- fileId: "FILE202512A101001"
|
||
fileName: "RIGHTS_SERVICE_CHK_A101_202512.csv"
|
||
fileSize: 12560
|
||
createTime: "20260103100000"
|
||
emptyResult:
|
||
summary: 无对账数据
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000021"
|
||
data:
|
||
fileList: []
|
||
'400':
|
||
description: 参数错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误"
|
||
traceId: "26031314253001000022"
|
||
monthExceed:
|
||
summary: 对账月份超过当前月
|
||
value:
|
||
code: 4
|
||
msg: "对账月份不能超过上月"
|
||
traceId: "26031314253001000023"
|
||
fileIntfcNameNotFound:
|
||
summary: 文件接口名不存在
|
||
value:
|
||
code: 4
|
||
msg: "文件接口名不存在"
|
||
traceId: "26031314253001000024"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "系统异常"
|
||
traceId: "26031314253001000024"
|
||
|
||
/api/v1/reconciliation/download:
|
||
post:
|
||
tags:
|
||
- 对账管理
|
||
summary: 对账文件下载接口
|
||
description: |
|
||
根据文件ID和文件接口名下载对账文件，用于管理员或运营人员获取具体的对账文件内容。
|
||
|
||
## 业务规则
|
||
1. 根据文件ID和文件接口名查询对账文件
|
||
2. 验证下载密码，密码错误拒绝下载
|
||
3. 文件格式为CSV，编码UTF-8-BOM（兼容Excel中文显示）
|
||
4. 直接返回文件流
|
||
|
||
## 对账文件内容字段
|
||
| 序号 | 字段名 | 说明 |
|
||
|-----|-------|------|
|
||
| 1 | 统计月份 | YYYYMM |
|
||
| 2 | 一分机构序号 | province_inst_no |
|
||
| 3 | 一分机构名称 | 根据机构号映射 |
|
||
| 4 | 网点机构属性 | 01-自营，02-代理 |
|
||
| 5 | 积分客户服务编码 | type字段 |
|
||
| 6 | 服务内容 | 服务名称 |
|
||
| 7 | 预约时间 | yyyyMMddHHmmss |
|
||
| 8 | 实际完成时间 | yyyyMMddHHmmss |
|
||
| 9 | 权益兑换码 | code字段 |
|
||
| 10 | 订单号 | order_no |
|
||
| 11 | 券码状态 | 1-正常，2-已核销，3-已作废，4-已过期 |
|
||
operationId: downloadReconciliationFile
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ReconciliationDownloadRequest'
|
||
examples:
|
||
normal:
|
||
summary: 正常下载请求
|
||
value:
|
||
fileId: "FILE202512A101001"
|
||
fileIntfcName: "RIGHTS_SERVICE_CHK_A101"
|
||
password: "your_password"
|
||
responses:
|
||
'200':
|
||
description: 下载成功
|
||
content:
|
||
text/csv:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
headers:
|
||
Content-Disposition:
|
||
description: 文件名
|
||
schema:
|
||
type: string
|
||
example: 'attachment; filename="RIGHTS_SERVICE_CHK_A101_202512.csv"'
|
||
'400':
|
||
description: 参数错误或文件不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误"
|
||
traceId: "26031314253001000025"
|
||
passwordError:
|
||
summary: 密码错误
|
||
value:
|
||
code: 3
|
||
msg: "密码错误"
|
||
traceId: "26031314253001000028"
|
||
fileNotFound:
|
||
summary: 文件不存在
|
||
value:
|
||
code: 4
|
||
msg: "文件不存在"
|
||
traceId: "26031314253001000026"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "系统异常"
|
||
traceId: "26031314253001000027"
|
||
|
||
/api/v1/reconciliation/batch-repush:
|
||
post:
|
||
tags:
|
||
- 对账管理
|
||
summary: 批量补推接口
|
||
description: |
|
||
手动批量触发服务完成通知，用于处理蓝色兄弟已核销但邮储银行未收到服务完成通知的订单。
|
||
|
||
## 业务规则
|
||
1. 查询本地订单状态为「服务已预约(200)」且券码状态为「已核销(2)」的订单
|
||
2. 批量创建服务完成通知任务(task_type=1)
|
||
3. 支持按时间范围、权益码列表筛选（二选一）
|
||
4. 单次补推数量限制：最多100笔
|
||
5. 幂等处理：已存在相同类型的待处理任务时跳过
|
||
6. 支持试运行模式(dryRun)，只查询不创建任务
|
||
operationId: batchRepush
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BatchRepushRequest'
|
||
examples:
|
||
byCodes:
|
||
summary: 按权益码列表补推
|
||
value:
|
||
codes:
|
||
- "16800G-VN4724-NX874-30VHR"
|
||
- "16800G-VN4724-NX874-30VHS"
|
||
dryRun: false
|
||
byTimeRange:
|
||
summary: 按时间范围补推
|
||
value:
|
||
startTime: "20251201000000"
|
||
endTime: "20251231235959"
|
||
dryRun: false
|
||
dryRunMode:
|
||
summary: 试运行模式
|
||
value:
|
||
startTime: "20251201000000"
|
||
endTime: "20251231235959"
|
||
dryRun: true
|
||
responses:
|
||
'200':
|
||
description: 补推成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BatchRepushResponse'
|
||
examples:
|
||
success:
|
||
summary: 补推成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000024"
|
||
data:
|
||
totalCount: 3
|
||
createdCount: 2
|
||
skippedCount: 1
|
||
dryRunSuccess:
|
||
summary: 试运行成功
|
||
value:
|
||
code: 0
|
||
msg: "成功"
|
||
traceId: "26031314253001000025"
|
||
data:
|
||
totalCount: 3
|
||
createdCount: 0
|
||
skippedCount: 0
|
||
orders:
|
||
- orderNo: "26031314253001000001"
|
||
code: "16800G-VN4724-NX874-30VHR"
|
||
status: 200
|
||
keyStatus: 2
|
||
keyUsageTime: "20251215143000"
|
||
hasTask: false
|
||
- orderNo: "26031314253001000002"
|
||
code: "16800G-VN4724-NX874-30VHS"
|
||
status: 200
|
||
keyStatus: 2
|
||
keyUsageTime: "20251216101530"
|
||
hasTask: true
|
||
'400':
|
||
description: 参数错误或业务错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
paramError:
|
||
summary: 参数错误
|
||
value:
|
||
code: 2
|
||
msg: "参数错误：权益码列表和时间范围必须二选一"
|
||
traceId: "26031314253001000026"
|
||
exceedLimit:
|
||
summary: 超过数量限制
|
||
value:
|
||
code: 2
|
||
msg: "单次补推数量不能超过100笔"
|
||
traceId: "26031314253001000027"
|
||
tooManyOrders:
|
||
summary: 符合条件订单超过限制
|
||
value:
|
||
code: 4
|
||
msg: "符合条件的订单超过100笔，请缩小时间范围或使用权益码列表"
|
||
traceId: "26031314253001000028"
|
||
'500':
|
||
description: 系统异常
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
examples:
|
||
systemError:
|
||
summary: 系统异常
|
||
value:
|
||
code: 1
|
||
msg: "系统异常"
|
||
traceId: "26031314253001000029"
|
||
|
||
components:
|
||
schemas:
|
||
# ============ 请求参数 ============
|
||
BaseRequest:
|
||
type: object
|
||
required:
|
||
- type
|
||
- request
|
||
- channel
|
||
- tranChnl
|
||
- instType
|
||
- provinceInstNo
|
||
properties:
|
||
type:
|
||
type: string
|
||
description: 服务编码，用于查询数据库获取AES解密密钥
|
||
example: "310001"
|
||
maxLength: 6
|
||
request:
|
||
type: string
|
||
description: |
|
||
AES加密字符串
|
||
解密后格式：type=服务编码&code=权益码&mac=加密后的客户id
|
||
加密算法：AES/CBC/PKCS5Padding
|
||
Key长度：16位
|
||
IV长度：16位
|
||
编码方式：Base64
|
||
example: "U2FsdGVkX1+abc123..."
|
||
channel:
|
||
type: string
|
||
description: 渠道标识
|
||
enum:
|
||
- "12"
|
||
- "17"
|
||
- "41"
|
||
x-enum-descriptions:
|
||
- 手机银行
|
||
- 电话银行
|
||
- CRM零售
|
||
example: "12"
|
||
maxLength: 4
|
||
tranChnl:
|
||
type: string
|
||
description: 渠道标识
|
||
enum:
|
||
- "12"
|
||
- "17"
|
||
- "41"
|
||
x-enum-descriptions:
|
||
- 手机银行
|
||
- 电话银行
|
||
- CRM零售
|
||
example: "12"
|
||
maxLength: 4
|
||
backUrl:
|
||
type: string
|
||
description: 返回手机银行的地址，可为空
|
||
example: "https://mobile.psbc.com/back"
|
||
maxLength: 256
|
||
instType:
|
||
type: string
|
||
description: 客户自营代理属性
|
||
enum:
|
||
- "01"
|
||
- "02"
|
||
x-enum-descriptions:
|
||
- 自营
|
||
- 代理
|
||
example: "01"
|
||
maxLength: 2
|
||
provinceInstNo:
|
||
type: string
|
||
description: 客户归属一分机构号
|
||
example: "100000"
|
||
maxLength: 20
|
||
|
||
AppointmentRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseRequest'
|
||
description: 服务预约请求参数
|
||
|
||
CancelRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseRequest'
|
||
description: 服务取消请求参数
|
||
|
||
ExpiredPointsRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseRequest'
|
||
description: 订单过期积分查询请求参数
|
||
|
||
ServiceDetailRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseRequest'
|
||
description: 服务详情查询请求参数
|
||
|
||
BatchRepushRequest:
|
||
type: object
|
||
description: |
|
||
批量补推请求参数
|
||
注意：codes 和 startTime/endTime 必须二选一
|
||
properties:
|
||
codes:
|
||
type: array
|
||
description: 权益码列表，最多100个，与时间范围二选一
|
||
items:
|
||
type: string
|
||
maxItems: 100
|
||
example:
|
||
- "16800G-VN4724-NX874-30VHR"
|
||
- "16800G-VN4724-NX874-30VHS"
|
||
startTime:
|
||
type: string
|
||
description: 开始时间，格式：yyyyMMddHHmmss，与codes二选一
|
||
pattern: '^\d{14}$'
|
||
example: "20251201000000"
|
||
endTime:
|
||
type: string
|
||
description: 结束时间，格式：yyyyMMddHHmmss，与codes二选一
|
||
pattern: '^\d{14}$'
|
||
example: "20251231235959"
|
||
dryRun:
|
||
type: boolean
|
||
description: 是否试运行，默认false。true时只返回待补推订单列表，不实际创建任务
|
||
default: false
|
||
example: false
|
||
|
||
ReconciliationFilesRequest:
|
||
type: object
|
||
description: 对账文件查询请求参数
|
||
required:
|
||
- accountingDate
|
||
- fileIntfcName
|
||
properties:
|
||
accountingDate:
|
||
type: string
|
||
description: 会计日期，格式：YYYYMMDD
|
||
pattern: '^\d{8}$'
|
||
maxLength: 8
|
||
example: "20251201"
|
||
fileIntfcName:
|
||
type: string
|
||
description: 文件接口名，固定值，如：RIGHTS_SERVICE_CHK_A101
|
||
maxLength: 64
|
||
example: "RIGHTS_SERVICE_CHK_A101"
|
||
|
||
ReconciliationDownloadRequest:
|
||
type: object
|
||
description: 对账文件下载请求参数
|
||
required:
|
||
- fileId
|
||
- fileIntfcName
|
||
- password
|
||
properties:
|
||
fileId:
|
||
type: string
|
||
description: 文件唯一标识，从查询接口获取
|
||
maxLength: 32
|
||
example: "FILE202512A101001"
|
||
fileIntfcName:
|
||
type: string
|
||
description: 文件接口名，固定值，如：RIGHTS_SERVICE_CHK_A101
|
||
maxLength: 64
|
||
example: "RIGHTS_SERVICE_CHK_A101"
|
||
password:
|
||
type: string
|
||
description: 下载密码，用于验证下载权限
|
||
maxLength: 32
|
||
example: "your_password"
|
||
|
||
# ============ 响应参数 ============
|
||
BaseResponse:
|
||
type: object
|
||
required:
|
||
- code
|
||
- msg
|
||
- traceId
|
||
properties:
|
||
code:
|
||
type: integer
|
||
description: |
|
||
公共响应码
|
||
- 0: 成功
|
||
- 1: 系统异常
|
||
- 2: 参数错误
|
||
- 3: 签名错误
|
||
- 4: 业务错误
|
||
enum:
|
||
- 0
|
||
- 1
|
||
- 2
|
||
- 3
|
||
- 4
|
||
example: 0
|
||
msg:
|
||
type: string
|
||
description: 响应描述信息，当code!=0时为错误信息
|
||
example: "成功"
|
||
traceId:
|
||
type: string
|
||
description: 请求追踪ID，用于问题排查。使用雪花算法或UUID确保全局唯一
|
||
example: "26031314253001000001"
|
||
maxLength: 32
|
||
|
||
AppointmentResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: 业务数据
|
||
required:
|
||
- url
|
||
- tranChnl
|
||
- instType
|
||
properties:
|
||
url:
|
||
type: string
|
||
description: 蓝色兄弟营销平台的兑换地址
|
||
example: "https://lsb.example.com/redeem/abc123"
|
||
maxLength: 125
|
||
tranChnl:
|
||
type: string
|
||
description: 渠道标识
|
||
example: "12"
|
||
maxLength: 4
|
||
instType:
|
||
type: string
|
||
description: 客户自营代理属性
|
||
example: "01"
|
||
maxLength: 2
|
||
backUrl:
|
||
type: string
|
||
description: 返回手机银行的地址
|
||
example: "https://mobile.psbc.com/back"
|
||
maxLength: 256
|
||
|
||
CancelResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: 业务数据
|
||
required:
|
||
- tranChnl
|
||
- instType
|
||
properties:
|
||
tranChnl:
|
||
type: string
|
||
description: 渠道标识
|
||
example: "12"
|
||
maxLength: 4
|
||
instType:
|
||
type: string
|
||
description: 客户自营代理属性
|
||
example: "01"
|
||
maxLength: 2
|
||
backUrl:
|
||
type: string
|
||
description: 返回手机银行的地址
|
||
example: "https://mobile.psbc.com/back"
|
||
maxLength: 256
|
||
|
||
ExpiredPointsResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: 业务数据
|
||
properties:
|
||
tranIntglNum:
|
||
type: integer
|
||
description: 交易总幸福点
|
||
example: 1000
|
||
ovdueIntglNum:
|
||
type: integer
|
||
description: 已过期的幸福点
|
||
example: 200
|
||
noticeMsg:
|
||
type: string
|
||
description: 提醒信息文本
|
||
example: "您有200幸福点已过期，取消后将无法退回"
|
||
|
||
ServiceDetailResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: 业务数据
|
||
required:
|
||
- url
|
||
- backUrl
|
||
properties:
|
||
url:
|
||
type: string
|
||
description: 券码链接，用于展示服务详情
|
||
example: "https://lsb.example.com/redeem/abc123"
|
||
maxLength: 125
|
||
backUrl:
|
||
type: string
|
||
description: 返回手机银行的地址
|
||
example: "https://mobile.psbc.com/back"
|
||
maxLength: 256
|
||
|
||
ErrorResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
description: 错误响应
|
||
|
||
ReconciliationFilesResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: 业务数据
|
||
required:
|
||
- fileList
|
||
properties:
|
||
fileList:
|
||
type: array
|
||
description: 对账文件列表
|
||
items:
|
||
$ref: '#/components/schemas/ReconciliationFileItem'
|
||
|
||
ReconciliationFileItem:
|
||
type: object
|
||
description: 对账文件信息
|
||
required:
|
||
- fileId
|
||
- fileName
|
||
- fileSize
|
||
- createTime
|
||
properties:
|
||
fileId:
|
||
type: string
|
||
description: 文件唯一标识，用于下载接口
|
||
example: "FILE202512A101001"
|
||
maxLength: 32
|
||
fileName:
|
||
type: string
|
||
description: 文件名称
|
||
example: "RIGHTS_SERVICE_CHK_A101_202512.csv"
|
||
maxLength: 64
|
||
fileSize:
|
||
type: integer
|
||
format: int64
|
||
description: 文件大小（字节）
|
||
example: 12560
|
||
createTime:
|
||
type: string
|
||
description: 文件创建时间 yyyyMMddHHmmss
|
||
example: "20260103100000"
|
||
|
||
BatchRepushResponse:
|
||
allOf:
|
||
- $ref: '#/components/schemas/BaseResponse'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: 业务数据
|
||
required:
|
||
- totalCount
|
||
- createdCount
|
||
- skippedCount
|
||
properties:
|
||
totalCount:
|
||
type: integer
|
||
description: 符合条件的订单总数
|
||
example: 3
|
||
createdCount:
|
||
type: integer
|
||
description: 新创建的任务数（dryRun=true时为0）
|
||
example: 2
|
||
skippedCount:
|
||
type: integer
|
||
description: 跳过的订单数（已有待处理任务）
|
||
example: 1
|
||
orders:
|
||
type: array
|
||
description: 订单列表（dryRun=true时返回）
|
||
items:
|
||
$ref: '#/components/schemas/RepushOrderItem'
|
||
|
||
RepushOrderItem:
|
||
type: object
|
||
description: 补推订单信息
|
||
required:
|
||
- orderNo
|
||
- code
|
||
- status
|
||
- keyStatus
|
||
- hasTask
|
||
properties:
|
||
orderNo:
|
||
type: string
|
||
description: 订单号
|
||
example: "26031314253001000001"
|
||
maxLength: 32
|
||
code:
|
||
type: string
|
||
description: 权益码
|
||
example: "16800G-VN4724-NX874-30VHR"
|
||
maxLength: 32
|
||
status:
|
||
type: integer
|
||
description: |
|
||
订单状态
|
||
- 100: 服务未预约
|
||
- 200: 服务已预约
|
||
- 300: 服务已完成
|
||
- 400: 服务已取消
|
||
- 500: 服务已过期
|
||
example: 200
|
||
keyStatus:
|
||
type: integer
|
||
description: |
|
||
券码状态
|
||
- 0: 待生成
|
||
- 1: 正常
|
||
- 2: 已核销
|
||
- 3: 已作废
|
||
- 4: 已过期
|
||
example: 2
|
||
keyUsageTime:
|
||
type: string
|
||
description: 核销时间，格式：yyyyMMddHHmmss
|
||
example: "20251215143000"
|
||
hasTask:
|
||
type: boolean
|
||
description: 是否已有待处理任务
|
||
example: false
|
||
|
||
# ============ 枚举定义 ============
|
||
Channel:
|
||
type: string
|
||
description: 渠道标识
|
||
enum:
|
||
- "12"
|
||
- "17"
|
||
- "41"
|
||
x-enum-descriptions:
|
||
- 手机银行
|
||
- 电话银行
|
||
- CRM零售
|
||
|
||
InstType:
|
||
type: string
|
||
description: 客户自营代理属性
|
||
enum:
|
||
- "01"
|
||
- "02"
|
||
x-enum-descriptions:
|
||
- 自营
|
||
- 代理
|
||
|
||
ResponseCode:
|
||
type: integer
|
||
description: 公共响应码
|
||
enum:
|
||
- 0
|
||
- 1
|
||
- 2
|
||
- 3
|
||
- 4
|
||
x-enum-descriptions:
|
||
- 成功
|
||
- 系统异常
|
||
- 参数错误
|
||
- 签名错误
|
||
- 业务错误
|
||
|
||
OrderStatus:
|
||
type: integer
|
||
description: 订单状态
|
||
enum:
|
||
- 100
|
||
- 200
|
||
- 300
|
||
- 400
|
||
- 500
|
||
x-enum-descriptions:
|
||
- 服务未预约
|
||
- 服务已预约
|
||
- 服务已完成
|
||
- 服务已取消
|
||
- 服务已过期
|
||
|
||
KeyCodeStatus:
|
||
type: integer
|
||
description: 券码状态
|
||
enum:
|
||
- 0
|
||
- 1
|
||
- 2
|
||
- 3
|
||
- 4
|
||
x-enum-descriptions:
|
||
- 待生成
|
||
- 正常
|
||
- 已核销
|
||
- 已作废
|
||
- 已过期
|