204 lines
9.8 KiB
YAML
204 lines
9.8 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/bills:
|
||
|
|
get:
|
||
|
|
summary: 查询平台账单
|
||
|
|
security: [{platformFinance: []}]
|
||
|
|
parameters:
|
||
|
|
- {$ref: '#/components/parameters/CustomerId'}
|
||
|
|
- {name: status, in: query, schema: {$ref: '#/components/schemas/BillStatus'}}
|
||
|
|
- {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
|
||
|
|
- {name: pageSize, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
|
||
|
|
post:
|
||
|
|
summary: 创建账单草稿
|
||
|
|
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: 查询平台账单详情
|
||
|
|
security: [{platformFinance: []}]
|
||
|
|
parameters: [{$ref: '#/components/parameters/BillId'}]
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessBill'}}
|
||
|
|
put:
|
||
|
|
summary: 更新账单草稿
|
||
|
|
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: 出账并冻结账单
|
||
|
|
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: 出账后调整并生成新版本
|
||
|
|
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: 作废账单
|
||
|
|
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: 人工登记收款并分配账单
|
||
|
|
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: 查询收款记录
|
||
|
|
security: [{platformFinance: []}]
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
|
||
|
|
/platform/finance/v1/cost-entries:
|
||
|
|
post:
|
||
|
|
summary: 人工登记单票或整柜成本
|
||
|
|
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: 查询成本记录
|
||
|
|
security: [{platformFinance: []}]
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessPage'}}
|
||
|
|
/client/finance/v1/bills:
|
||
|
|
get:
|
||
|
|
summary: 客户只读查询账单
|
||
|
|
security: [{customerFinanceRead: []}]
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
|
|
/client/finance/v1/bills/{billId}:
|
||
|
|
get:
|
||
|
|
summary: 客户只读查看账单详情
|
||
|
|
security: [{customerFinanceRead: []}]
|
||
|
|
parameters: [{$ref: '#/components/parameters/BillId'}]
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessBill'}, '403': {$ref: '#/components/responses/BusinessError'}}
|
||
|
|
/client/finance/v1/receipts:
|
||
|
|
get:
|
||
|
|
summary: 客户只读查询收款记录
|
||
|
|
security: [{customerFinanceRead: []}]
|
||
|
|
responses: {'200': {$ref: '#/components/responses/SuccessPage'}, '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]*$'}}
|
||
|
|
CustomerId: {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:
|
||
|
|
CreateBillRequest:
|
||
|
|
type: object
|
||
|
|
required: [customerId, billDate, lines]
|
||
|
|
properties:
|
||
|
|
customerId: {type: string}
|
||
|
|
billDate: {type: string, format: date}
|
||
|
|
lines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/BillLineInput'}}
|
||
|
|
UpdateBillRequest:
|
||
|
|
allOf:
|
||
|
|
- {$ref: '#/components/schemas/CreateBillRequest'}
|
||
|
|
- type: object
|
||
|
|
required: [expectedVersion]
|
||
|
|
properties: {expectedVersion: {type: integer, minimum: 0}}
|
||
|
|
BillLineInput:
|
||
|
|
type: object
|
||
|
|
required: [sourceFeeId, sourceFeeVersion, amount]
|
||
|
|
properties:
|
||
|
|
sourceFeeId: {type: string}
|
||
|
|
sourceFeeVersion: {type: integer, minimum: 1}
|
||
|
|
orderId: {type: string}
|
||
|
|
inboundId: {type: string}
|
||
|
|
feeItemName: {type: string}
|
||
|
|
amount: {type: number, format: double, minimum: 0}
|
||
|
|
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}
|
||
|
|
receivedDate: {type: string, format: date}
|
||
|
|
amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
|
||
|
|
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}
|
||
|
|
amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
|
||
|
|
CreateCostRequest:
|
||
|
|
type: object
|
||
|
|
required: [costType, amount, expenseName, voucherFileIds]
|
||
|
|
properties:
|
||
|
|
costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED]}
|
||
|
|
orderId: {type: string}
|
||
|
|
containerId: {type: string}
|
||
|
|
expenseName: {type: string, minLength: 1, maxLength: 100}
|
||
|
|
amount: {type: number, format: double, minimum: 0, exclusiveMinimum: true}
|
||
|
|
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}
|
||
|
|
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'}}}}
|
||
|
|
SuccessPage: {description: Paged result, content: {application/json: {schema: {$ref: '#/components/schemas/ApiEnvelope'}}}}
|
||
|
|
BusinessError: {description: Business error, content: {application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}}}
|