openapi: 3.0.3

info:
  title: Vasion Output Print API
  version: 1.0.0
  description: API for submitting print jobs and managing print batches.

servers:
  - url: https://{host}:31990
    variables:
      host:
        default: localhost
        description: Hostname of the Output Management SCS server.

security:
  - basicAuth: []
  - bearerAuth: []
  - {}

components:

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer

  schemas:

    PrintJobResponse:
      type: object
      required:
        - jobID
      properties:
        jobID:
          type: string
          format: uuid
          example: 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f

    JobStatusCallback:
      type: object
      required:
        - jobID
        - status
        - message
      properties:
        jobID:
          type: string
          format: uuid
          example: 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f
        status:
          type: string
          enum:
            - success
            - fail
          example: success
        message:
          type: string
          example: Job completed successfully.

    BatchOpenRequest:
      type: object
      required:
        - batchID
        - jobIDs
      properties:
        batchID:
          type: string
          example: batch-2024-001
        jobIDs:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f
            - 9a8b7c6d-5e4f-3a2b-1c0d-ef1234567890
        requireAllJobs:
          type: boolean
          default: false
          description: If `true`, the batch cannot be closed until all listed jobs have been received.
        name:
          type: string
          example: Morning print run

    BatchOpenResponse:
      type: object
      required:
        - batchID
        - jobIDs
        - requireAllJobs
        - createdTime
      properties:
        batchID:
          type: string
          example: batch-2024-001
        jobIDs:
          type: array
          items:
            type: string
            format: uuid
        requireAllJobs:
          type: integer
          enum:
            - 0
            - 1
          description: "`0` = false, `1` = true."
          example: 1
        createdTime:
          type: string
          format: date-time
          example: "2024-01-15T09:30:00Z"
        name:
          type: string
          example: Morning print run

    BatchCloseRequest:
      type: object
      required:
        - batchID
      properties:
        batchID:
          type: string
          example: batch-2024-001

paths:

  /v1/print:
    post:
      summary: Submit a print job
      description: |
        Submits a document and print options as a `multipart/form-data` upload.
        Returns a job UUID immediately; printing is handled asynchronously.

        Any field names configured in the admin panel may be included as
        additional string form values alongside the standard fields below.

        If `statusURL` is provided, the server will POST a `JobStatusCallback`
        to that URL on job completion or failure. See the `jobStatusUpdate`
        callback.
      operationId: submitPrintJob
      security:
        - basicAuth: []
        - bearerAuth: []
        - {}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - queue
                - username
                - duplex
                - copies
                - color
                - file
              properties:

                queue:
                  type: string
                  description: Printer path. Optionally append a tray name as `PrinterName/TrayName`.
                  example: HP-LaserJet-5/TRAY1

                username:
                  type: string
                  description: User submitting the job. Use `domain\username` for domain accounts.
                  example: ACME\jsmith

                file:
                  type: string
                  format: binary
                  description: The print document.

                duplex:
                  type: string
                  description: |
                    | Value   | Meaning                              |
                    |---------|--------------------------------------|
                    | `0`     | Auto (printer default)               |
                    | `1`     | Simplex (one-sided)                  |
                    | `2`     | Two-sided, long-edge binding         |
                    | `3`     | Two-sided, short-edge binding        |
                    | `true`  | Alias for `2`                        |
                    | `false` | Alias for `0`                        |
                  enum:
                    - "0"
                    - "1"
                    - "2"
                    - "3"
                    - "true"
                    - "false"
                  example: "1"

                copies:
                  type: string
                  description: Number of copies (≥ 1).
                  example: "2"

                color:
                  type: string
                  description: Color (`true`) or monochrome (`false`).
                  enum:
                    - "true"
                    - "false"
                  example: "false"

                jobID:
                  type: string
                  format: uuid
                  description: Client-supplied job UUID. Auto-generated if omitted.
                  example: 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f

                deviceName:
                  type: string
                  description: Name of the submitting device.
                  example: WORKSTATION-42

                paperSource:
                  type: string
                  description: Paper tray or source (e.g. `1`, `TRAY1`, `TRAY 1`).
                  example: TRAY1

                paperSize:
                  type: string
                  description: Paper size (e.g. `letter`, `legal`, `a4`, `a3`, `executive`, `tabloid`).
                  example: letter

                statusURL:
                  type: string
                  format: uri
                  description: Webhook URL called on job completion or failure. See the `jobStatusUpdate` callback.
                  example: https://ehr.example.com/callbacks/print-status

                pageCount:
                  type: string
                  description: Page count override (integer ≥ 0).
                  example: "4"

                costCenter:
                  type: string
                  description: |
                    **Example custom field.** Any field name configured in the admin
                    panel may be submitted as an additional form value.
                  example: "12345"

              additionalProperties:
                type: string

            encoding:
              file:
                contentType: application/octet-stream

      responses:
        "202":
          description: Accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrintJobResponse"
              example:
                jobID: 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f
        "400":
          description: Bad request.
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Unauthorized.
          content:
            text/plain:
              schema:
                type: string
        "405":
          description: Method not allowed.
        "500":
          description: Internal server error.

      callbacks:
        jobStatusUpdate:
          "{$request.body#/statusURL}":
            post:
              summary: Print job status notification
              description: POSTed to `statusURL` on job completion or failure.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/JobStatusCallback"
                    example:
                      jobID: 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f
                      status: success
                      message: Job completed successfully.
              responses:
                "200":
                  description: Acknowledged.
                "4XX":
                  description: Rejected.

  /v1/batch/open:
    post:
      summary: Open a print batch
      description: Registers a batch and associates a set of expected job UUIDs with it.
      operationId: openBatch
      security:
        - basicAuth: []
        - bearerAuth: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchOpenRequest"
            example:
              batchID: batch-2024-001
              jobIDs:
                - 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f
                - 9a8b7c6d-5e4f-3a2b-1c0d-ef1234567890
              requireAllJobs: true
              name: Morning print run
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchOpenResponse"
              example:
                batchID: batch-2024-001
                jobIDs:
                  - 7f3b4c2e-1a2b-4c5d-8e9f-0a1b2c3d4e5f
                  - 9a8b7c6d-5e4f-3a2b-1c0d-ef1234567890
                requireAllJobs: 1
                createdTime: "2024-01-15T09:30:00Z"
                name: Morning print run
        "400":
          description: Bad request.
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Unauthorized.
          content:
            text/plain:
              schema:
                type: string
        "405":
          description: Method not allowed.
        "500":
          description: Internal server error.

  /v1/batch/close:
    post:
      summary: Close a print batch
      description: |
        Closes an open batch. If the batch was opened with `requireAllJobs: true`,
        returns 400 unless all expected jobs have been received.
      operationId: closeBatch
      security:
        - basicAuth: []
        - bearerAuth: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchCloseRequest"
            example:
              batchID: batch-2024-001
      responses:
        "202":
          description: Accepted.
        "400":
          description: Bad request.
          content:
            text/plain:
              schema:
                type: string
              example: "not all jobs have been received and batch was set to require all jobs"
        "401":
          description: Unauthorized.
          content:
            text/plain:
              schema:
                type: string
        "405":
          description: Method not allowed.
        "500":
          description: Internal server error.