Print vendor API

 

GET /api/printOrders?statuses=[statusList]

 

Description

Query a list of print orders.

 

Query string parameters:

- statuses: a comma-separated list of order statuses

 

Valid status values are:

- ReceivedByVendor
- Printing
- Shipping
- OnHold
- Cancelled

 

Response format

A JSON list of pending print orders. The format for a print order is:

{
    "orderId": number,
    "printJobs": array[PrintJob],
    "rushOrder": boolean,
    "reprint": boolean
}

 

The format for a print job is:

{
    "jobId": string,
    "documentURL": string,
    "csvURL": string (optional),
    "quantity": number,
    "shippingAddress": ShippingAddress,
    "shippingMethod": string,
    "jobOptions": JobOptions
}

 

The jobId will be a string representation of the print job's ID, or of the form [jobId]-addon for add-on jobs. Add-on jobs include envelopes, banner stands, etc.

The shippingMethod will be one of the following:

  • USPS First Class
  • USPS Priority
  • UPS Ground
  • UPS 2nd Day Air
  • UPS Next Day Air
  • Direct mailer
  • FedEx Ground
  • FedEx Priority
  • FedEx Saturday

 

The format for a shipping address is:

{ 
    "name": string,
    "address1": string,
    "address2": string (optional), 
    "city": string,
    "state": string,
    "country": string,
    "zipcode": string
}

 

The format for job options is:

{
    "width": number,
    "height": number,
    "description": string,
    "productType": string,
    "media": string,
    "duplex": boolean (optional),
    "pageCount": number,
    "folds": string (optional),
    "finish": string (optional) 
}

description is a human-friendly description of the print product

productType represents the general type of print

folds, if present, will be of the format (h|v);(\d+.\d+,)+. The first character denotes whether the folds are horizontal or vertical. The decimal numbers after the semicolon are comma-separated and denote the distance (in inches) from the bottom/left edge of the page

 

Example response

[
  {
    "orderId": 1,
    "printJobs": [
      {
        "jobId": 1,
        "documentURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 4,
          "height": 6,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      }
    ]
  },
  {
    "orderId": 2,
    "printJobs": [
      {
        "jobId": 1,
        "documentURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 5,
          "height": 7,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      },
      {
        "jobId": 2,
        "documentURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 5,
          "height": 7,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      },
      {
        "jobId": 3,
        "documentURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 4,
          "height": 6,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      }
    ]
  },
  {
    "orderId": 3,
    "printJobs": [
      {
        "jobId": 1,
        "documentURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 4,
          "height": 6,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      }
    ]
  }
]

 

Authentication

You no longer need to use a vendor code to connect to the API. Going forward, the endpoint is /api/printOrders?statuses=X,Y,Z where X, Y, and Z are substituted with valid status values. If you would like to access this endpoint from outsite the browser via cURL or Postman, you need to copy the lucidauth cookies form the browser and send it with the request. For example:

1. Sign in to Lucidpress.

2. Copy the value of the lucidauth cookie under the Lucidpress.com domain.

3. Decode this value using decodeURIComponent(cookieValueHere)

4. Use https://print.lucidpress.com/api/printOrders?statuses=SentToVendor for the URL in Postman.

5. Set the Authorization header in the request in Postman. The value should be the result of step 3.

 

 

 

POST /api/printOrders

 

Description

Send a list of updates for print jobs and orders

 

Body parameters

  • A JSON list of order updates

 

Order update format:

{  
    "orderId": number,
    "jobId": number,
    "status": string,
    "trackingNumber": string (optional),
    "shippingCarrier": string (optional),
    "shippingMethod": string (optional),
    "dateShipped": string (optional) 
}

 

Note: currently, only one status update per order is accepted. The jobId can be the ID of any job in the order.

Note: Status updates for "add-on" jobs are not needed and will not be accepted

Valid status values are:

  • ReceivedByVendor
  • Printing
  • Shipping
  • OnHold
  • Cancelled

 

The optional keys (trackingNumber, shippingCarrier, shippingMethod, and dateShipped) are only required when the status is Shipping

The format for the shipping date is MM/DD/YYYY HH:MM:SS [AM|PM]

 

A status update on a job will only be accepted if the new status is a valid transition from the current status. Valid transitions are:

  • SentToVendor -> ReceivedByVendor, Printing, Shipping, OnHold, or Cancelled
  • ReceivedByVendor -> Printing, Shipping, OnHold, or Cancelled
  • Printing -> OnHold or Shipping
  • Shipping -> Shipping (terminal state, but updates to shipping information are allowed)
  • OnHold -> ReceivedByVendor, Printing, Shipping, or Cancelled
  • Cancelled -> N/A (terminal state)

 

Response format

A multistatus JSON object:

{
    "multistatus": [
        {...},
        {...},
        {...},
        ...
    ]
}

 

Status object format:

{  
    "id": string,
    "Status": string,
    "Reason": string
}

 

The id will be of the form [orderId]-[jobId]

The Status will be a string representation of an HTTP status code

  • 200 for a successful status update
  • 400 for invalid data
  • 500 for an internal server error

 

The Reason will give additional information. Examples of reasons are:

  • "Success"
  • "Invalid order id"
  • "Invalid job id"
  • "No existing status for [id]"
  • "Attempted to set status of [id] to invalid status [status]"
  • "Attempted to make invalid status transition from [currentStatus] to [attemptedStatus]"

 

Example request body data

[
  {
    "orderId": 1,
    "jobId": 1,
    "status": "Shipping",
    "trackingNumber": "9400000000000000000000",
    "shippingCarrier": "USPS",
    "shippingMethod": "USPS Priority",
    "dateShipped": "04/17/2018 11:00:00 AM"
  },
  {
    "orderId": 2,
    "jobId": 1,
    "status": "Printing"
  },
  {
    "orderId": 2,
    "jobId": 2,
    "status": "SomeInvalidStatus"
  },
  {
    "orderId": 2,
    "jobId": 3,
    "status": "Printing"
  },
  {
    "orderId": 3,
    "jobId": 1,
    "status": "ReceivedByVendor"
  },
  {
    "orderId": 3,
    "jobId": 2,
    "status": "ReceivedByVendor"
  },
  {
    "orderId": 4,
    "jobId": 1,
    "status": "Printing"
  }
] 

 

Example response

{
  "multistatus": [
    {
      "id": "1-1",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "2-1",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "2-2",
      "Status": "400",
      "Reason": "Attempted to set status of 2-2 to invalid status SomeInvalidStatus"
    },
    {
      "id": "2-3",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "3-1",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "3-2",
      "Status": "400",
      "Reason": "Invalid job id"
    },
    {
      "id": "4-1",
      "Status": "500",
      "Reason": "Invalid order id"
    }
  ]
}
 
 
Was this article helpful?
1 out of 1 found this helpful
Fill out my online form.