openapi: 3.0.3
info: {title: Firstleg Container Customs API, version: 2.0.0}
paths:
  /api/platform/v1/customs/loading-plans/{planId}:
    get:
      summary: 查询整柜报关状态、缺资料票及文件映射
      x-permission: platform:firstleg:customs:list
      parameters: [{$ref: '#/components/parameters/PlanId'}]
      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
  /api/platform/v1/customs/loading-plans/{planId}/start:
    post:
      summary: 确认开始整柜报关并冻结全部当前资料版本和覆盖范围
      x-permission: platform:firstleg:customs:manage
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {$ref: '#/components/requestBodies/ActionBody'}
      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
  /api/platform/v1/customs/loading-plans/{planId}/complete-all-buy:
    post:
      summary: 二次确认全买单柜报关完成
      x-permission: platform:firstleg:customs:manage
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {$ref: '#/components/requestBodies/ActionBody'}
      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
  /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/upload:
    post:
      summary: 上传或覆盖冻结客户资料的一对一完成文件
      description: 完成文件自动继承冻结入仓码且不可删除；最后一份须finalConfirmation=true，File调用前服务端预检。
      x-permission: platform:firstleg:customs:manage
      parameters:
        - {$ref: '#/components/parameters/DocumentId'}
        - {$ref: '#/components/parameters/IdempotencyKey'}
        - {name: expectedVersion, in: query, required: true, schema: {type: integer, minimum: 0}}
        - {name: finalConfirmation, in: query, required: true, schema: {type: boolean}}
      requestBody: {$ref: '#/components/requestBodies/FileBody'}
      responses: {'200': {$ref: '#/components/responses/DocumentResponse'}}
  /api/platform/v1/customs/loading-plans/documents/{documentId}/download:
    get:
      summary: 平台下载客户报送资料
      x-permission: platform:firstleg:customs:list
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
  /api/platform/v1/customs/loading-plans/documents/{documentId}/completion/download:
    get:
      summary: 平台下载报关完成文件
      x-permission: platform:firstleg:customs:list
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
  /api/merchant/v1/customs/orders/{orderId}:
    get:
      summary: 客户订单列表查询当前完成装柜退税报关四态
      x-permission: merchant:order:view
      parameters: [{$ref: '#/components/parameters/OrderId'}]
      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
  /api/merchant/v1/customs/loading-plans/{planId}/documents/upload:
    post:
      summary: 上传资料并关联当前柜内本客户一个或多个退税入仓码
      x-permission: merchant:order:edit
      parameters:
        - {$ref: '#/components/parameters/PlanId'}
        - {$ref: '#/components/parameters/IdempotencyKey'}
        - {$ref: '#/components/parameters/InboundIds'}
      requestBody: {$ref: '#/components/requestBodies/FileBody'}
      responses: {'200': {$ref: '#/components/responses/DocumentResponse'}}
  /api/merchant/v1/customs/documents/{documentId}/upload:
    post:
      summary: 报关开始前覆盖资料并同步修改同柜关联票
      x-permission: merchant:order:edit
      parameters:
        - {$ref: '#/components/parameters/DocumentId'}
        - {$ref: '#/components/parameters/IdempotencyKey'}
        - {$ref: '#/components/parameters/InboundIds'}
        - {name: expectedVersion, in: query, required: true, schema: {type: integer, minimum: 1}}
      requestBody: {$ref: '#/components/requestBodies/FileBody'}
      responses: {'200': {$ref: '#/components/responses/DocumentResponse'}}
  /api/merchant/v1/customs/documents/{documentId}/inbounds:
    put:
      summary: 报关开始前修改资料关联的同柜退税入仓码
      x-permission: merchant:order:edit
      parameters: [{$ref: '#/components/parameters/DocumentId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ScopeRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/DocumentResponse'}}
  /api/merchant/v1/customs/documents/{documentId}:
    delete:
      summary: 报关开始前逻辑删除误传资料并保留不可变版本
      x-permission: merchant:order:edit
      parameters:
        - {$ref: '#/components/parameters/DocumentId'}
        - {$ref: '#/components/parameters/IdempotencyKey'}
        - {name: expectedVersion, in: query, required: true, schema: {type: integer, minimum: 1}}
      responses: {'200': {$ref: '#/components/responses/ContainerResponse'}}
  /api/merchant/v1/customs/documents/{documentId}/download:
    get:
      summary: 客户下载自己当前报送资料
      x-permission: merchant:order:view
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
  /api/merchant/v1/customs/documents/{documentId}/completion/download:
    get:
      summary: 整柜完成后客户下载对应完成文件
      x-permission: merchant:order:view
      parameters: [{$ref: '#/components/parameters/DocumentId'}]
      responses: {'200': {$ref: '#/components/responses/BinaryResponse'}}
  /internal/exports/v1/LOADING_LIST_BUY_DECLARATION_ITEMS/batches:
    post:
      summary: File导出中心按loadingPlanId分页获取已完成装柜买单实际行
      parameters: [{name: X-Internal-Service-Token, in: header, required: true, schema: {type: string}}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ExportBatchRequest'}}}}
      responses: {'200': {description: 成功, content: {application/json: {schema: {$ref: '#/components/schemas/ExportBatchEnvelope'}}}}}
components:
  parameters:
    PlanId: {name: planId, in: path, required: true, schema: {$ref: '#/components/schemas/LongId'}}
    OrderId: {name: orderId, in: path, required: true, schema: {$ref: '#/components/schemas/LongId'}}
    DocumentId: {name: documentId, in: path, required: true, schema: {$ref: '#/components/schemas/LongId'}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
    InboundIds: {name: inboundIds, in: query, required: true, schema: {type: array, minItems: 1, maxItems: 200, items: {$ref: '#/components/schemas/LongId'}}}
  requestBodies:
    ActionBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
    FileBody: {required: true, content: {multipart/form-data: {schema: {type: object, required: [file], properties: {file: {type: string, format: binary, description: 任意格式且最大50MB}}}}}}
  responses:
    ContainerResponse: {description: 成功或业务失败, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerEnvelope'}}}}
    DocumentResponse: {description: 成功或业务失败, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentEnvelope'}}}}
    BinaryResponse: {description: 文件二进制, headers: {Content-Disposition: {schema: {type: string}}, Cache-Control: {schema: {type: string, example: no-store}}}, content: {application/octet-stream: {schema: {type: string, format: binary}}}}
  schemas:
    LongId: {type: string, pattern: '^[1-9][0-9]*$', description: Long ID序列化为字符串}
    ApiEnvelope: {type: object, required: [code, message, timestamp], properties: {code: {type: string}, message: {type: string}, requestId: {type: string, nullable: true}, traceId: {type: string, nullable: true}, timestamp: {type: string, format: date-time}}}
    ContainerEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {$ref: '#/components/schemas/ContainerView'}}}]}
    DocumentEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {$ref: '#/components/schemas/DocumentView'}}}]}
    ActionRequest: {type: object, required: [expectedVersion, confirm], additionalProperties: false, properties: {expectedVersion: {type: integer, minimum: 0}, confirm: {type: boolean}, remark: {type: string, maxLength: 500, nullable: true}}}
    ScopeRequest: {type: object, required: [inboundIds, expectedVersion], additionalProperties: false, properties: {inboundIds: {type: array, minItems: 1, maxItems: 200, items: {$ref: '#/components/schemas/LongId'}}, expectedVersion: {type: integer, minimum: 1}}}
    FileView: {type: object, required: [fileId, fileName, fileHash, sizeBytes, version, uploadedAt], properties: {fileId: {$ref: '#/components/schemas/LongId'}, fileName: {type: string}, fileHash: {type: string}, contentType: {type: string, nullable: true}, sizeBytes: {type: integer, format: int64}, version: {type: integer}, uploadedAt: {type: string, format: date-time}}}
    InboundView: {type: object, required: [inboundId, orderId, orderNo, inboundCode, tenantId, customerName, taxMode, covered], properties: {inboundId: {$ref: '#/components/schemas/LongId'}, orderId: {$ref: '#/components/schemas/LongId'}, orderNo: {type: string}, inboundCode: {type: string}, tenantId: {$ref: '#/components/schemas/LongId'}, customerName: {type: string}, taxMode: {type: string, enum: [TAX_REFUND, BUY_DECLARATION]}, covered: {type: boolean}}}
    DocumentView: {type: object, required: [documentId, tenantId, source, inboundIds, inboundCodes, frozen], properties: {documentId: {$ref: '#/components/schemas/LongId'}, tenantId: {$ref: '#/components/schemas/LongId'}, source: {$ref: '#/components/schemas/FileView'}, inboundIds: {type: array, items: {$ref: '#/components/schemas/LongId'}}, inboundCodes: {type: array, items: {type: string}}, frozen: {type: boolean}, completion: {allOf: [{$ref: '#/components/schemas/FileView'}], nullable: true}}}
    ContainerView: {type: object, required: [aggregateId, loadingPlanId, containerBookingId, status, version, taxRefundCount, coveredTaxRefundCount, inbounds, documents], properties: {aggregateId: {$ref: '#/components/schemas/LongId'}, loadingPlanId: {$ref: '#/components/schemas/LongId'}, containerBookingId: {$ref: '#/components/schemas/LongId'}, planNo: {type: string}, cabinetNo: {type: string}, containerNo: {type: string, nullable: true}, status: {type: string, enum: [WAITING_CUSTOMER_DOCUMENTS, READY_TO_START, DECLARING, COMPLETED]}, merchantStatus: {type: string, enum: [WAITING_UPLOAD, DOCUMENT_UPLOADED, DECLARING, CUSTOMS_COMPLETED], nullable: true}, version: {type: integer}, taxRefundCount: {type: integer}, coveredTaxRefundCount: {type: integer}, inbounds: {type: array, items: {$ref: '#/components/schemas/InboundView'}}, documents: {type: array, items: {$ref: '#/components/schemas/DocumentView'}}, startedAt: {type: string, format: date-time, nullable: true}, completedAt: {type: string, format: date-time, nullable: true}}}
    ExportBatchRequest: {type: object, required: [taskId, tenantId, appCode, requestedBy, dispatchVersion, parameters, limit], properties: {taskId: {type: string}, tenantId: {type: string, enum: ['0']}, appCode: {type: string, enum: [PLATFORM]}, requestedBy: {type: string}, dispatchVersion: {type: integer}, parameters: {type: object, required: [loadingPlanId], additionalProperties: false, properties: {loadingPlanId: {type: string}}}, cursor: {type: string, nullable: true}, snapshotToken: {type: string, nullable: true}, limit: {type: integer, minimum: 1, maximum: 500}}}
    ExportBatchEnvelope: {allOf: [{$ref: '#/components/schemas/ApiEnvelope'}, {type: object, properties: {data: {type: object, properties: {schemaVersion: {type: integer}, schemaHash: {type: string}, snapshotToken: {type: string}, columns: {type: array, items: {type: object}}, rows: {type: array, items: {type: object}}, nextCursor: {type: string}, hasMore: {type: boolean}, totalRows: {type: integer, format: int64, nullable: true}}}}}]}