feat(firstleg): implement container customs workflow
This commit is contained in:
@@ -1,127 +1,135 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Phase 3 Customs Collaboration API
|
||||
version: 1.0.0
|
||||
description: Immutable checklist and file versions, supplement requests, frozen agent batches, receipts and history.
|
||||
info: {title: Firstleg Container Customs API, version: 2.0.0}
|
||||
paths:
|
||||
/api/platform/v1/customs/checklist-versions:
|
||||
post:
|
||||
summary: Create an immutable customs document checklist version
|
||||
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
responses: {'200': {description: Checklist version}}
|
||||
/api/platform/v1/customs/cases:
|
||||
/api/platform/v1/customs/loading-plans/{planId}:
|
||||
get:
|
||||
summary: Page customs cases
|
||||
responses: {'200': {description: Page result}}
|
||||
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: Create a customer/order/inbound/container scoped customs case
|
||||
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
responses: {'200': {description: Customs case detail}}
|
||||
/api/platform/v1/customs/cases/{caseId}:
|
||||
parameters: [{$ref: '#/components/parameters/CaseId'}]
|
||||
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: Query complete customs detail and stable history
|
||||
responses: {'200': {description: Detail}}
|
||||
/api/platform/v1/customs/cases/{caseId}/documents:
|
||||
parameters: [{$ref: '#/components/parameters/CaseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
post:
|
||||
summary: Reference a file validated against customer, CUSTOMS_DOCUMENT and case ID
|
||||
responses: {'200': {description: New document version}}
|
||||
/api/platform/v1/customs/cases/{caseId}/documents/upload:
|
||||
parameters: [{$ref: '#/components/parameters/CaseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
post:
|
||||
summary: Upload a document and create a new immutable version
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
required: [itemCode, expectedVersion, file]
|
||||
properties:
|
||||
itemCode: {type: string}
|
||||
expectedVersion: {type: integer, minimum: 0}
|
||||
file: {type: string, format: binary}
|
||||
responses: {'200': {description: New document version}}
|
||||
/api/platform/v1/customs/cases/{caseId}/documents/{documentId}/review:
|
||||
parameters:
|
||||
- {$ref: '#/components/parameters/CaseId'}
|
||||
- {name: documentId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||||
- {$ref: '#/components/parameters/IdempotencyKey'}
|
||||
post:
|
||||
summary: Approve a current file version or return it with a supplement task
|
||||
responses: {'200': {description: Updated detail}}
|
||||
/api/platform/v1/customs/cases/{caseId}/submission-batches:
|
||||
parameters: [{$ref: '#/components/parameters/CaseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
post:
|
||||
summary: Submit to customs agent and freeze approved file versions in a batch snapshot
|
||||
description: customsAgentId must identify an ACTIVE Warehouse supplier in category CUSTOMS; the persisted agent name is resolved server-side and free text cannot bypass supplier validation.
|
||||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/SubmitBatchRequest'}}}}
|
||||
responses:
|
||||
'200':
|
||||
description: Submission batch
|
||||
content:
|
||||
application/json:
|
||||
schema: {$ref: '#/components/schemas/CustomsSubmissionBatch'}
|
||||
/api/platform/v1/customs/submission-batches/{batchId}/receipts:
|
||||
parameters:
|
||||
- {name: batchId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
||||
- {$ref: '#/components/parameters/IdempotencyKey'}
|
||||
post:
|
||||
summary: Reference a customer-owned receipt file with explicit visibility
|
||||
responses: {'200': {description: Receipt version}}
|
||||
/api/platform/v1/customs/submission-batches/{batchId}/receipts/upload:
|
||||
post:
|
||||
summary: Upload a receipt version; RELEASED closes the customs dispatch gate
|
||||
responses: {'200': {description: Receipt version}}
|
||||
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: Query the authenticated customer's customs case by order
|
||||
responses: {'200': {description: Customer-filtered detail}}
|
||||
/api/merchant/v1/customs/cases/{caseId}/documents/upload:
|
||||
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: Upload or replace a checklist document within authenticated customer scope
|
||||
responses: {'200': {description: New document version}}
|
||||
/api/merchant/v1/customs/cases/{caseId}/receipts/{receiptId}/download:
|
||||
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: Download only CUSTOMER-visible receipts from the authenticated customer's case
|
||||
responses: {'200': {description: Authorized file stream}}
|
||||
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:
|
||||
IdempotencyKey:
|
||||
name: Idempotency-Key
|
||||
in: header
|
||||
required: true
|
||||
schema: {type: string, minLength: 1, maxLength: 128}
|
||||
CaseId:
|
||||
name: caseId
|
||||
in: path
|
||||
required: true
|
||||
schema: {type: string, pattern: '^[1-9][0-9]*$'}
|
||||
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:
|
||||
SubmitBatchRequest:
|
||||
type: object
|
||||
required: [customsAgentId, expectedVersion]
|
||||
properties:
|
||||
customsAgentId: {type: integer, format: int64, minimum: 1, description: ACTIVE Warehouse supplier ID validated as CUSTOMS.}
|
||||
customsAgentName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint; persisted name always comes from Warehouse.}
|
||||
externalReference: {type: string, maxLength: 128, nullable: true}
|
||||
note: {type: string, maxLength: 500, nullable: true}
|
||||
expectedVersion: {type: integer, minimum: 0}
|
||||
CustomsSubmissionBatch:
|
||||
type: object
|
||||
required: [id, customsCaseId, batchNo, batchVersion, customsAgentName, status, submittedBy, submittedAt]
|
||||
properties:
|
||||
id: {type: string, pattern: '^[1-9][0-9]*$'}
|
||||
customsCaseId: {type: string, pattern: '^[1-9][0-9]*$'}
|
||||
batchNo: {type: string, maxLength: 40}
|
||||
batchVersion: {type: integer, minimum: 1}
|
||||
customsAgentId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: Server-validated CUSTOMS supplier ID snapshot; null only for non-migrated historical rows.}
|
||||
customsAgentName: {type: string, maxLength: 128, description: Server-frozen Warehouse supplier name snapshot.}
|
||||
externalReference: {type: string, maxLength: 128, nullable: true}
|
||||
fileSnapshotJson: {type: string}
|
||||
status: {type: string, enum: [SUBMITTED, ACKNOWLEDGED, REJECTED, COMPLETED]}
|
||||
note: {type: string, maxLength: 500, nullable: true}
|
||||
submittedBy: {type: string, pattern: '^[1-9][0-9]*$'}
|
||||
submittedByName: {type: string, maxLength: 64, nullable: true}
|
||||
submittedAt: {type: string, format: date-time}
|
||||
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}}}}}]}
|
||||
|
||||
Reference in New Issue
Block a user