• Authentication
  • Request access token
  • Use refresh token
• Printing
  • Base URL
  • Get Configuration
  • Get Printer
  • Get Printer Properties
  • Prepare file upload
  • File Upload
    • Upload in one part
    • Upload in multiple parts
  • Print an uploaded file
  • Print a file referenced by URL
  • Printed Document Naming Logic
    • Precedence Rules
      • File Base Name (in order of precedence):
      • File Extension (in order of precedence):
  • Get Status
  • Print Job Status Codes
  • Error codes

Printing Quick Guide

The Print API lets you fully integrate the printing process of ezeep into your workflows. Starting from an authorization code created with the Authorization Code Flow or the Authorization Code Flow with PKCE, the steps below cover authenticating a user with access and refresh tokens, selecting a cloud-connected printer, creating and uploading a document, customizing the settings for a print job, triggering a print job on a printer connected to ezeep, and finally getting information on the print job status - all through the API.

Authentication

Request access token

Once you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (code) from the previous step.

POST 'https://account.ezeep.com/oauth/access_token/'

scope can only narrow the scopes granted in the authorization request, never widen them.

Replace <base64(client_id:)> with the Base64 encoding of your client ID followed by a colon (see ClientID/Secret Encoding). Public clients use the Authorization Code Flow with PKCE and send the additional parameters described there.

Example Request

curl  -X POST 'https://account.ezeep.com/oauth/access_token/' \
      --header "Authorization: Basic <base64(client_id:)>" \
      --header "Content-Type: application/x-www-form-urlencoded" \
      --data "grant_type=authorization_code" \
      --data "scope=printing" \
      --data "code=<authorization_code>" \
      --data-urlencode "redirect_uri=<registered redirect_uri>"

Example Response

{
  "access_token": "eyJ0eXAiO...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "printing",
  "refresh_token": "erliDdAb..."
}

Access_token will be valid for 3600 seconds (1 hour) and after that duration you have to request new access token using the refresh token that you received in the access token response.

Use refresh token

Use the refresh token to get a new access token after the previous one expires. Don’t request a new access token before every API call.

To refresh your token, send a POST request to /oauth/access_token/ with grant_type=refresh_token.

curl -X POST 'https://account.ezeep.com/oauth/access_token/'

Example request:

curl -X POST 'https://account.ezeep.com/oauth/access_token/' \
     --header "Authorization: Basic <base64(client_id:)>" \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data "grant_type=refresh_token" \
     --data "scope=printing" \
     --data "refresh_token=qX5HTLt4..."

Example Response

{
  "access_token": "eyJ0eXAiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "",
  "refresh_token": "vT5GTKk8..."
}

refresh_token: You can use the refresh token once to generate a new access token and refresh token.

You will need to replace and store the new refresh token securely from the response for future usage.

Printing

To print using the ezeep print api first you will need to work through the Authentication process and have a valid access token. You can now use this token to work through the following steps of the printing process.

Base URL

https://printapi.ezeep.com/

Get Configuration

With this request, you can retrieve details of the currently authenticated user and related system configuration parameters. It is used to determine which filetypes are supported for printing (System:FILEEXT). You can also get the supported file types from the public endpoint GET https://printapi.ezeep.com/sfapi/GetSupportedFileTypes/.

GET https://printapi.ezeep.com/sfapi/GetConfiguration/

Example Request:

curl -X GET 'https://printapi.ezeep.com/sfapi/GetConfiguration/' \
     --header "Authorization: Bearer <access_token>"

Example response:

{
    "Drivers": {
        "PrinterDynamic": "0e651413e003e36de6781cfe227a9cc2",
        "PrinterStatic": "ee527381ab6ab5d4aba89f8ec2fd5d2c"
    },
    "Folders": [
        {
            "export": "",
            "id": 1,
            "op": 3
        }
    ],
    "SFForms": {
        "$Count": 0
    },
    "Shell": [],
    "System": {
        "BW": 0,
        "CONNECT": ":4001",
        "CONNECTEX": ":4001",
        "DocProvUplInterval": 60,
        "FILEEXT": "bmp;csv;doc;docm;docx;dot;dotm;dotx;eml;gif;htm;html;jpeg;jpg;log;mht;mhtml;odf;odg;odm;odp;odt;otg;oth;otp;ott;pdf;png;pot;potm;potx;pps;ppsx;ppt;pptm;pptx;rtf;scp;sda;sdd;sds;sdw;sgl;smf;sti;stw;sxd;sxg;sxi;sxm;sxw;tif;tiff;tpf;txt;vor;wtx;xls;xlsb;xlsm;xlsx;xlt;xltm;xltx;xml;xps;",
        "HOST": "https://printserver.example.com:443",
        "HOSTEX": "https://printserver.example.com:443",
        "MaxLocalPreviewFileSize": 16777216
    }
}

