128 lines
6.4 KiB
YAML
128 lines
6.4 KiB
YAML
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.
|
|
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:
|
|
get:
|
|
summary: Page customs cases
|
|
responses: {'200': {description: Page result}}
|
|
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'}]
|
|
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}}
|
|
/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:
|
|
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:
|
|
get:
|
|
summary: Download only CUSTOMER-visible receipts from the authenticated customer's case
|
|
responses: {'200': {description: Authorized file stream}}
|
|
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]*$'}
|
|
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}
|