1. Cloud Printing
  2. Print Jobs

Cloud Printing

Print Jobs

Print jobs represent documents queued for printing. When you create a print job, the system automatically routes it to the best available printer based on document requirements and queue length.

Endpoints

Method Endpoint Description
GET /v1/cloud-printing/jobs List all print jobs
POST /v1/cloud-printing/jobs Create a new print job
GET /v1/cloud-printing/jobs/:job_id Retrieve a print job
POST /v1/cloud-printing/jobs/:job_id Update a print job status

Required Scopes

  • print_jobs:read - For listing and retrieving jobs
  • print_jobs:write - For creating and updating jobs

Create Print Job

        POST /v1/cloud-printing/jobs

Creates a new print job. The system will route the job to the most suitable printer based on capabilities and queue length.

Request Body

        {
  "location_id": "loc_abc123",
  "print_station_id": "prnt_stn_xyz",
  "printer_name": "HP LaserJet Pro",
  "data": "https://example.com/document.pdf",
  "name": "Invoice #12345",
  "resource": {
    "type": "shipment",
    "id": "shp_abc123",
    "document": "shipping_label"
  },
  "configuration": {
    "copies": 1,
    "color_print": false,
    "double_sided": true,
    "orientation": "portrait",
    "paper_size": "page_size_letter",
    "print_all_pages": true,
    "reverse_order": false,
    "scaling": 1.0
  }
}

Parameters

Parameter Type Required Description
location_id string ✓ Location ID
data string ✓ Document URL or base64 encoded data
print_station_id string Target station (auto-selects if omitted)
printer_name string Target printer name within station
name string Job name (max 191 chars)
resource object Link to a resource
configuration object Print settings

Document Data Formats

The data field accepts two formats:

URL:

        "data": "https://example.com/document.pdf"

Base64 with data URI:

        "data": "data:application/pdf;base64,JVBERi0xLjQK..."

Resource Types

Link print jobs to PackageX resources for tracking:

        // Shipment (shipping labels)
{
  "type": "shipment",
  "id": "shp_abc123",
  "document": "shipping_label"
}

// Fulfillment (packing slips)
{
  "type": "fulfillment",
  "id": "ful_abc123",
  "document": "packing_slip"
}

// Item (item labels)
{
  "type": "item",
  "id": "item_abc123",
  "document": "item_label"
}

// Asset (asset labels)
{
  "type": "asset",
  "id": "ast_abc123",
  "document": "asset_label"
}

Configuration Options

Parameter Type Default Description
copies integer 1 Number of copies
color_print boolean false Print in color
double_sided boolean false Duplex printing
orientation string "portrait" portrait or landscape
paper_size string Paper size value (see Models)
print_all_pages boolean true Print all pages
pages_to_print array Specific pages (e.g., ["1", "3", "5-10"])
reverse_order boolean false Reverse page order
scaling number Scale factor (0.5 = 50%, 1.5 = 150%)
total_pages integer Override page count

Auto-Selection Logic

When print_station_id is not provided, the system automatically selects the best printer:

  1. Filter by Capability - Only printers supporting the required paper size and orientation
  2. Check User Access - Only stations the user can access
  3. Match Location - Only stations at the specified location
  4. Optimize Queue - Select the printer with the fewest queued jobs

Minimal Request Example

        {
  "location_id": "loc_abc123",
  "data": "https://example.com/document.pdf"
}

Response

        {
  "data": {
    "object": "print_job",
    "id": "prnt_job_abc123",
    "name": "Invoice #12345",
    "status": "queued",
    "data_url": "https://storage.packagex.io/...",
    "station": {
      "id": "prnt_stn_xyz",
      "name": "Station-001",
      "display_name": "Front Desk Printer"
    },
    "printer": {
      "id": "019b1234-...",
      "name": "HP LaserJet Pro",
      "model": "HP LaserJet Pro M404dn"
    },
    "options": {
      "paper_size": "page_size_letter",
      "copies": 1,
      "orientation": "portrait",
      ...
    },
    "created_at": "2024-01-15T10:30:00.000Z"
  },
  "status": 201,
  "message": "Print job created"
}

