257 lines
10 KiB
YAML
257 lines
10 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 客户资金账户、授信与充值 API
|
|
version: 1.2.0
|
|
description: |
|
|
CNY 资金账户支持静态收款码、付款截图申请、平台审核、手工充扣、限时授信及业务冻结/结算/释放。
|
|
授信到期日当天仍有效，次日不再计入可用余额。消费直接扣减实际余额并允许形成负数；实际余额为负时禁止提交新订单。
|
|
充值直接增加实际余额。新账户授信额度由
|
|
`baiyue.finance.wallet.default-credit-limit` 初始化，默认 `0.00`，平台可按客户调整。
|
|
paths:
|
|
/api/client/finance/v1/account:
|
|
get:
|
|
summary: 查询当前客户资金账户
|
|
responses:
|
|
'200':
|
|
description: 成功
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/WalletAccountEnvelope' }
|
|
/api/client/finance/v1/account/ledger:
|
|
get:
|
|
summary: 查询当前客户账户流水
|
|
parameters:
|
|
- { name: page, in: query, schema: { type: integer, default: 1 } }
|
|
- { name: size, in: query, schema: { type: integer, default: 20 } }
|
|
responses:
|
|
'200': { description: 成功 }
|
|
/api/client/finance/v1/recharge-channel:
|
|
get:
|
|
summary: 查询平台统一静态收款码配置
|
|
responses:
|
|
'200': { description: 成功 }
|
|
/api/client/finance/v1/recharge-requests:
|
|
get:
|
|
summary: 查询当前客户充值申请，待审核优先
|
|
responses:
|
|
'200': { description: 成功 }
|
|
post:
|
|
summary: 上传付款截图并提交充值申请
|
|
parameters:
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required: [amount, file]
|
|
properties:
|
|
amount: { type: number, format: decimal, minimum: 0.01 }
|
|
file: { type: string, format: binary, description: JPG 或 PNG }
|
|
responses:
|
|
'200': { description: 提交成功 }
|
|
/api/client/finance/v1/recharge-requests/{requestId}/voucher:
|
|
get:
|
|
summary: 预览当前客户充值凭证
|
|
parameters:
|
|
- $ref: '#/components/parameters/RequestId'
|
|
responses:
|
|
'200': { description: 图片内容 }
|
|
/api/platform/finance/v1/accounts/{customerId}/recharge-requests:
|
|
get:
|
|
summary: 查询客户充值申请，待审核优先
|
|
parameters:
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
responses:
|
|
'200': { description: 成功 }
|
|
/api/platform/finance/v1/recharge-requests/{requestId}/review:
|
|
post:
|
|
summary: 审核或驳回充值申请
|
|
parameters:
|
|
- $ref: '#/components/parameters/RequestId'
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/RechargeReviewRequest' }
|
|
responses:
|
|
'200': { description: 成功 }
|
|
/api/platform/finance/v1/recharge-requests/{requestId}/voucher:
|
|
get:
|
|
summary: 平台预览充值凭证
|
|
parameters:
|
|
- $ref: '#/components/parameters/RequestId'
|
|
responses:
|
|
'200': { description: 图片内容 }
|
|
/api/platform/finance/v1/accounts/{customerId}/adjustments:
|
|
post:
|
|
summary: 平台手工充值或扣款
|
|
parameters:
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/AccountAdjustmentRequest' }
|
|
responses:
|
|
'200': { description: 成功 }
|
|
/api/platform/finance/v1/accounts/{customerId}/credit-limit:
|
|
put:
|
|
summary: 设置客户授信额度
|
|
parameters:
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/CreditLimitRequest' }
|
|
responses:
|
|
'200': { description: 成功并生成授信调整流水 }
|
|
/internal/finance/v1/wallet/accounts/{customerId}:
|
|
get:
|
|
summary: 业务模块查询客户资金账户
|
|
parameters:
|
|
- $ref: '#/components/parameters/InternalServiceToken'
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
responses:
|
|
'200': { description: 成功 }
|
|
/internal/finance/v1/wallet/accounts/{customerId}/holds:
|
|
post:
|
|
summary: 按业务单冻结资金，先冻结实际资金再冻结授信
|
|
parameters:
|
|
- $ref: '#/components/parameters/InternalServiceToken'
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/WalletFreezeRequest' }
|
|
responses:
|
|
'200': { description: 成功；同一客户、业务类型和业务单号只允许一条冻结记录 }
|
|
/internal/finance/v1/wallet/accounts/{customerId}/holds/{businessType}/{businessNo}/settle:
|
|
post:
|
|
summary: 结算已冻结资金
|
|
parameters:
|
|
- $ref: '#/components/parameters/InternalServiceToken'
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
- $ref: '#/components/parameters/BusinessType'
|
|
- $ref: '#/components/parameters/BusinessNo'
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/WalletHoldActionRequest' }
|
|
responses:
|
|
'200': { description: 成功；实际冻结转为实际扣减，授信冻结转为已用授信 }
|
|
/internal/finance/v1/wallet/accounts/{customerId}/holds/{businessType}/{businessNo}/release:
|
|
post:
|
|
summary: 释放已冻结资金
|
|
parameters:
|
|
- $ref: '#/components/parameters/InternalServiceToken'
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
- $ref: '#/components/parameters/CustomerId'
|
|
- $ref: '#/components/parameters/BusinessType'
|
|
- $ref: '#/components/parameters/BusinessNo'
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema: { $ref: '#/components/schemas/WalletHoldActionRequest' }
|
|
responses:
|
|
'200': { description: 成功；实际资金和授信恢复为可用 }
|
|
components:
|
|
parameters:
|
|
IdempotencyKey:
|
|
name: Idempotency-Key
|
|
in: header
|
|
required: true
|
|
schema: { type: string, maxLength: 128 }
|
|
InternalServiceToken:
|
|
name: X-Internal-Service-Token
|
|
in: header
|
|
required: true
|
|
schema: { type: string, writeOnly: true }
|
|
CustomerId:
|
|
name: customerId
|
|
in: path
|
|
required: true
|
|
schema: { type: string, pattern: '^[1-9][0-9]*$' }
|
|
RequestId:
|
|
name: requestId
|
|
in: path
|
|
required: true
|
|
schema: { type: string, pattern: '^[1-9][0-9]*$' }
|
|
BusinessType:
|
|
name: businessType
|
|
in: path
|
|
required: true
|
|
schema: { type: string, pattern: '^[A-Z][A-Z0-9_]{1,31}$' }
|
|
BusinessNo:
|
|
name: businessNo
|
|
in: path
|
|
required: true
|
|
schema: { type: string, minLength: 1, maxLength: 128 }
|
|
schemas:
|
|
WalletAccountEnvelope:
|
|
type: object
|
|
properties:
|
|
data: { $ref: '#/components/schemas/WalletAccount' }
|
|
WalletAccount:
|
|
type: object
|
|
required: [currencyCode, actualBalance, frozenBalance, availableBalance, creditLimit, creditUsed, creditFrozen, availableCredit, creditActive, version]
|
|
properties:
|
|
currencyCode: { type: string, enum: [CNY] }
|
|
actualBalance: { type: number, format: decimal, description: 实际余额；授信到期后已用额度并入此余额，可为负数 }
|
|
frozenBalance: { type: number, format: decimal, minimum: 0, description: 实际资金冻结与授信冻结合计 }
|
|
availableBalance: { type: number, format: decimal, description: 当前可用余额，可在授信失效后为负数 }
|
|
creditLimit: { type: number, format: decimal, minimum: 0 }
|
|
creditUsed: { type: number, format: decimal, minimum: 0 }
|
|
creditFrozen: { type: number, format: decimal, minimum: 0 }
|
|
availableCredit: { type: number, format: decimal, minimum: 0 }
|
|
creditExpiresOn: { type: string, format: date, nullable: true, description: 授信到期日，当天仍有效 }
|
|
creditActive: { type: boolean, description: 授信当前是否有效 }
|
|
version: { type: integer, minimum: 0 }
|
|
updatedAt: { type: string, format: date-time, nullable: true }
|
|
RechargeReviewRequest:
|
|
type: object
|
|
required: [decision, expectedVersion]
|
|
properties:
|
|
decision: { type: string, enum: [APPROVE, REJECT] }
|
|
remark: { type: string, maxLength: 500, description: 驳回时必填 }
|
|
expectedVersion: { type: integer, minimum: 0 }
|
|
AccountAdjustmentRequest:
|
|
type: object
|
|
required: [type, amount, occurredDate, remark, expectedAccountVersion]
|
|
properties:
|
|
type: { type: string, enum: [RECHARGE, DEDUCTION] }
|
|
amount: { type: number, format: decimal, minimum: 0.01 }
|
|
occurredDate: { type: string, format: date }
|
|
paymentMethod: { type: string, maxLength: 32 }
|
|
referenceNo: { type: string, maxLength: 128 }
|
|
remark: { type: string, maxLength: 500 }
|
|
expectedAccountVersion: { type: integer, minimum: 0 }
|
|
CreditLimitRequest:
|
|
type: object
|
|
required: [creditLimit, creditExpiresOn, expectedAccountVersion]
|
|
properties:
|
|
creditLimit: { type: number, format: decimal, minimum: 0 }
|
|
creditExpiresOn: { type: string, format: date, description: 必须晚于服务端当前日期，不限制最远日期 }
|
|
remark: { type: string, maxLength: 500 }
|
|
expectedAccountVersion: { type: integer, minimum: 0 }
|
|
WalletFreezeRequest:
|
|
type: object
|
|
required: [amount, businessType, businessNo]
|
|
properties:
|
|
amount: { type: number, format: decimal, minimum: 0.01 }
|
|
businessType: { type: string, minLength: 1, maxLength: 64 }
|
|
businessNo: { type: string, minLength: 1, maxLength: 128 }
|
|
remark: { type: string, maxLength: 500 }
|
|
WalletHoldActionRequest:
|
|
type: object
|
|
properties:
|
|
remark: { type: string, maxLength: 500 }
|