1370 lines
41 KiB
YAML
1370 lines
41 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Finance F1 Manual AR API
|
||
version: 1.3.0
|
||
description: >-
|
||
F1 人工账单、收款和成本目标契约。仅 CNY；平台财务可写；客户只读且仅可见
|
||
ISSUED、PARTIALLY_PAID、PAID 账单。整柜成本由 Finance 根据 containerId 调用
|
||
Firstleg 真实快照，浏览器不提交订单体积。固定 DTO、完整追踪字段和 File fail-closed
|
||
校验仍属于放行目标；当前实现差异见契约门禁文档。
|
||
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/CustomerTermsResponse'
|
||
'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/CustomerTermsResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/platform/finance/v1/bills:
|
||
get:
|
||
summary: 查询平台账单
|
||
x-permission: platform:finance:customer-statement:list
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/RequiredCustomerId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/BillListResponse'
|
||
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/BillDetailResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/platform/finance/v1/bills/{billId}:
|
||
get:
|
||
summary: 查询平台账单详情
|
||
x-permission: platform:finance:customer-statement:list
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/BillId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/BillDetailResponse'
|
||
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/BillDetailResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/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/BillDetailResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/platform/finance/v1/bills/{billId}/revisions:
|
||
get:
|
||
summary: 查询账单修订历史
|
||
description: 只返回指定客户所属账单的调整前快照，跨客户或不存在账单统一拒绝。
|
||
x-permission: platform:finance:customer-statement:list
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/BillId'
|
||
- $ref: '#/components/parameters/RequiredCustomerId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/BillRevisionListResponse'
|
||
'404':
|
||
$ref: '#/components/responses/BusinessError'
|
||
/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/BillDetailResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/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/BillDetailResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/platform/finance/v1/receipts:
|
||
get:
|
||
summary: 查询收款记录
|
||
x-permission: platform:finance:receipt:view
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/OptionalCustomerId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/ReceiptListResponse'
|
||
post:
|
||
summary: 人工登记收款并分配账单
|
||
description: voucherFileIds 必须先通过 File 财务凭证上传接口取得，并通过客户、用途和状态校验。
|
||
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/ReceiptResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/platform/finance/v1/cost-entries:
|
||
get:
|
||
summary: 查询成本记录
|
||
x-permission: platform:finance:cost:view
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/OptionalCustomerId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/CostListResponse'
|
||
post:
|
||
summary: 人工登记单票或整柜成本
|
||
description: >-
|
||
SINGLE_ORDER 直接归属经服务端验证的同客户订单；CONTAINER_SHARED 只提交 containerId，
|
||
Finance 从 Firstleg 取得属于该客户的柜内有效订单体积快照。快照为空或总体积无效时拒绝，
|
||
首期不支持浏览器提交体积或人工分摊。
|
||
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/CostResponse'
|
||
'409':
|
||
$ref: '#/components/responses/IdempotencyConflict'
|
||
/platform/finance/v1/container-settlement-details:
|
||
get:
|
||
summary: 按客户和柜次查询已结算柜费及成本分摊
|
||
description: >-
|
||
为装柜清单柜费页提供固定请求量聚合。服务端校验柜次在 Finance 快照中的客户归属，
|
||
以集合查询一次返回已进入 PAID 正式结算或 FIRSTLEG_DIRECT_PAID 已确认成本的
|
||
CONTAINER_FEE 来源 ID，以及该客户在该柜下的全部成本及不可变分摊明细。
|
||
不返回整张结算单、其他客户数据或平台凭证。
|
||
x-permissions-all-of:
|
||
- platform:finance:cost:view
|
||
- platform:finance:settlement-ar:list
|
||
- platform:finance:settlement-ap:list
|
||
x-query-count: 3 fixed set-based SQL statements
|
||
x-customer-isolation: customerId 与 containerBookingId 必须在 Finance 费用来源或成本快照中存在真实归属关系。
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/RequiredCustomerId'
|
||
- $ref: '#/components/parameters/ContainerBookingId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/ContainerSettlementDetailsResponse'
|
||
'403':
|
||
$ref: '#/components/responses/BusinessError'
|
||
'404':
|
||
$ref: '#/components/responses/BusinessError'
|
||
/platform/finance/v1/vouchers:
|
||
post:
|
||
summary: 上传财务凭证图片
|
||
description: >-
|
||
当前 Finance Controller 的真实入口，query 参数为 customerId，multipart 字段为 file。
|
||
收款与成本创建均按客户、FINANCE_VOUCHER 业务类型和图片 MIME 校验元数据；
|
||
File 客户端缺失时仍须改为 fail-closed，详见门禁文档。
|
||
x-permission-any-of:
|
||
- platform:finance:receipt:create
|
||
- platform:finance:cost:create
|
||
- platform:finance:fee-source:edit
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/RequiredCustomerId'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
$ref: '#/components/schemas/FinanceVoucherUploadRequest'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/VoucherUploadResponse'
|
||
/platform/finance/v1/vouchers/{fileId}:
|
||
get:
|
||
summary: 读取付款凭证名称及类型
|
||
description: 按 customerId 校验 File 的客户、FINANCE_VOUCHER 类型和业务归属；下载响应禁止缓存并使用 attachment。
|
||
x-permission: platform:finance:customer-arap:list
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/RequiredCustomerId'
|
||
- name: fileId
|
||
in: path
|
||
required: true
|
||
schema: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
required: [fileId, fileName, contentType, sizeBytes]
|
||
properties:
|
||
fileId: {type: string}
|
||
fileName: {type: string}
|
||
contentType: {type: string}
|
||
sizeBytes: {type: integer, format: int64}
|
||
'400':
|
||
$ref: '#/components/responses/BusinessError'
|
||
'403':
|
||
$ref: '#/components/responses/BusinessError'
|
||
/platform/finance/v1/vouchers/{fileId}/content:
|
||
get:
|
||
summary: 下载付款凭证
|
||
description: 按 customerId 校验 File 的客户、FINANCE_VOUCHER 类型和业务归属；下载响应禁止缓存并使用 attachment。
|
||
x-permission: platform:finance:customer-arap:list
|
||
security:
|
||
- platformFinance: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/RequiredCustomerId'
|
||
- name: fileId
|
||
in: path
|
||
required: true
|
||
schema: {type: string, pattern: '^[1-9][0-9]*$'}
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/octet-stream:
|
||
schema: {type: string, format: binary}
|
||
'400':
|
||
$ref: '#/components/responses/BusinessError'
|
||
'403':
|
||
$ref: '#/components/responses/BusinessError'
|
||
/client/finance/v1/bills:
|
||
get:
|
||
summary: 客户只读查询可见账单
|
||
description: 服务端只返回当前客户且状态为 ISSUED、PARTIALLY_PAID、PAID 的账单。
|
||
x-permission: merchant:finance:statement:list
|
||
security:
|
||
- customerFinanceRead: []
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/ClientBillListResponse'
|
||
'403':
|
||
$ref: '#/components/responses/BusinessError'
|
||
/client/finance/v1/bills/{billId}:
|
||
get:
|
||
summary: 客户只读查看可见账单详情
|
||
description: DRAFT、VOIDED、跨客户或不存在的账单统一返回 FIN-AR-001，不泄露资源是否存在。
|
||
x-permission: merchant:finance:statement:view
|
||
security:
|
||
- customerFinanceRead: []
|
||
parameters:
|
||
- $ref: '#/components/parameters/BillId'
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/ClientBillDetailResponse'
|
||
'404':
|
||
$ref: '#/components/responses/BusinessError'
|
||
/client/finance/v1/receipts:
|
||
get:
|
||
summary: 客户只读查询收款记录
|
||
description: 仅返回分配到当前客户可见账单的收款信息，不返回平台凭证 fileId 和内部备注。
|
||
x-permission: merchant:finance:statement:view
|
||
security:
|
||
- customerFinanceRead: []
|
||
responses:
|
||
'200':
|
||
$ref: '#/components/responses/ClientReceiptListResponse'
|
||
'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:
|
||
$ref: '#/components/schemas/Id'
|
||
TenantId:
|
||
name: tenantId
|
||
in: path
|
||
required: true
|
||
description: 后端兼容字段，对应产品中的客户 ID。
|
||
schema:
|
||
$ref: '#/components/schemas/Id'
|
||
RequiredCustomerId:
|
||
name: customerId
|
||
in: query
|
||
required: true
|
||
schema:
|
||
$ref: '#/components/schemas/Id'
|
||
OptionalCustomerId:
|
||
name: customerId
|
||
in: query
|
||
required: false
|
||
schema:
|
||
$ref: '#/components/schemas/Id'
|
||
ContainerBookingId:
|
||
name: containerBookingId
|
||
in: query
|
||
required: true
|
||
description: Firstleg 真实货柜 containerBookingId，不是装柜计划 loadingPlanId。
|
||
schema:
|
||
$ref: '#/components/schemas/Id'
|
||
IdempotencyKey:
|
||
name: Idempotency-Key
|
||
in: header
|
||
required: true
|
||
description: >-
|
||
服务端以 HTTP method、规范化 path、客户范围和完整规范化 JSON body 计算请求哈希。
|
||
同键同参重放原结果；同键异参冲突；PROCESSING 返回 409 和 Retry-After。
|
||
schema:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
schemas:
|
||
Id:
|
||
type: string
|
||
pattern: '^[1-9][0-9]*$'
|
||
Money:
|
||
type: string
|
||
pattern: '^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$'
|
||
example: '300.000000'
|
||
ResponseMeta:
|
||
type: object
|
||
required:
|
||
- requestId
|
||
- traceId
|
||
- timestamp
|
||
properties:
|
||
requestId:
|
||
type: string
|
||
minLength: 1
|
||
traceId:
|
||
type: string
|
||
minLength: 1
|
||
timestamp:
|
||
type: string
|
||
format: date-time
|
||
description: UTC ISO-8601 时间。
|
||
CustomerTermsRequest:
|
||
type: object
|
||
required:
|
||
- creditDays
|
||
properties:
|
||
customerName:
|
||
type: string
|
||
maxLength: 200
|
||
creditDays:
|
||
type: integer
|
||
minimum: 0
|
||
maximum: 3650
|
||
default: 30
|
||
CreateBillRequest:
|
||
type: object
|
||
required:
|
||
- customerId
|
||
- billDate
|
||
- lines
|
||
properties:
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
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:
|
||
$ref: '#/components/schemas/Id'
|
||
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
|
||
- feeItemName
|
||
- amount
|
||
properties:
|
||
sourceFeeId:
|
||
$ref: '#/components/schemas/Id'
|
||
sourceFeeVersion:
|
||
type: integer
|
||
minimum: 1
|
||
orderId:
|
||
$ref: '#/components/schemas/Id'
|
||
inboundId:
|
||
$ref: '#/components/schemas/Id'
|
||
feeItemName:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 100
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
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:
|
||
$ref: '#/components/schemas/Id'
|
||
receivedDate:
|
||
type: string
|
||
format: date
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
currency:
|
||
type: string
|
||
enum:
|
||
- CNY
|
||
default: CNY
|
||
paymentMethod:
|
||
type: string
|
||
enum:
|
||
- BANK_TRANSFER
|
||
- CASH
|
||
- OTHER
|
||
voucherFileIds:
|
||
type: array
|
||
minItems: 1
|
||
uniqueItems: true
|
||
items:
|
||
$ref: '#/components/schemas/Id'
|
||
remark:
|
||
type: string
|
||
maxLength: 500
|
||
allocations:
|
||
type: array
|
||
minItems: 1
|
||
items:
|
||
$ref: '#/components/schemas/ReceiptAllocationInput'
|
||
example:
|
||
customerId: '10001'
|
||
receivedDate: '2026-08-11'
|
||
amount: '300.000000'
|
||
currency: CNY
|
||
paymentMethod: BANK_TRANSFER
|
||
voucherFileIds:
|
||
- '90001'
|
||
allocations:
|
||
- billId: '81001'
|
||
amount: '100.000000'
|
||
- billId: '81002'
|
||
amount: '100.000000'
|
||
- billId: '81003'
|
||
amount: '100.000000'
|
||
ReceiptAllocationInput:
|
||
type: object
|
||
required:
|
||
- billId
|
||
- amount
|
||
properties:
|
||
billId:
|
||
$ref: '#/components/schemas/Id'
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
CreateCostRequest:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/CreateSingleOrderCostRequest'
|
||
- $ref: '#/components/schemas/CreateContainerCostRequest'
|
||
discriminator:
|
||
propertyName: costType
|
||
mapping:
|
||
SINGLE_ORDER: '#/components/schemas/CreateSingleOrderCostRequest'
|
||
CONTAINER_SHARED: '#/components/schemas/CreateContainerCostRequest'
|
||
CostRequestBase:
|
||
type: object
|
||
required:
|
||
- customerId
|
||
- amount
|
||
- expenseName
|
||
- voucherFileIds
|
||
properties:
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
expenseName:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 100
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
currency:
|
||
type: string
|
||
enum:
|
||
- CNY
|
||
default: CNY
|
||
voucherFileIds:
|
||
type: array
|
||
minItems: 1
|
||
uniqueItems: true
|
||
items:
|
||
$ref: '#/components/schemas/Id'
|
||
remark:
|
||
type: string
|
||
maxLength: 500
|
||
CreateSingleOrderCostRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/CostRequestBase'
|
||
- type: object
|
||
required:
|
||
- costType
|
||
- orderId
|
||
properties:
|
||
costType:
|
||
type: string
|
||
enum:
|
||
- SINGLE_ORDER
|
||
orderId:
|
||
$ref: '#/components/schemas/Id'
|
||
CreateContainerCostRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/CostRequestBase'
|
||
- type: object
|
||
required:
|
||
- costType
|
||
- containerId
|
||
properties:
|
||
costType:
|
||
type: string
|
||
enum:
|
||
- CONTAINER_SHARED
|
||
containerId:
|
||
$ref: '#/components/schemas/Id'
|
||
FinanceVoucherUploadRequest:
|
||
type: object
|
||
required:
|
||
- file
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
BillStatus:
|
||
type: string
|
||
enum:
|
||
- DRAFT
|
||
- ISSUED
|
||
- PARTIALLY_PAID
|
||
- PAID
|
||
- VOIDED
|
||
ClientBillStatus:
|
||
type: string
|
||
enum:
|
||
- ISSUED
|
||
- PARTIALLY_PAID
|
||
- PAID
|
||
Bill:
|
||
type: object
|
||
required:
|
||
- billId
|
||
- billNo
|
||
- customerId
|
||
- customerName
|
||
- billDate
|
||
- dueDate
|
||
- currency
|
||
- totalAmount
|
||
- receivedAmount
|
||
- outstandingAmount
|
||
- status
|
||
- version
|
||
properties:
|
||
billId:
|
||
$ref: '#/components/schemas/Id'
|
||
billNo:
|
||
type: string
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
customerName:
|
||
type: string
|
||
billDate:
|
||
type: string
|
||
format: date
|
||
dueDate:
|
||
type: string
|
||
format: date
|
||
currency:
|
||
type: string
|
||
enum:
|
||
- CNY
|
||
totalAmount:
|
||
$ref: '#/components/schemas/Money'
|
||
receivedAmount:
|
||
$ref: '#/components/schemas/Money'
|
||
outstandingAmount:
|
||
$ref: '#/components/schemas/Money'
|
||
status:
|
||
$ref: '#/components/schemas/BillStatus'
|
||
version:
|
||
type: integer
|
||
minimum: 0
|
||
ClientBill:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Bill'
|
||
- type: object
|
||
properties:
|
||
status:
|
||
$ref: '#/components/schemas/ClientBillStatus'
|
||
BillLine:
|
||
type: object
|
||
required:
|
||
- lineId
|
||
- sourceFeeId
|
||
- sourceFeeVersion
|
||
- feeItemName
|
||
- amount
|
||
properties:
|
||
lineId:
|
||
$ref: '#/components/schemas/Id'
|
||
sourceFeeId:
|
||
$ref: '#/components/schemas/Id'
|
||
sourceFeeVersion:
|
||
type: integer
|
||
minimum: 1
|
||
orderId:
|
||
$ref: '#/components/schemas/Id'
|
||
inboundId:
|
||
$ref: '#/components/schemas/Id'
|
||
feeItemName:
|
||
type: string
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
BillDetail:
|
||
allOf:
|
||
- $ref: '#/components/schemas/Bill'
|
||
- type: object
|
||
required:
|
||
- lines
|
||
properties:
|
||
lines:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/BillLine'
|
||
BillRevision:
|
||
type: object
|
||
required:
|
||
- revisionId
|
||
- billId
|
||
- version
|
||
- reason
|
||
- billSnapshot
|
||
- lineSnapshot
|
||
- createdBy
|
||
- createdAt
|
||
properties:
|
||
revisionId:
|
||
$ref: '#/components/schemas/Id'
|
||
billId:
|
||
$ref: '#/components/schemas/Id'
|
||
version:
|
||
type: integer
|
||
minimum: 0
|
||
reason:
|
||
type: string
|
||
billSnapshot:
|
||
type: object
|
||
additionalProperties: true
|
||
lineSnapshot:
|
||
type: array
|
||
items:
|
||
type: object
|
||
additionalProperties: true
|
||
createdBy:
|
||
$ref: '#/components/schemas/Id'
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
ClientBillDetail:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ClientBill'
|
||
- type: object
|
||
required:
|
||
- lines
|
||
properties:
|
||
lines:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/BillLine'
|
||
ReceiptAllocation:
|
||
type: object
|
||
required:
|
||
- billId
|
||
- allocatedAmount
|
||
properties:
|
||
billId:
|
||
$ref: '#/components/schemas/Id'
|
||
allocatedAmount:
|
||
$ref: '#/components/schemas/Money'
|
||
Receipt:
|
||
type: object
|
||
required:
|
||
- receiptId
|
||
- receiptNo
|
||
- customerId
|
||
- receivedDate
|
||
- amount
|
||
- currency
|
||
- paymentMethod
|
||
- voucherFileIds
|
||
- allocations
|
||
- createdAt
|
||
properties:
|
||
receiptId:
|
||
$ref: '#/components/schemas/Id'
|
||
receiptNo:
|
||
type: string
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
receivedDate:
|
||
type: string
|
||
format: date
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
currency:
|
||
type: string
|
||
enum:
|
||
- CNY
|
||
paymentMethod:
|
||
type: string
|
||
enum:
|
||
- BANK_TRANSFER
|
||
- CASH
|
||
- OTHER
|
||
voucherFileIds:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Id'
|
||
remark:
|
||
type: string
|
||
allocations:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ReceiptAllocation'
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
ClientReceipt:
|
||
type: object
|
||
required:
|
||
- receiptId
|
||
- receiptNo
|
||
- receivedDate
|
||
- amount
|
||
- currency
|
||
- paymentMethod
|
||
- allocations
|
||
properties:
|
||
receiptId:
|
||
$ref: '#/components/schemas/Id'
|
||
receiptNo:
|
||
type: string
|
||
receivedDate:
|
||
type: string
|
||
format: date
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
currency:
|
||
type: string
|
||
enum:
|
||
- CNY
|
||
paymentMethod:
|
||
type: string
|
||
allocations:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ReceiptAllocation'
|
||
CostAllocation:
|
||
type: object
|
||
required:
|
||
- orderId
|
||
- volumeCbm
|
||
- totalVolumeCbm
|
||
- ratio
|
||
- allocatedAmount
|
||
- roundingAdjustment
|
||
properties:
|
||
orderId:
|
||
$ref: '#/components/schemas/Id'
|
||
volumeCbm:
|
||
$ref: '#/components/schemas/Money'
|
||
totalVolumeCbm:
|
||
$ref: '#/components/schemas/Money'
|
||
ratio:
|
||
type: string
|
||
pattern: '^(0|1|0\.[0-9]{1,12})$'
|
||
allocatedAmount:
|
||
$ref: '#/components/schemas/Money'
|
||
roundingAdjustment:
|
||
type: boolean
|
||
description: 仅实际尾差非零时为 true。
|
||
Cost:
|
||
type: object
|
||
required:
|
||
- costId
|
||
- costNo
|
||
- customerId
|
||
- costType
|
||
- expenseName
|
||
- amount
|
||
- currency
|
||
- voucherFileIds
|
||
- allocations
|
||
- createdAt
|
||
properties:
|
||
costId:
|
||
$ref: '#/components/schemas/Id'
|
||
costNo:
|
||
type: string
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
costType:
|
||
type: string
|
||
enum:
|
||
- SINGLE_ORDER
|
||
- CONTAINER_SHARED
|
||
orderId:
|
||
$ref: '#/components/schemas/Id'
|
||
containerId:
|
||
$ref: '#/components/schemas/Id'
|
||
allocationMode:
|
||
type: string
|
||
enum:
|
||
- DIRECT
|
||
- AUTO_VOLUME
|
||
expenseName:
|
||
type: string
|
||
amount:
|
||
$ref: '#/components/schemas/Money'
|
||
currency:
|
||
type: string
|
||
enum:
|
||
- CNY
|
||
voucherFileIds:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Id'
|
||
allocations:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/CostAllocation'
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
ContainerSettlementDetails:
|
||
type: object
|
||
required: [customerId, containerBookingId, settledSourceFeeIds, costs]
|
||
properties:
|
||
customerId: {$ref: '#/components/schemas/Id'}
|
||
containerBookingId: {$ref: '#/components/schemas/Id'}
|
||
settledSourceFeeIds:
|
||
type: array
|
||
uniqueItems: true
|
||
items: {$ref: '#/components/schemas/Id'}
|
||
costs:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ContainerSettlementCost'}
|
||
ContainerSettlementCost:
|
||
type: object
|
||
required: [costId, costNo, costType, costOrigin, containerBookingId, feeItemName, amount, currency, status, allocations]
|
||
properties:
|
||
costId: {$ref: '#/components/schemas/Id'}
|
||
costNo: {type: string}
|
||
costType: {type: string, enum: [SINGLE_ORDER, CONTAINER_SHARED, SOURCE_DIRECT_PAID]}
|
||
costOrigin: {type: string, enum: [MANUAL, FIRSTLEG_DIRECT_PAID, BUSINESS_DIRECT_PAID]}
|
||
sourceFeeId: {$ref: '#/components/schemas/Id'}
|
||
sourceFeeVersion: {type: integer, minimum: 1}
|
||
containerBookingId: {$ref: '#/components/schemas/Id'}
|
||
supplierName: {type: string}
|
||
feeItemName: {type: string}
|
||
amount: {$ref: '#/components/schemas/Money'}
|
||
currency: {type: string, enum: [CNY]}
|
||
status: {type: string, enum: [DRAFT, CONFIRMED, VOIDED]}
|
||
allocations:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ContainerSettlementCostAllocation'}
|
||
ContainerSettlementCostAllocation:
|
||
type: object
|
||
required: [allocationId, orderId, volumeCbm, totalVolumeCbm, allocationRate, allocatedAmount, roundingAdjustment]
|
||
properties:
|
||
allocationId: {$ref: '#/components/schemas/Id'}
|
||
orderId: {$ref: '#/components/schemas/Id'}
|
||
inboundId: {$ref: '#/components/schemas/Id'}
|
||
volumeCbm: {$ref: '#/components/schemas/Money'}
|
||
totalVolumeCbm: {$ref: '#/components/schemas/Money'}
|
||
allocationRate: {type: string, pattern: '^(0|1|0\.[0-9]{1,10})$'}
|
||
allocatedAmount: {$ref: '#/components/schemas/Money'}
|
||
roundingAdjustment: {type: boolean}
|
||
CustomerTerms:
|
||
type: object
|
||
required:
|
||
- customerId
|
||
- creditDays
|
||
- status
|
||
- version
|
||
properties:
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
customerName:
|
||
type: string
|
||
creditDays:
|
||
type: integer
|
||
minimum: 0
|
||
maximum: 3650
|
||
status:
|
||
type: string
|
||
enum:
|
||
- ACTIVE
|
||
version:
|
||
type: integer
|
||
minimum: 0
|
||
VoucherFile:
|
||
type: object
|
||
required:
|
||
- fileId
|
||
- customerId
|
||
- fileName
|
||
- contentType
|
||
- sizeBytes
|
||
properties:
|
||
fileId:
|
||
$ref: '#/components/schemas/Id'
|
||
customerId:
|
||
$ref: '#/components/schemas/Id'
|
||
fileName:
|
||
type: string
|
||
contentType:
|
||
type: string
|
||
enum:
|
||
- image/jpeg
|
||
- image/png
|
||
- image/webp
|
||
sizeBytes:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 10485760
|
||
ErrorDetail:
|
||
type: object
|
||
required:
|
||
- field
|
||
- reason
|
||
properties:
|
||
field:
|
||
type: string
|
||
reason:
|
||
type: string
|
||
ErrorEnvelope:
|
||
type: object
|
||
required:
|
||
- code
|
||
- message
|
||
- requestId
|
||
- traceId
|
||
- timestamp
|
||
properties:
|
||
code:
|
||
type: string
|
||
example: FIN-AR-002
|
||
description: >-
|
||
稳定业务码。体积快照/归属使用 FIN-COST-VOLUME-SNAPSHOT-REQUIRED、
|
||
FIN-COST-VOLUME-SNAPSHOT-INVALID、FIN-COST-CUSTOMER-MISMATCH、
|
||
FIN-COST-ORDER-NOT-IN-CONTAINER；凭证使用 FIN-FILE-VALIDATION-UNAVAILABLE、
|
||
FIN-FILE-CUSTOMER-MISMATCH、FIN-FILE-TYPE-INVALID；幂等使用
|
||
FIN-IDEMPOTENCY-CONFLICT、FIN-IDEMPOTENCY-PROCESSING。
|
||
message:
|
||
type: string
|
||
details:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ErrorDetail'
|
||
requestId:
|
||
type: string
|
||
traceId:
|
||
type: string
|
||
timestamp:
|
||
type: string
|
||
format: date-time
|
||
BillListEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Bill'}
|
||
ClientBillListEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ClientBill'}
|
||
BillDetailEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/BillDetail'}
|
||
BillRevisionListEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/BillRevision'}
|
||
ClientBillDetailEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/ClientBillDetail'}
|
||
ReceiptEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/Receipt'}
|
||
ReceiptListEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Receipt'}
|
||
ClientReceiptListEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ClientReceipt'}
|
||
CostEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/Cost'}
|
||
CostListEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/Cost'}
|
||
ContainerSettlementDetailsEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/ContainerSettlementDetails'}
|
||
CustomerTermsEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/CustomerTerms'}
|
||
VoucherUploadEnvelope:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResponseMeta'
|
||
- type: object
|
||
required: [code, message, data]
|
||
properties:
|
||
code: {type: string, example: '200'}
|
||
message: {type: string}
|
||
data: {$ref: '#/components/schemas/VoucherFile'}
|
||
responses:
|
||
BillListResponse:
|
||
description: 平台账单列表。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/BillListEnvelope'}
|
||
ClientBillListResponse:
|
||
description: 客户可见账单列表。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ClientBillListEnvelope'}
|
||
BillDetailResponse:
|
||
description: 平台账单详情。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/BillDetailEnvelope'}
|
||
BillRevisionListResponse:
|
||
description: 账单修订历史列表。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/BillRevisionListEnvelope'}
|
||
ClientBillDetailResponse:
|
||
description: 客户可见账单详情。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ClientBillDetailEnvelope'}
|
||
ReceiptResponse:
|
||
description: 收款结果。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ReceiptEnvelope'}
|
||
ReceiptListResponse:
|
||
description: 平台收款列表。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ReceiptListEnvelope'}
|
||
ClientReceiptListResponse:
|
||
description: 客户可见收款列表。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ClientReceiptListEnvelope'}
|
||
CostResponse:
|
||
description: 成本结果。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/CostEnvelope'}
|
||
CostListResponse:
|
||
description: 成本列表。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/CostListEnvelope'}
|
||
ContainerSettlementDetailsResponse:
|
||
description: 柜级已结算来源与成本分摊聚合结果。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ContainerSettlementDetailsEnvelope'}
|
||
CustomerTermsResponse:
|
||
description: 客户账期结果。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/CustomerTermsEnvelope'}
|
||
VoucherUploadResponse:
|
||
description: 临时财务凭证元数据。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/VoucherUploadEnvelope'}
|
||
BusinessError:
|
||
description: 业务错误。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ErrorEnvelope'}
|
||
IdempotencyConflict:
|
||
description: >-
|
||
幂等冲突。同键异参返回 FIN-IDEMPOTENCY-CONFLICT；同键同参且原请求仍为 PROCESSING
|
||
返回 FIN-IDEMPOTENCY-PROCESSING，并携带 Retry-After: 2。
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
description: 仅 PROCESSING 时返回，单位秒。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ErrorEnvelope'}
|