openapi: 3.0.1
info:
  title: Vasion Output Cloud Link API
  version: v1.0.1
  description: Submit print jobs and manage batches.
  contact:
    name: PrinterLogic Support
    url: https://vasion.com/technical-support/
    email: support@printerlogic.com
servers:
  - url: https://external-api.app.printercloud.com
  - url: https://external-api.app.printercloud5.com
  - url: https://external-api.app.printercloud6.com
  - url: https://external-api.app.printercloud10.com
  - url: https://external-api.app.printercloud15.com
  - url: https://external-api.app.printercloud20.com
  - url: https://external-api.app.printercloudnow.com
tags:
  - name: Jobs
    description: Print job submission
  - name: Batch
    description: Batch management

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or OAuth2 access token passed as a Bearer token.

  schemas:
    BatchOpenRequest:
      type: object
      required:
        - batchID
        - jobIDs
      properties:
        batchID:
          type: string
          pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          description: UUID for this batch.
          example: 96e31686-daae-4820-9389-5a9d36496bad
        jobIDs:
          type: array
          items:
            type: string
            pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          description: Job UUIDs that belong to this batch.
          example:
            - "96e31686-daae-4820-9389-5a9d36496ba1"
            - "96e31686-daae-4820-9389-5a9d36496bc2"
        requireAllJobs:
          type: boolean
          default: false
          description: When `true`, the batch cannot be closed until all listed jobs have been submitted.
          example: false
        name:
          type: string
          description: Optional display name for the batch.
          example: Monthly Report Batch

    BatchOpenResponse:
      type: object
      properties:
        batchID:
          type: string
          example: 96e31686-daae-4820-9389-5a9d36496bad
        jobIDs:
          type: array
          items:
            type: string
          example:
            - "96e31686-daae-4820-9389-5a9d36496ba1"
            - "96e31686-daae-4820-9389-5a9d36496bc2"
        createdTime:
          type: string
          format: date-time
          example: "2024-01-12T03:25:36.229752Z"
        name:
          type: string
          example: Monthly Report Batch

    BatchCloseRequest:
      type: object
      required:
        - batchID
      properties:
        batchID:
          type: string
          pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
          description: UUID of the batch to close.
          example: 96e31686-daae-4820-9389-5a9d36496bad

paths:
  /v1/print:
    post:
      operationId: submitPrintJob
      tags:
        - Jobs
      summary: Submit a print job
      description: >-
        Queues a document for printing. Returns a job ID that can be used to
        track status.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - queue
                - copies
                - username
              properties:
                file:
                  type: string
                  format: binary
                  description: The document to print.
                queue:
                  type: string
                  description: Printer name.
                  example: HP127
                copies:
                  type: integer
                  minimum: 1
                  default: 1
                  description: Number of copies. Must be ≥ 1.
                  example: 1
                username:
                  type: string
                  description: >-
                    User submitting the job. Accepts email (`john@example.com`)
                    or domain account (`DOMAIN\john`).
                  example: john@example.com
                jobID:
                  type: string
                  pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
                  description: Optional pre-assigned job UUID. Generated if not provided.
                  example: 96e31686-daae-4820-9389-5a9d36496bad
                deviceName:
                  type: string
                  description: Name of the originating device.
                  example: m123.local
                duplex:
                  type: integer
                  minimum: 0
                  maximum: 3
                  default: 0
                  description: >-
                    `0` = printer default, `1` = simplex, `2` = duplex long-edge,
                    `3` = duplex short-edge.
                  example: 0
                color:
                  type: boolean
                  default: true
                  description: "`true` = color, `false` = black and white."
                  example: true
                paperSource:
                  type: string
                  description: Paper source tray code.
                  example: "1"
                paperSize:
                  type: string
                  description: Paper size (e.g. `LETTER`, `A4`).
                  example: A4
                orientation:
                  type: string
                  description: Print orientation (e.g. `portrait`, `landscape`).
                  example: portrait
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobID:
                    type: string
                    example: ac6bce59-ccfb-45d5-a939-09da12b8eebc
                  warnings:
                    type: array
                    items:
                      type: string
              examples:
                Success:
                  value:
                    jobID: ac6bce59-ccfb-45d5-a939-09da12b8eebc
                SuccessWithWarnings:
                  value:
                    jobID: ac6bce59-ccfb-45d5-a939-09da12b8eebc
                    warnings:
                      - Unknown custom field received
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error

  /v1/batch/open:
    post:
      operationId: openBatch
      tags:
        - Batch
      summary: Open a batch
      description: >-
        Creates a batch and associates a set of job IDs with it.
        Jobs in a batch are released together when the batch is closed.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchOpenRequest"
            examples:
              Minimal:
                value:
                  batchID: 96e31686-daae-4820-9389-5a9d36496bad
                  jobIDs:
                    - "96e31686-daae-4820-9389-5a9d36496ba1"
                    - "96e31686-daae-4820-9389-5a9d36496bc2"
              WithOptions:
                value:
                  batchID: 96e31686-daae-4820-9389-5a9d36496bad
                  jobIDs:
                    - "96e31686-daae-4820-9389-5a9d36496ba1"
                    - "96e31686-daae-4820-9389-5a9d36496bc2"
                  requireAllJobs: true
                  name: Monthly Report Batch
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchOpenResponse"
              example:
                batchID: 96e31686-daae-4820-9389-5a9d36496bad
                jobIDs:
                  - "96e31686-daae-4820-9389-5a9d36496ba1"
                  - "96e31686-daae-4820-9389-5a9d36496bc2"
                createdTime: "2024-01-12T03:25:36.229752Z"
                name: Monthly Report Batch
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error

  /v1/batch/close:
    post:
      operationId: closeBatch
      tags:
        - Batch
      summary: Close a batch
      description: Closes an open batch and releases all eligible jobs within it.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchCloseRequest"
            example:
              batchID: 96e31686-daae-4820-9389-5a9d36496bad
      responses:
        "202":
          description: Accepted
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error