baiyue-firstleg/print/src/main/resources/openapi/print-internal-v1.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/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]+$'
    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
        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
      properties:
        fields:
          type: object
          additionalProperties:
            type: string
            maxLength: 4000
          description: Template field map. Known keys are documented in the print module README.
        cargoRows:
          type: array
          maxItems: 1
          description: V1 templates render at most one cargo row. Callers must not send additional rows.
          items:
            $ref: '#/components/schemas/FreightA4CargoRow'
    FreightA4CargoRow:
      type: object
      properties:
        marksAndNos:
          type: string
        quantity:
          type: string
        packaging:
          type: string
        descriptionOfGoods:
          type: string
        grossWeight:
          type: string
        measurement:
          type: string
    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