Update Print Job Status

        POST /v1/cloud-printing/jobs/:job_id

Updates the status of a print job. This endpoint is typically used by the print station application to report job progress.

Status Transitions

        queued → processing → completed
                   → failed (requires reason)
       → canceled

Request Examples

Mark as Processing:

        {
  "status": "processing"
}

Mark as Completed:

        {
  "status": "completed"
}

Mark as Failed:

        {
  "status": "failed",
  "reason": "Printer out of paper"
}

The reason field is required when status is failed and must be 3-1023 characters.

Cancel Job:

        {
  "status": "canceled"
}

Response

        {
  "data": {
    "object": "print_job",
    "id": "prnt_job_abc123",
    "status": "completed",
    ...
  },
  "message": "Print job updated"
}

List Print Jobs

        GET /v1/cloud-printing/jobs

Returns a paginated list of print jobs.

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
limit integer Results per page (default: 20, max: 100)
order_by string Sort field: created_at, updated_at
direction string Sort direction: asc, desc
location_id string Filter by location ID
status string Filter by status
print_station_id string Filter by print station ID
printer_id string Filter by printer ID (UUID)
created_at[gte] string Filter by creation date
created_at[lte] string Filter by creation date
updated_at[gte] string Filter by update date
updated_at[lte] string Filter by update date

Example Request

        curl -H "PX-API-KEY: your_api_key" \
     "https://api.packagex.io/v1/cloud-printing/jobs?status=queued&print_station_id=prnt_stn_abc123"

Response

        {
  "data": [
    {
      "object": "print_job",
      "id": "prnt_job_abc123",
      "name": "Invoice #12345",
      "status": "queued",
      "station": {...},
      "printer": {...},
      ...
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "has_more": true
  },
  "message": "5 print jobs retrieved"
}

Retrieve Print Job

        GET /v1/cloud-printing/jobs/:job_id

Retrieves a single print job by ID.

Example Request

        curl -H "PX-API-KEY: your_api_key" \
     "https://api.packagex.io/v1/cloud-printing/jobs/prnt_job_abc123"

Response

        {
  "data": {
    "object": "print_job",
    "id": "prnt_job_abc123",
    "name": "Invoice #12345",
    "status": "completed",
    "reason": null,
    "data_url": "https://storage.packagex.io/...",
    "data_type": "application/pdf",
    "resource_id": "shp_abc123",
    "resource_document": "shipping_label",
    "station": {
      "id": "prnt_stn_xyz",
      "name": "Station-001",
      "display_name": "Front Desk Printer"
    },
    "printer": {
      "id": "019b1234-...",
      "name": "HP LaserJet Pro",
      "model": "HP LaserJet Pro M404dn"
    },
    "options": {
      "paper_size": "page_size_letter",
      "copies": 1,
      "total_pages": 2,
      "orientation": "portrait",
      "color_print": false,
      "double_sided": true,
      "print_all_pages": true,
      "pages_to_print": null,
      "reverse_order": false,
      "scaling": null
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z",
    "created_by": "key_abc123",
    "updated_by": "key_abc123"
  },
  "message": "Print job retrieved"
}

Error Codes

Code Status Description
no_compatible_printer 400 No printer matches the document requirements
unauthorized 403 You don't have access to this print station
location_access 403 You don't have access to this location
not_found 404 Print job not found

Webhooks

Print job status changes trigger webhook events:

Event Description
cloud_printing.job.created New print job created
cloud_printing.job.completed Print job completed successfully
cloud_printing.job.failed Print job failed
cloud_printing.job.canceled Print job canceled
Previous <- Print Stations
Next Integrations Overview ->