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/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'
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:
    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
      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]+$'
        skuCode:
          type: string
          maxLength: 64
          nullable: true
          description: 一件代发箱唛显示的 SKU；二维码仍只使用 qrContent 稳定箱码
    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'
    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