252 lines
13 KiB
YAML
252 lines
13 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Finance F1 Manual AR API
|
||
version: 1.0.0
|
||
description: 首期人工账单、收款和成本接口；仅 CNY，平台财务可写，客户只读。
|
||
servers:
|
||
- url: /api
|
||
paths:
|
||
/platform/finance/v1/customers/{tenantId}/terms:
|
||
get:
|
||
summary: 查询客户账期
|
||
x-permission: platform:finance:customer-terms:view
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/TenantId'}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessObject'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
put:
|
||
summary: 保存客户账期
|
||
x-permission: platform:finance:customer-terms:update
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CustomerTermsRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessObject'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
/platform/finance/v1/bills:
|
||
get:
|
||
summary: 查询平台账单
|
||
x-permission: platform:finance:bill:view
|
||
security: [{platformFinance: []}]
|
||
parameters:
|
||
- {$ref: '#/components/parameters/RequiredCustomerId'}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessList'}}
|
||
post:
|
||
summary: 创建账单草稿
|
||
x-permission: platform:finance:bill:create
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateBillRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
/platform/finance/v1/bills/{billId}:
|
||
get:
|
||
summary: 查询平台账单详情
|
||
x-permission: platform:finance:bill:view
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/BillId'}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
|
||
put:
|
||
summary: 更新账单草稿
|
||
x-permission: platform:finance:bill:update
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/UpdateBillRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
|
||
/platform/finance/v1/bills/{billId}/issue:
|
||
post:
|
||
summary: 出账并冻结账单
|
||
x-permission: platform:finance:bill:issue
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/VersionRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
|
||
/platform/finance/v1/bills/{billId}/adjust:
|
||
post:
|
||
summary: 出账后调整并生成新版本
|
||
x-permission: platform:finance:bill:adjust
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/AdjustBillRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
|
||
/platform/finance/v1/bills/{billId}/void:
|
||
post:
|
||
summary: 作废账单
|
||
x-permission: platform:finance:bill:void
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/BillId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReasonRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
|
||
/platform/finance/v1/receipts:
|
||
post:
|
||
summary: 人工登记收款并分配账单
|
||
x-permission: platform:finance:receipt:create
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateReceiptRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessReceipt'}}
|
||
get:
|
||
summary: 查询收款记录
|
||
x-permission: platform:finance:receipt:view
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/OptionalCustomerId'}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessList'}}
|
||
/platform/finance/v1/cost-entries:
|
||
post:
|
||
summary: 人工登记单票或整柜成本
|
||
x-permission: platform:finance:cost:create
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
|
||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateCostRequest'}}}}
|
||
responses: {'200': {$ref: '#/components/responses/SuccessCost'}}
|
||
get:
|
||
summary: 查询成本记录
|
||
x-permission: platform:finance:cost:view
|
||
security: [{platformFinance: []}]
|
||
parameters: [{$ref: '#/components/parameters/OptionalCustomerId'}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessList'}}
|
||
/client/finance/v1/bills:
|
||
get:
|
||
summary: 客户只读查询账单
|
||
x-permission: merchant:finance:statement:list
|
||
security: [{customerFinanceRead: []}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessList'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
/client/finance/v1/bills/{billId}:
|
||
get:
|
||
summary: 客户只读查看账单详情
|
||
x-permission: merchant:finance:statement:view
|
||
security: [{customerFinanceRead: []}]
|
||
parameters: [{$ref: '#/components/parameters/BillId'}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
/client/finance/v1/receipts:
|
||
get:
|
||
summary: 客户只读查询收款记录
|
||
x-permission: merchant:finance:statement:view
|
||
security: [{customerFinanceRead: []}]
|
||
responses: {'200': {$ref: '#/components/responses/SuccessList'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
components:
|
||
securitySchemes:
|
||
platformFinance: {type: http, scheme: bearer}
|
||
customerFinanceRead: {type: http, scheme: bearer}
|
||
parameters:
|
||
BillId: {name: billId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
TenantId: {name: tenantId, in: path, required: true, description: 后端兼容字段，对应产品中的客户 ID, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
RequiredCustomerId: {name: customerId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
OptionalCustomerId: {name: customerId, in: query, required: false, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||
IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
|
||
schemas:
|
||
CustomerTermsRequest:
|
||
type: object
|
||
required: [creditDays]
|
||
properties:
|
||
customerName: {type: string, maxLength: 200, description: 客户名称快照；未传时由服务端按客户主数据补齐}
|
||
creditDays: {type: integer, minimum: 0, maximum: 3650, default: 30, description: 自然日账期}
|
||
CreateBillRequest:
|
||
type: object
|
||
required: [customerId, billDate, lines]
|
||
properties:
|
||
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
billDate: {type: string, format: date}
|
||
lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}
|
||
UpdateBillRequest:
|
||
type: object
|
||
required: [customerId, billDate, expectedVersion, lines]
|
||
properties:
|
||
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
billDate: {type: string, format: date}
|
||
expectedVersion: {type: integer, minimum: 0}
|
||
lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}
|
||
BillLineInput:
|
||
type: object
|
||
required: [sourceFeeId, sourceFeeVersion, amount]
|
||
properties:
|
||
sourceFeeId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
sourceFeeVersion: {type: integer, minimum: 1}
|
||
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
inboundId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
feeItemName: {type: string}
|
||
amount: {type: number, minimum: 0, multipleOf: 0.000001}
|
||
VersionRequest:
|
||
type: object
|
||
required: [expectedVersion]
|
||
properties: {expectedVersion: {type: integer, minimum: 0}}
|
||
ReasonRequest:
|
||
type: object
|
||
required: [expectedVersion, reason]
|
||
properties:
|
||
expectedVersion: {type: integer, minimum: 0}
|
||
reason: {type: string, minLength: 1, maxLength: 500}
|
||
AdjustBillRequest:
|
||
allOf:
|
||
- {$ref: '#/components/schemas/ReasonRequest'}
|
||
- type: object
|
||
required: [lines]
|
||
properties: {lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}}
|
||
CreateReceiptRequest:
|
||
type: object
|
||
required: [customerId, receivedDate, amount, paymentMethod, voucherFileIds, allocations]
|
||
properties:
|
||
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
receivedDate: {type: string, format: date}
|
||
amount: {type: number, minimum: 0, exclusiveMinimum: true, multipleOf: 0.000001}
|
||
currency: {type: string, enum: [CNY], default: CNY}
|
||
paymentMethod: {type: string, enum: [BANK_TRANSFER, CASH, OTHER]}
|
||
voucherFileIds: {type: array, minItems: 1, items: {type: string}}
|
||
remark: {type: string, maxLength: 500}
|
||
allocations: {type: array, minItems: 1, items: {$ref: '#/components/schemas/ReceiptAllocationInput'}}
|
||
example:
|
||
customerId: '10001'
|
||
receivedDate: '2026-08-11'
|
||
amount: 300
|
||
currency: CNY
|
||
paymentMethod: BANK_TRANSFER
|
||
voucherFileIds: ['90001']
|
||
allocations:
|
||
- {billId: '81001', amount: 100}
|
||
- {billId: '81002', amount: 100}
|
||
- {billId: '81003', amount: 100}
|
||
ReceiptAllocationInput:
|
||
type: object
|
||
required: [billId, amount]
|
||
properties:
|
||
billId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
amount: {type: number, minimum: 0, exclusiveMinimum: true, multipleOf: 0.000001}
|
||
CreateCostRequest:
|
||
type: object
|
||
description: SINGLE_ORDER 必须提供 orderId；CONTAINER_SHARED 必须提供 containerId，并按柜内有效票体积分摊。
|
||
required: [customerId, costType, amount, expenseName, voucherFileIds]
|
||
properties:
|
||
customerId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED]}
|
||
orderId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
containerId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
expenseName: {type: string, minLength: 1, maxLength: 100}
|
||
amount: {type: number, minimum: 0, exclusiveMinimum: true, multipleOf: 0.000001}
|
||
currency: {type: string, enum: [CNY], default: CNY}
|
||
voucherFileIds: {type: array, minItems: 1, items: {type: string}}
|
||
remark: {type: string, maxLength: 500}
|
||
BillStatus: {type: string, enum: [DRAFT, ISSUED, PARTIALLY_PAID, PAID, VOIDED]}
|
||
ApiEnvelope:
|
||
type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {type: object, additionalProperties: true}
|
||
requestId: {type: string}
|
||
ApiListEnvelope:
|
||
type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {type: array, items: {type: object, additionalProperties: true}}
|
||
requestId: {type: string}
|
||
ErrorEnvelope:
|
||
type: object
|
||
required: [code, message]
|
||
properties: {code: {type: string}, message: {type: string}, requestId: {type: string}}
|
||
responses:
|
||
SuccessBill: {description: Bill result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
|
||
SuccessReceipt: {description: Receipt result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
|
||
SuccessCost: {description: Cost result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
|
||
SuccessObject: {description: Object result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
|
||
SuccessList: {description: Non-paged list result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiListEnvelope'}}}}
|
||
BusinessError: {description: Business error, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}}}
|