1346 lines
37 KiB
YAML
1346 lines
37 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Finance F1 Manual AR API
|
|
version: 1.1.0
|
|
description: >-
|
|
F1 人工账单、收款和成本目标契约。仅 CNY；平台财务可写；客户只读且仅可见
|
|
ISSUED、PARTIALLY_PAID、PAID 账单。所有响应使用固定 DTO 和统一追踪字段。
|
|
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:bill:view
|
|
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:bill:view
|
|
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}/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 默认按柜内同客户有效票体积分摊，
|
|
只有总体积为零时才接受 MANUAL_ZERO_VOLUME。
|
|
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/v1/files/finance-vouchers:
|
|
post:
|
|
summary: 上传财务凭证临时文件
|
|
description: >-
|
|
File 服务目标接口。文件上传后为 TEMPORARY，Finance 成功创建收款或成本后通过内部接口幂等关联。
|
|
临时文件不得直接向客户开放下载。
|
|
x-permissions:
|
|
- platform:finance:receipt:create
|
|
- platform:finance:cost:create
|
|
security:
|
|
- platformFinance: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
$ref: '#/components/schemas/FinanceVoucherUploadRequest'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/VoucherUploadResponse'
|
|
/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'
|
|
/internal/file/v1/finance-vouchers/validate:
|
|
post:
|
|
servers:
|
|
- url: /
|
|
summary: Finance 批量校验财务凭证
|
|
description: Finance 落单前同步调用；任一文件不合规则整批失败，Finance 不落业务数据。
|
|
security:
|
|
- internalService: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VoucherValidationRequest'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/VoucherValidationResponse'
|
|
/internal/file/v1/finance-vouchers/associate:
|
|
post:
|
|
servers:
|
|
- url: /
|
|
summary: Finance 幂等关联财务凭证
|
|
description: >-
|
|
Finance 落单成功后以业务幂等键调用。相同文件、资源类型和资源 ID 重放返回原关联结果；
|
|
已关联到其他资源时拒绝。调用失败进入 Finance Outbox 重试，不重复创建财务单据。
|
|
security:
|
|
- internalService: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/IdempotencyKey'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VoucherAssociationRequest'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/VoucherAssociationResponse'
|
|
'409':
|
|
$ref: '#/components/responses/IdempotencyConflict'
|
|
components:
|
|
securitySchemes:
|
|
platformFinance:
|
|
type: http
|
|
scheme: bearer
|
|
customerFinanceRead:
|
|
type: http
|
|
scheme: bearer
|
|
internalService:
|
|
type: apiKey
|
|
in: header
|
|
name: X-Internal-Service-Token
|
|
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'
|
|
IdempotencyKey:
|
|
name: Idempotency-Key
|
|
in: header
|
|
required: true
|
|
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
|
|
- allocationMode
|
|
properties:
|
|
costType:
|
|
type: string
|
|
enum:
|
|
- CONTAINER_SHARED
|
|
containerId:
|
|
$ref: '#/components/schemas/Id'
|
|
allocationMode:
|
|
type: string
|
|
enum:
|
|
- AUTO_VOLUME
|
|
- MANUAL_ZERO_VOLUME
|
|
default: AUTO_VOLUME
|
|
manualAllocations:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/ManualCostAllocationInput'
|
|
description: 仅柜内有效票总体积为零且 allocationMode=MANUAL_ZERO_VOLUME 时允许。
|
|
ManualCostAllocationInput:
|
|
type: object
|
|
required:
|
|
- orderId
|
|
- amount
|
|
properties:
|
|
orderId:
|
|
$ref: '#/components/schemas/Id'
|
|
amount:
|
|
$ref: '#/components/schemas/Money'
|
|
FinanceVoucherUploadRequest:
|
|
type: object
|
|
required:
|
|
- customerId
|
|
- purpose
|
|
- file
|
|
properties:
|
|
customerId:
|
|
$ref: '#/components/schemas/Id'
|
|
purpose:
|
|
type: string
|
|
enum:
|
|
- RECEIPT
|
|
- COST
|
|
file:
|
|
type: string
|
|
format: binary
|
|
VoucherValidationRequest:
|
|
type: object
|
|
required:
|
|
- customerId
|
|
- purpose
|
|
- fileIds
|
|
properties:
|
|
customerId:
|
|
$ref: '#/components/schemas/Id'
|
|
purpose:
|
|
type: string
|
|
enum:
|
|
- RECEIPT
|
|
- COST
|
|
fileIds:
|
|
type: array
|
|
minItems: 1
|
|
uniqueItems: true
|
|
items:
|
|
$ref: '#/components/schemas/Id'
|
|
VoucherAssociationRequest:
|
|
type: object
|
|
required:
|
|
- customerId
|
|
- purpose
|
|
- resourceType
|
|
- resourceId
|
|
- fileIds
|
|
properties:
|
|
customerId:
|
|
$ref: '#/components/schemas/Id'
|
|
purpose:
|
|
type: string
|
|
enum:
|
|
- RECEIPT
|
|
- COST
|
|
resourceType:
|
|
type: string
|
|
enum:
|
|
- FINANCE_RECEIPT
|
|
- FINANCE_COST
|
|
resourceId:
|
|
$ref: '#/components/schemas/Id'
|
|
fileIds:
|
|
type: array
|
|
minItems: 1
|
|
uniqueItems: true
|
|
items:
|
|
$ref: '#/components/schemas/Id'
|
|
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'
|
|
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:
|
|
$ref: '#/components/schemas/Money'
|
|
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
|
|
- MANUAL_ZERO_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
|
|
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
|
|
- purpose
|
|
- fileName
|
|
- contentType
|
|
- sizeBytes
|
|
- sha256
|
|
- status
|
|
properties:
|
|
fileId:
|
|
$ref: '#/components/schemas/Id'
|
|
customerId:
|
|
$ref: '#/components/schemas/Id'
|
|
purpose:
|
|
type: string
|
|
enum:
|
|
- RECEIPT
|
|
- COST
|
|
fileName:
|
|
type: string
|
|
contentType:
|
|
type: string
|
|
enum:
|
|
- image/jpeg
|
|
- image/png
|
|
- image/webp
|
|
- application/pdf
|
|
sizeBytes:
|
|
type: integer
|
|
format: int64
|
|
minimum: 1
|
|
maximum: 10485760
|
|
sha256:
|
|
type: string
|
|
pattern: '^[a-f0-9]{64}$'
|
|
status:
|
|
type: string
|
|
enum:
|
|
- TEMPORARY
|
|
- ASSOCIATED
|
|
resourceType:
|
|
type: string
|
|
resourceId:
|
|
$ref: '#/components/schemas/Id'
|
|
VoucherValidationResult:
|
|
type: object
|
|
required:
|
|
- valid
|
|
- files
|
|
properties:
|
|
valid:
|
|
type: boolean
|
|
files:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VoucherFile'
|
|
VoucherAssociationResult:
|
|
type: object
|
|
required:
|
|
- resourceType
|
|
- resourceId
|
|
- files
|
|
properties:
|
|
resourceType:
|
|
type: string
|
|
enum:
|
|
- FINANCE_RECEIPT
|
|
- FINANCE_COST
|
|
resourceId:
|
|
$ref: '#/components/schemas/Id'
|
|
files:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/VoucherFile'
|
|
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
|
|
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'}
|
|
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'}
|
|
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'}
|
|
VoucherValidationEnvelope:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ResponseMeta'
|
|
- type: object
|
|
required: [code, message, data]
|
|
properties:
|
|
code: {type: string, example: '200'}
|
|
message: {type: string}
|
|
data: {$ref: '#/components/schemas/VoucherValidationResult'}
|
|
VoucherAssociationEnvelope:
|
|
allOf:
|
|
- $ref: '#/components/schemas/ResponseMeta'
|
|
- type: object
|
|
required: [code, message, data]
|
|
properties:
|
|
code: {type: string, example: '200'}
|
|
message: {type: string}
|
|
data: {$ref: '#/components/schemas/VoucherAssociationResult'}
|
|
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'}
|
|
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'}
|
|
CustomerTermsResponse:
|
|
description: 客户账期结果。
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/CustomerTermsEnvelope'}
|
|
VoucherUploadResponse:
|
|
description: 临时财务凭证元数据。
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/VoucherUploadEnvelope'}
|
|
VoucherValidationResponse:
|
|
description: 财务凭证批量校验结果。
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/VoucherValidationEnvelope'}
|
|
VoucherAssociationResponse:
|
|
description: 财务凭证关联结果。
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/VoucherAssociationEnvelope'}
|
|
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'}
|