62 lines
3.2 KiB
YAML
62 lines
3.2 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 平台资金账户关联退款
|
|
version: 1.0.0
|
|
description: 原消费保持不可变；退款记录关联原消费流水号，累计退款不得超过原消费金额，包含业务退款事件已退金额。
|
|
paths:
|
|
/api/platform/finance/v1/accounts/{customerId}/ledger/{ledgerId}/refunds:
|
|
post:
|
|
operationId: refundWalletConsumption
|
|
summary: 原消费关联退款
|
|
description: 仅平台 tenantId=0 且具有 platform:finance:customer-account:adjust 权限可操作。账户行锁串行校验累计可退金额，无需前端提交账户版本。优先归还已用授信，再增加实际余额。相同键同请求返回原流水；相同键不同原消费或金额失败。非成功消费、跨客户原流水、超额退款均拒绝。
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- {name: customerId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
|
- {name: ledgerId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
|
- {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [amount, reason]
|
|
properties:
|
|
amount: {type: number, minimum: 0.01, maximum: 999999999999.99, multipleOf: 0.01}
|
|
reason: {type: string, minLength: 1, maxLength: 500, description: 必填退款原因，不得仅空白}
|
|
responses:
|
|
'200':
|
|
description: 统一响应 code=200 成功；业务失败使用 FIN-REQ-400、FIN-WALLET-404、FIN-IDEMPOTENCY-CONFLICT 或 FIN-WALLET-REFUND-EXCEEDED 等业务码。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code: {type: string}
|
|
data:
|
|
$ref: '#/components/schemas/RefundLedgerEntry'
|
|
'403': {description: 非平台主体或缺少调账权限}
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
|
|
schemas:
|
|
RefundLedgerEntry:
|
|
type: object
|
|
description: 完整返回 FinanceWalletDtos.WalletLedgerEntry，资金余额字段沿用账户流水协议。
|
|
properties:
|
|
ledgerId: {type: string}
|
|
businessNo: {type: string, description: 新退款流水正式 AC 单号}
|
|
changeType: {type: string, enum: [REFUND]}
|
|
amount: {type: number, description: 实际退款正金额}
|
|
sourceType: {type: string, enum: [BUSINESS_REFUND]}
|
|
sourceNo: {type: string, description: 客户及幂等键派生的稳定技术退款引用}
|
|
referenceNo: {type: string, description: 原消费流水 businessNo，用于关联及累计可退校验}
|
|
operatorName: {type: string, nullable: true}
|
|
remark: {type: string, description: 退款原因}
|
|
actualBalanceAfter: {type: number}
|
|
frozenBalanceAfter: {type: number}
|
|
availableBalanceAfter: {type: number}
|
|
creditUsedAfter: {type: number}
|
|
availableCreditAfter: {type: number}
|