Get Printer

Requests a list of printers available to the user

  GET  https://printapi.ezeep.com/sfapi/GetPrinter/

Example Request:

The response contains a list of available printers:

curl -X GET 'https://printapi.ezeep.com/sfapi/GetPrinter/' \
     --header "Authorization:Bearer <access_token>"

Example Response:

[
  {
    "id": "2fd4f571-7c2e-4042-8fc5-1d736f532e88",
    "location": "Parallel Universe 2b-α-3187",
    "name": "printer 6"
  },
  {
    "id": "9620e656-b39b-49ba-a653-a3f168575ec2",
    "location": "",
    "name": "printer01"
  }
]

Get Printer Properties

Returns further properties of the printer by printer id.

 GET https://printapi.ezeep.com/sfapi/GetPrinterProperties/

Specify either printer or id. ezeep is following Microsoft’s DEVMODE for printer properties. You can find a detailed specification here

Example Request:

curl -X GET \
     "https://printapi.ezeep.com/sfapi/GetPrinterProperties/?id=016bc036-2498-431e-84c6-14552639f515" \
     --header "Authorization: Bearer <access_token>"

Example response:

[
  {
    "Collate": true,
    "Color": false,
    "Driver": "",
    "DuplexMode": 0,
    "DuplexSupported": false,
    "Id": "9620e656-b39b-49ba-a653-a3f168575ec2",
    "Location": "",
    "MaxXExtent": 0,
    "MaxYExtent": 0,
    "Name": "printer01",
    "OrientationsSupported": ["portrait", "landscape"],
    "OrientationsSupportedId": [1, 2]
  }
]

Prepare file upload

Uploads a file to print.

GET https://printapi.ezeep.com/sfapi/PrepareUpload/

Example request:

curl -X GET 'https://printapi.ezeep.com/sfapi/PrepareUpload/' \
     --header "Authorization: Bearer <access_token>"

Example Response:

The response will include the file id of your new document as well as the sasURI which we will use for the upload later on:

{
  "fileid": "ERI_be20b4d1-d6b8-41ee-8ca8-580905b9b4ed",
  "sasUri": "https://<storage_account>.blob.core.windows.net/userstorage/ERI_be20b4d1-d6b8-41ee-8ca8-580905b9b4ed?sv=2018-03-28&sr=b&sig=<signature>&se=2020-05-22T15%3A45%3A12Z&sp=wl"
}

File Upload

Uploads a file to print. For uploading, the sasUri returned in PrepareUpload is used. This Uri points to a global Azure Blob Storage. You can upload a file in one request when the file length is known in advance, or in several parts with one HTTP request per part. Uploading in parts does not use HTTP Transfer-Encoding: chunked. The request body contains the raw file bytes. Send Content-Type: application/octet-stream.

Upload in one part

PUT {{sasUri}}

Example request:

curl -X PUT "<sasUri>" \
    --header "x-ms-blob-type: BlockBlob" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @file.pdf

If successful, you will receive an empty HTTP 201 (created) response.

Upload in multiple parts

1st call: create the AppendBlob type blob

PUT {{sasUri}}

Example request:

curl -X PUT "<sasUri>" \
    --header "Content-Type: application/octet-stream" \
    --header "x-ms-blob-type: AppendBlob" \
    --header "Content-Length: 0"

If successful, you will receive an empty HTTP 201 (created) response.

2nd and following calls:

Pay attention to append the described parameter to the sasUri.

PUT {{sasUri}}&comp=appendblock

Example request:

