526 lines
22 KiB
YAML
526 lines
22 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Baiyue Print Internal API
|
|
version: 1.0.0
|
|
description: Internal stateless PDF rendering API. This path must not be exposed through Gateway.
|
|
paths:
|
|
/internal/print/v1/pdfs/pallet-a4-labels:
|
|
post:
|
|
summary: Generate non-FBA pallet labels as landscape A4 pages
|
|
operationId: generatePalletA4Labels
|
|
security: [{ internalServiceToken: [] }]
|
|
parameters: [{ $ref: '#/components/parameters/RequestId' }]
|
|
requestBody:
|
|
required: true
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/GenericPalletPdfRequest' } } }
|
|
responses:
|
|
'200':
|
|
description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
|
|
content:
|
|
application/pdf: { schema: { type: string, format: binary } }
|
|
application/json: { schema: { $ref: '#/components/schemas/ApiError' } }
|
|
'413':
|
|
description: Request body exceeds the configured limit.
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/ApiError' } } }
|
|
/internal/print/v1/pdfs/fba-pallet-labels:
|
|
post:
|
|
summary: Generate shared domestic and overseas FBA pallet labels as landscape A4 pages
|
|
operationId: generateFbaPalletLabels
|
|
description: One label per page in input order. The destination is the FBA code such as SCK8; the stored pallet code (including internal warehouse number such as 141) is printed verbatim and encoded as Code 128. No business lookup or new numbering.
|
|
security: [{ internalServiceToken: [] }]
|
|
parameters: [{ $ref: '#/components/parameters/RequestId' }]
|
|
requestBody:
|
|
required: true
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/FbaPalletPdfRequest' } } }
|
|
responses:
|
|
'200':
|
|
description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
|
|
headers:
|
|
Content-Disposition: { schema: { type: string } }
|
|
Cache-Control: { schema: { type: string, example: no-store } }
|
|
X-Print-Page-Count: { schema: { type: integer, minimum: 1, maximum: 2000 } }
|
|
content:
|
|
application/pdf: { schema: { type: string, format: binary } }
|
|
application/json: { schema: { $ref: '#/components/schemas/ApiError' } }
|
|
'413':
|
|
description: Request body exceeds the configured limit.
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/ApiError' } } }
|
|
/internal/print/v1/pdfs/inbound-marks:
|
|
post:
|
|
summary: Generate an inbound-mark PDF
|
|
operationId: generateInboundMarkPdf
|
|
security:
|
|
- internalServiceToken: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/RequestId'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InboundMarkPdfRequest'
|
|
responses:
|
|
'200':
|
|
description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
|
|
headers:
|
|
Content-Disposition:
|
|
description: UTF-8 attachment filename. Present only for a successful PDF.
|
|
schema:
|
|
type: string
|
|
Cache-Control:
|
|
schema:
|
|
type: string
|
|
example: no-store
|
|
X-Print-Page-Count:
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 2000
|
|
X-Request-Id:
|
|
schema:
|
|
type: string
|
|
content:
|
|
application/pdf:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'413':
|
|
description: Request body exceeds the configured limit.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
/internal/print/v1/pdfs/freight-a4-documents:
|
|
post:
|
|
summary: Generate an A4 sea-freight document PDF
|
|
operationId: generateFreightA4DocumentPdf
|
|
security:
|
|
- internalServiceToken: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/RequestId'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FreightA4PdfRequest'
|
|
responses:
|
|
'200':
|
|
description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
|
|
headers:
|
|
Content-Disposition:
|
|
description: UTF-8 attachment filename. Present only for a successful PDF.
|
|
schema:
|
|
type: string
|
|
Cache-Control:
|
|
schema:
|
|
type: string
|
|
example: no-store
|
|
X-Print-Page-Count:
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 2000
|
|
X-Request-Id:
|
|
schema:
|
|
type: string
|
|
content:
|
|
application/pdf:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
'413':
|
|
description: Request body exceeds the configured limit.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiError'
|
|
/internal/print/v1/pdfs/dispatch-bol-documents:
|
|
post:
|
|
summary: Generate vehicle-dispatch BOL documents as fixed A4 PDF pages
|
|
operationId: generateDispatchBolPdf
|
|
security: [{ internalServiceToken: [] }]
|
|
parameters: [{ $ref: '#/components/parameters/RequestId' }]
|
|
requestBody:
|
|
required: true
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/DispatchBolPdfRequest' } } }
|
|
responses:
|
|
'200':
|
|
description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
|
|
headers:
|
|
Content-Disposition: { schema: { type: string } }
|
|
X-Print-Page-Count: { schema: { type: integer, minimum: 1, maximum: 2000 } }
|
|
content:
|
|
application/pdf: { schema: { type: string, format: binary } }
|
|
application/json: { schema: { $ref: '#/components/schemas/ApiError' } }
|
|
/internal/print/v1/pdfs/dropship-pallet-a4-documents:
|
|
post:
|
|
summary: Generate one A4 information sheet per dropship pallet
|
|
operationId: generateDropshipPalletA4Pdf
|
|
security: [{ internalServiceToken: [] }]
|
|
parameters: [{ $ref: '#/components/parameters/RequestId' }]
|
|
requestBody:
|
|
required: true
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/DropshipPalletA4PdfRequest' } } }
|
|
responses:
|
|
'200':
|
|
description: PDF generation succeeded, or a business error was returned as ApiResponse JSON.
|
|
headers:
|
|
Content-Disposition: { schema: { type: string } }
|
|
X-Print-Page-Count: { schema: { type: integer, minimum: 1, maximum: 2000 } }
|
|
content:
|
|
application/pdf: { schema: { type: string, format: binary } }
|
|
application/json: { schema: { $ref: '#/components/schemas/ApiError' } }
|
|
'413':
|
|
description: Request body exceeds the configured limit.
|
|
content: { application/json: { schema: { $ref: '#/components/schemas/ApiError' } } }
|
|
components:
|
|
securitySchemes:
|
|
internalServiceToken:
|
|
type: apiKey
|
|
in: header
|
|
name: X-Internal-Service-Token
|
|
parameters:
|
|
RequestId:
|
|
name: X-Request-Id
|
|
in: header
|
|
required: false
|
|
schema:
|
|
type: string
|
|
schemas:
|
|
GenericPalletPdfRequest:
|
|
type: object
|
|
required: [templateCode, pageSpec, downloadFileName, labels]
|
|
properties:
|
|
templateCode: { type: string, enum: [PALLET_A4_LANDSCAPE_V1] }
|
|
pageSpec:
|
|
type: object
|
|
required: [widthMm, heightMm]
|
|
properties:
|
|
widthMm: { type: number, enum: [297] }
|
|
heightMm: { type: number, enum: [210] }
|
|
downloadFileName: { type: string, minLength: 4, maxLength: 120 }
|
|
labels:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 2000
|
|
items:
|
|
type: object
|
|
required: [heading, reference, palletCode]
|
|
properties:
|
|
heading: { type: string, minLength: 1, maxLength: 80 }
|
|
reference: { type: string, minLength: 1, maxLength: 80 }
|
|
palletCode: { type: string, minLength: 1, maxLength: 80, pattern: '^[\x20-\x7E]+$' }
|
|
FbaPalletPdfRequest:
|
|
type: object
|
|
required: [templateCode, pageSpec, downloadFileName, labels]
|
|
properties:
|
|
templateCode: { type: string, enum: [FBA_PALLET_A4_LANDSCAPE_V1] }
|
|
pageSpec:
|
|
type: object
|
|
required: [widthMm, heightMm]
|
|
properties:
|
|
widthMm: { type: number, enum: [297] }
|
|
heightMm: { type: number, enum: [210] }
|
|
downloadFileName: { type: string, minLength: 4, maxLength: 120, description: PDF filename without path separators or control characters }
|
|
labels:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 2000
|
|
items:
|
|
type: object
|
|
required: [fbaWarehouseCode, palletCode]
|
|
properties:
|
|
fbaWarehouseCode: { type: string, pattern: '^[A-Z0-9][A-Z0-9-]{0,31}$', example: SCK8 }
|
|
palletCode: { type: string, minLength: 1, maxLength: 80, description: Printable ASCII with no surrounding spaces; unchanged text and Code 128 payload, example: MSCU6639870-141-001 }
|
|
InboundMarkPdfRequest:
|
|
type: object
|
|
required: [templateCode, pageSpec, labels]
|
|
properties:
|
|
templateCode:
|
|
type: string
|
|
enum: [INBOUND_MARK_V1]
|
|
pageSpec:
|
|
$ref: '#/components/schemas/PageSpec'
|
|
downloadFileName:
|
|
type: string
|
|
maxLength: 120
|
|
example: PCHK2608040174-19件-MCC1.pdf
|
|
labels:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 2000
|
|
items:
|
|
$ref: '#/components/schemas/InboundMarkLabel'
|
|
PageSpec:
|
|
type: object
|
|
required: [widthMm, heightMm]
|
|
properties:
|
|
widthMm:
|
|
type: number
|
|
enum: [100]
|
|
heightMm:
|
|
type: number
|
|
enum: [100]
|
|
InboundMarkLabel:
|
|
type: object
|
|
description: 箱唛仅展示入仓码、仓库、箱序、线路、稳定箱码二维码及产地，不包含 SKU；SKU 明细由一件代发 A4 托盘信息单展示。
|
|
required: [topCode, warehouseText, cartonText, routeText, qrContent]
|
|
properties:
|
|
topCode:
|
|
type: string
|
|
warehouseText:
|
|
type: string
|
|
cartonText:
|
|
type: string
|
|
routeText:
|
|
type: string
|
|
qrContent:
|
|
type: string
|
|
minLength: 1
|
|
maxLength: 34
|
|
pattern: '^[\\x20-\\x7E]+$'
|
|
FreightA4PdfRequest:
|
|
type: object
|
|
required: [templateCode, pageSpec, documents]
|
|
properties:
|
|
templateCode:
|
|
type: string
|
|
enum: [SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1, BILL_OF_LADING_CONFIRMATION_A4_V1]
|
|
pageSpec:
|
|
$ref: '#/components/schemas/FreightA4PageSpec'
|
|
downloadFileName:
|
|
type: string
|
|
maxLength: 120
|
|
example: BYSE2607044-托运书.pdf
|
|
description: 未传时托运书为{jobNumber}-出口货物托运单.pdf，提单确认件为{bookingNumber}-提单确认件.pdf
|
|
documents:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 2000
|
|
description: One document item renders one A4 page in request order.
|
|
items:
|
|
$ref: '#/components/schemas/FreightA4Document'
|
|
DispatchBolPdfRequest:
|
|
type: object
|
|
required: [templateCode, pageSpec, downloadFileName, documents]
|
|
properties:
|
|
templateCode: { type: string, enum: [DISPATCH_BILL_OF_LADING_A4_V2] }
|
|
pageSpec: { $ref: '#/components/schemas/FreightA4PageSpec' }
|
|
downloadFileName: { type: string, maxLength: 120 }
|
|
documents:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 2000
|
|
description: One item renders one A4 page; the caller groups and chunks BOL rows in stable order.
|
|
items: { $ref: '#/components/schemas/DispatchBolDocument' }
|
|
DispatchBolDocument:
|
|
type: object
|
|
required: [shipFromName, carrierName, fbaWarehouseCode, shipToName, dispatchNo, totalPackages, pageNumber, pageCount, cargoRows]
|
|
properties:
|
|
shipFromName: { type: string }
|
|
shipFromAddress: { type: string }
|
|
carrierName: { type: string }
|
|
isaNumber: { type: string }
|
|
appointmentTime: { type: string }
|
|
trailerNumber: { type: string }
|
|
sealNumber: { type: string }
|
|
fbaWarehouseCode: { type: string }
|
|
shipToName: { type: string }
|
|
shipToAddress: { type: string }
|
|
dispatchNo: { type: string }
|
|
fbaShipmentIds: { type: string }
|
|
poReferenceNos: { type: string }
|
|
totalPackages: { type: integer, minimum: 0 }
|
|
pageNumber: { type: integer, minimum: 1 }
|
|
pageCount: { type: integer, minimum: 1 }
|
|
cargoRows:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 26
|
|
description: First page accepts at most 18 rows; continuation pages accept at most 26 rows.
|
|
items: { $ref: '#/components/schemas/DispatchBolCargoRow' }
|
|
DispatchBolCargoRow:
|
|
type: object
|
|
required: [containerNo, palletNo, fbaWarehouseCode, warehouseNo, fbaShipmentId, poReferenceNo, packageCount]
|
|
properties:
|
|
containerNo: { type: string }
|
|
palletNo: { type: string }
|
|
fbaWarehouseCode: { type: string }
|
|
warehouseNo: { type: string }
|
|
fbaShipmentId: { type: string }
|
|
poReferenceNo: { type: string }
|
|
packageCount: { type: integer, minimum: 0 }
|
|
DropshipPalletA4PdfRequest:
|
|
type: object
|
|
required: [templateCode, pageSpec, downloadFileName, documents]
|
|
properties:
|
|
templateCode: { type: string, enum: [DROPSHIP_PALLET_A4_V2] }
|
|
pageSpec: { $ref: '#/components/schemas/FreightA4PageSpec' }
|
|
downloadFileName: { type: string, maxLength: 120 }
|
|
documents:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 2000
|
|
description: One pallet renders as exactly one A4 page in request order.
|
|
items: { $ref: '#/components/schemas/DropshipPalletA4Document' }
|
|
DropshipPalletA4Document:
|
|
type: object
|
|
required: [palletNo, destinationWarehouse, barcodeContent, inboundRows, skuRows]
|
|
properties:
|
|
palletNo: { type: string, maxLength: 80 }
|
|
destinationWarehouse: { type: string, maxLength: 200 }
|
|
barcodeContent:
|
|
type: string
|
|
maxLength: 80
|
|
pattern: '^[\\x20-\\x7E]+$'
|
|
description: Code 128 一维码内容，当前固定为稳定托盘码
|
|
inboundRows:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 10
|
|
items: { $ref: '#/components/schemas/DropshipPalletInboundRow' }
|
|
skuRows:
|
|
type: array
|
|
minItems: 0
|
|
maxItems: 34
|
|
items: { $ref: '#/components/schemas/DropshipPalletSkuRow' }
|
|
DropshipPalletInboundRow:
|
|
type: object
|
|
required: [inboundCode, customerNickname, cartonCount, itemQuantity]
|
|
properties:
|
|
inboundCode: { type: string, maxLength: 80 }
|
|
customerNickname: { type: string, maxLength: 80 }
|
|
cartonCount: { type: integer, minimum: 0 }
|
|
itemQuantity: { type: integer, minimum: 0 }
|
|
DropshipPalletSkuRow:
|
|
type: object
|
|
required: [skuCode, cartonCount, itemQuantity, unitsPerCarton]
|
|
properties:
|
|
skuCode: { type: string, maxLength: 128 }
|
|
cartonCount: { type: integer, minimum: 0 }
|
|
itemQuantity: { type: integer, minimum: 0 }
|
|
unitsPerCarton: { type: string, maxLength: 30 }
|
|
FreightA4PageSpec:
|
|
type: object
|
|
required: [widthMm, heightMm]
|
|
properties:
|
|
widthMm:
|
|
type: number
|
|
enum: [210]
|
|
heightMm:
|
|
type: number
|
|
enum: [297]
|
|
FreightA4Document:
|
|
type: object
|
|
required: [fields, cargoRows]
|
|
x-template-contracts:
|
|
SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1:
|
|
required: [toCompany, shipper, consignee, notifyParty, jobNumber, cargoQuantity, portOfLoading, portOfDischarge, placeOfDelivery, totalPackagesInWords]
|
|
optional: [issuerNameCn, issuerNameEn, issuerAddress, issuerPostalCode, issuerTel, issuerFax, picName, picTel, picFax, documentName, documentTel, documentFax, etdDate, serviceTerm, freightTerm, apCode, apName, transshipment, partialShipment, oceanVesselVoyage, remark, carrier, bookingAgent, printDate]
|
|
BILL_OF_LADING_CONFIRMATION_A4_V1:
|
|
required: [shipper, consignee, notifyParty, bookingNumber, portOfLoading, portOfDischarge, placeOfDelivery, serviceTerm, freightTerm, totalPackagesInWords]
|
|
optional: [ensAmsCutoffDate, customsCutoffDate, expectedDepartureDate, oceanVesselVoyage, finalDestination, shipperLoadCountSeal, containerSpec, shippedOnBoard, draftText, containerSummary, notes, issuePlace, issueDate]
|
|
properties:
|
|
fields:
|
|
type: object
|
|
additionalProperties: false
|
|
description: 只能提交所选模板登记的键；未知键和缺少必填键返回A0422。
|
|
properties:
|
|
toCompany: {$ref: '#/components/schemas/FreightField'}
|
|
issuerNameCn: {$ref: '#/components/schemas/FreightField'}
|
|
issuerNameEn: {$ref: '#/components/schemas/FreightField'}
|
|
issuerAddress: {$ref: '#/components/schemas/FreightField'}
|
|
issuerPostalCode: {$ref: '#/components/schemas/FreightField'}
|
|
issuerTel: {$ref: '#/components/schemas/FreightField'}
|
|
issuerFax: {$ref: '#/components/schemas/FreightField'}
|
|
shipper: {$ref: '#/components/schemas/FreightField'}
|
|
consignee: {$ref: '#/components/schemas/FreightField'}
|
|
notifyParty: {$ref: '#/components/schemas/FreightField'}
|
|
picName: {$ref: '#/components/schemas/FreightField'}
|
|
picTel: {$ref: '#/components/schemas/FreightField'}
|
|
picFax: {$ref: '#/components/schemas/FreightField'}
|
|
documentName: {$ref: '#/components/schemas/FreightField'}
|
|
documentTel: {$ref: '#/components/schemas/FreightField'}
|
|
documentFax: {$ref: '#/components/schemas/FreightField'}
|
|
jobNumber: {$ref: '#/components/schemas/FreightField'}
|
|
etdDate: {$ref: '#/components/schemas/FreightField'}
|
|
serviceTerm: {$ref: '#/components/schemas/FreightField'}
|
|
freightTerm: {$ref: '#/components/schemas/FreightField'}
|
|
apCode: {$ref: '#/components/schemas/FreightField'}
|
|
apName: {$ref: '#/components/schemas/FreightField'}
|
|
cargoQuantity: {$ref: '#/components/schemas/FreightField'}
|
|
transshipment: {$ref: '#/components/schemas/FreightField'}
|
|
partialShipment: {$ref: '#/components/schemas/FreightField'}
|
|
oceanVesselVoyage: {$ref: '#/components/schemas/FreightField'}
|
|
portOfLoading: {$ref: '#/components/schemas/FreightField'}
|
|
portOfDischarge: {$ref: '#/components/schemas/FreightField'}
|
|
placeOfDelivery: {$ref: '#/components/schemas/FreightField'}
|
|
totalPackagesInWords: {$ref: '#/components/schemas/FreightField'}
|
|
remark: {$ref: '#/components/schemas/FreightField'}
|
|
carrier: {$ref: '#/components/schemas/FreightField'}
|
|
bookingAgent: {$ref: '#/components/schemas/FreightField'}
|
|
printDate: {$ref: '#/components/schemas/FreightField'}
|
|
bookingNumber: {$ref: '#/components/schemas/FreightField'}
|
|
ensAmsCutoffDate: {$ref: '#/components/schemas/FreightField'}
|
|
customsCutoffDate: {$ref: '#/components/schemas/FreightField'}
|
|
expectedDepartureDate: {$ref: '#/components/schemas/FreightField'}
|
|
finalDestination: {$ref: '#/components/schemas/FreightField'}
|
|
shipperLoadCountSeal: {$ref: '#/components/schemas/FreightField'}
|
|
containerSpec: {$ref: '#/components/schemas/FreightField'}
|
|
shippedOnBoard: {$ref: '#/components/schemas/FreightField'}
|
|
draftText: {$ref: '#/components/schemas/FreightField'}
|
|
containerSummary: {$ref: '#/components/schemas/FreightField'}
|
|
notes: {$ref: '#/components/schemas/FreightField'}
|
|
issuePlace: {$ref: '#/components/schemas/FreightField'}
|
|
issueDate: {$ref: '#/components/schemas/FreightField'}
|
|
cargoRows:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 1
|
|
description: V1模板固定恰好一行货物，六个字段均必填且非空。
|
|
items:
|
|
$ref: '#/components/schemas/FreightA4CargoRow'
|
|
FreightA4CargoRow:
|
|
type: object
|
|
required: [marksAndNos, quantity, packaging, descriptionOfGoods, grossWeight, measurement]
|
|
properties:
|
|
marksAndNos:
|
|
type: string
|
|
quantity:
|
|
type: string
|
|
packaging:
|
|
type: string
|
|
descriptionOfGoods:
|
|
type: string
|
|
grossWeight:
|
|
type: string
|
|
measurement:
|
|
type: string
|
|
FreightField:
|
|
type: string
|
|
maxLength: 4000
|
|
ApiError:
|
|
type: object
|
|
required: [code, message]
|
|
properties:
|
|
code:
|
|
type: string
|
|
enum: [A0400, A0403, A0422, A0429, S0500]
|
|
message:
|
|
type: string
|
|
data:
|
|
nullable: true
|
|
requestId:
|
|
type: string
|
|
nullable: true
|
|
traceId:
|
|
type: string
|
|
nullable: true
|