docs/财务管理/openapi/finance-f1-manual-v1.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'}}}}