curl -X PUT "<sasUri>&comp=appendblock" \
    --header "Content-Type: application/octet-stream" \
    --header "x-ms-blob-type: AppendBlob" \
    --data-binary @part1.bin

If successful, you will receive an empty HTTP 201 (created) response. Each request body contains one part of the raw file bytes. The parts are joined into the file to print.

Print an uploaded file

Prints a file that you have uploaded before or releases an AnyPrinter print job.

POST https://printapi.ezeep.com/sfapi/Print/

Parameters:

For all parameters, see the Print API.

Example request:

The request parameters need to be sent in the body in JSON format.

curl -X POST 'https://printapi.ezeep.com/sfapi/Print/' \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer <access_token>" \
     --data '{
         "fileid": "<fileid>",
         "printerid": "<printer_id>",
         "type": "pdf"
         }'

Example Response:

{
  "jobid": "ezprnds-d000001:HP Un_tpcb_788_7863578#2031753094:4"
}

Print is not idempotent. Every successful Print call can create a new print job. Don’t resend a Print request blindly, for example after a timeout.

If Print returns HTTP 412 Precondition Failed, the print data is already stored. Resend Print with the fileid from the 412 response body. Don’t upload or download the file again. This applies to requests with fileid and with fileurl.

Print a file referenced by URL

Target documents’ URL must be publicly reachable and must contain all information needed to download the file (e.g. authorization information if needed).

Request and response are the same as for Print an uploaded file, except that the JSON attribute fileurl replaces fileid. If Print returns HTTP 412 Precondition Failed, resend Print with the fileid from the response body as described in Print an uploaded file. If the file at fileurl can’t be downloaded, Print returns HTTP 428 and the response body contains no fileid.

POST https://printapi.ezeep.com/sfapi/Print/

Parameters:

Example request:

curl -X POST "https://printapi.ezeep.com/sfapi/Print/" \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer <access_token>" \
     --data '{
         "fileurl": "https://example.com/file.pdf",
         "printerid": "016bc036-2498-431e-84c6-14552639f515",
         "type": "pdf"
        }'

Example Response if file has printed:

{
  "jobid": "ezprnds-d000001:HP Un_tpcb_788_7863578#2031753094:4"
}

Example response with HTTP 412:

{
  "fileid": "ERI_be20b4d1-d6b8-41ee-8ca8-580905b9b4ed",
  "sasUri": ""
}

Printed Document Naming Logic

The final document name consists of a base name and an extension separated by a dot. The extension itself does not contain any dots and is used for determine the document type.

ezeep automatically determines both components by examining: 1. The file URL (either given by fileurl or the reference to the uploaded file) 2. HTTP headers: Content-Disposition and Content-Type

These automatically determined values can be overwritten using the alias and type parameters.

Precedence Rules

File Base Name (in order of precedence):

1. alias parameter value
2. Content-Disposition header filename
3. URL path (filename from URL)
4. Default value: “printfile”

File Extension (in order of precedence):

1. type parameter (if not empty or “auto”)
2. alias parameter (if alias contains a dot the extension is extracted from it)
3. Content-Disposition header (if filename contains a dot, extension is extracted from it)
4. Content-Type header (mapped to appropriate extension)
5. URL path (extension extracted from URL)
6. Default value: “pdf”

Get Status

You can retrieve information on the printjob state with the following request:

GET https://printapi.ezeep.com/sfapi/Status/?id=:id

Parameters:

Always URL-encode the job identifier. It can contain # and spaces.

Example request:

curl -G "https://printapi.ezeep.com/sfapi/status/" \
 --data-urlencode "id=ezprnds-p00000M:HP Co_tpcb_4936_114813343#1801071420:1" \
 --header "Authorization: Bearer <access_token>"

Example response:

{
  "jobpagesprinted": 0,
  "jobpagestotal": 1,
  "jobposition": 1,
  "jobstatus": 129,
  "jobstatusstring": "PRINTING|RETAINED|"
}

Print Job Status Codes

These codes are expected. Handle each of them in your client.

Error codes

Stuck with an error code? We are using Microsoft error codes that are represented by an integer. Find a comprehensive list here: https://docs.microsoft.com/en-us/windows/win32/debug/system-error-codes