java-project/baiyue-firstleg
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93e2e8fb4409c3afa009f637a489d1e77c652f96
baiyue-firstleg/print/src/main/resources/openapi/print-internal-v1.yaml
T

526 lines
22 KiB
YAML
Raw Normal View History

打印服务
2026-08-04 18:54:22 +08:00
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:
fix: keep pallet labels on A4 templates
2026-09-20 14:05:00 +08:00
/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' } } }
优化
2026-09-16 15:21:08 +08:00
/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' } } }
打印服务
2026-08-04 18:54:22 +08:00
/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'
优化
2026-08-06 11:49:51 +08:00
/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'
feat: generate dispatch BOL PDFs
2026-09-11 10:09:06 +08:00
/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' } }
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
/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' } } }
打印服务
2026-08-04 18:54:22 +08:00
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:
fix: keep pallet labels on A4 templates
2026-09-20 14:05:00 +08:00
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]+$' }
优化
2026-09-16 15:21:08 +08:00
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 }
打印服务
2026-08-04 18:54:22 +08:00
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
fix(print): remove SKU from carton labels while retaining dropship A4 details
2026-09-20 11:22:29 +08:00
description: 箱唛仅展示入仓码、仓库、箱序、线路、稳定箱码二维码及产地，不包含 SKU；SKU 明细由一件代发 A4 托盘信息单展示。
打印服务
2026-08-04 18:54:22 +08:00
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]+$'
优化
2026-08-06 11:49:51 +08:00
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
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
description: 未传时托运书为{jobNumber}-出口货物托运单.pdf，提单确认件为{bookingNumber}-提单确认件.pdf
优化
2026-08-06 11:49:51 +08:00
documents:
type: array
minItems: 1
maxItems: 2000
description: One document item renders one A4 page in request order.
items:
$ref: '#/components/schemas/FreightA4Document'
feat: generate dispatch BOL PDFs
2026-09-11 10:09:06 +08:00
DispatchBolPdfRequest:
type: object
required: [templateCode, pageSpec, downloadFileName, documents]
properties:
feat: match warehouse BOL print layout
2026-09-11 11:35:37 +08:00
templateCode: { type: string, enum: [DISPATCH_BILL_OF_LADING_A4_V2] }
feat: generate dispatch BOL PDFs
2026-09-11 10:09:06 +08:00
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 }
feat: match warehouse BOL print layout
2026-09-11 11:35:37 +08:00
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' }
feat: generate dispatch BOL PDFs
2026-09-11 10:09:06 +08:00
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 }
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
DropshipPalletA4PdfRequest:
type: object
required: [templateCode, pageSpec, downloadFileName, documents]
properties:
优化
2026-09-14 15:33:29 +08:00
templateCode: { type: string, enum: [DROPSHIP_PALLET_A4_V2] }
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
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
feat: finalize dropship pallet print documents
2026-09-14 17:52:01 +08:00
required: [palletNo, destinationWarehouse, barcodeContent, inboundRows, skuRows]
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
properties:
palletNo: { type: string, maxLength: 80 }
优化
2026-09-14 15:33:29 +08:00
destinationWarehouse: { type: string, maxLength: 200 }
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
barcodeContent:
type: string
maxLength: 80
pattern: '^[\\x20-\\x7E]+$'
description: Code 128 一维码内容，当前固定为稳定托盘码
优化
2026-09-14 15:33:29 +08:00
inboundRows:
type: array
minItems: 1
maxItems: 10
items: { $ref: '#/components/schemas/DropshipPalletInboundRow' }
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
skuRows:
type: array
minItems: 0
maxItems: 34
items: { $ref: '#/components/schemas/DropshipPalletSkuRow' }
优化
2026-09-14 15:33:29 +08:00
DropshipPalletInboundRow:
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
type: object
优化
2026-09-14 15:33:29 +08:00
required: [inboundCode, customerNickname, cartonCount, itemQuantity]
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
properties:
inboundCode: { type: string, maxLength: 80 }
优化
2026-09-14 15:33:29 +08:00
customerNickname: { type: string, maxLength: 80 }
feat: support mixed-SKU dropship cartons
2026-09-11 15:38:19 +08:00
cartonCount: { type: integer, minimum: 0 }
优化
2026-09-14 15:33:29 +08:00
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 }
优化
2026-08-06 11:49:51 +08:00
FreightA4PageSpec:
type: object
required: [widthMm, heightMm]
properties:
widthMm:
type: number
enum: [210]
heightMm:
type: number
enum: [297]
FreightA4Document:
type: object
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
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]
优化
2026-08-06 11:49:51 +08:00
properties:
fields:
type: object
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
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'}
优化
2026-08-06 11:49:51 +08:00
cargoRows:
type: array
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
minItems: 1
优化
2026-08-06 11:49:51 +08:00
maxItems: 1
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
description: V1模板固定恰好一行货物，六个字段均必填且非空。
优化
2026-08-06 11:49:51 +08:00
items:
$ref: '#/components/schemas/FreightA4CargoRow'
FreightA4CargoRow:
type: object
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
required: [marksAndNos, quantity, packaging, descriptionOfGoods, grossWeight, measurement]
优化
2026-08-06 11:49:51 +08:00
properties:
marksAndNos:
type: string
quantity:
type: string
packaging:
type: string
descriptionOfGoods:
type: string
grossWeight:
type: string
measurement:
type: string
feat(file-print): support ocean booking documents
2026-08-31 19:30:37 +08:00
FreightField:
type: string
maxLength: 4000
打印服务
2026-08-04 18:54:22 +08:00
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
Reference in New Issue Copy Permalink