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