Base URL
Get Configuration
Get Printer
Get Printer Properties
Prepare File Upload
File Upload
Print an Uploaded File
Print a File Referenced by URL
Get Status
Status Codes
Error codes

Print API

For code snippets and integration patterns, see AGENT.md.

Printing Quick Guide: The Printing Quick Guide leads you through the different endpoints and functionalities of the Print API and helps you to fully integrate the printing process of ezeep into your workflows.

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)

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

Type	Key	Value
Header	Authorization	`Bearer <access_token>`

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://printhost.example.com:443",
    "HOSTEX": "https://printhost.example.com:443",
    "MaxLocalPreviewFileSize": 16777216
  }
}

Section	Attribute	Type	Description
`System`	`FILEEXT`	string	list of supported file formats (file extension)

Get Printer

Requests a list of printers available to the user

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

Type	Key	Value
Header	Authorization	`Bearer <access_token>`

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/"
 GET "https://printapi.ezeep.com/sfapi/GetPrinterProperties/?id=<printer uuid>"
 GET "https://printapi.ezeep.com/sfapi/GetPrinterProperties/?printer=<printer name>"

Attribute	Type	Required	Description
`Authorization`	Header	yes	`Bearer <access_token>`
`printer`	string	no	The name of the printer. If it is empty, printerproperties of all available printers will be returned.
`id`	string	no	The uiid of the printer. If it is empty, printerproperties of all available printers will be returned.

Specify either printer or id. ezeep is following Microsofts 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,
    "ColorSupported": true,
    "Driver": "TP Output Gateway",
    "DuplexMode": 2,
    "DuplexSupported": true,
    "Id": "176f7433-48b1-43c0-bf5f-637c0d831bdd",
    "Location": "",
    "MediaSupported": ["Auto", "Letter", "Legal", "Statement", "Executive", "A5", "B5", "A4", "Envelope Monarch", "Envelope No. 10 (COM10)", "Envelope DL", "Envelope C5", "Custom [Name Fixed]"],
    "MediaSupportedId": [0, 1, 5, 6, 7, 11, 13, 9, 37, 20, 27, 28, 256],
    "Name": "Canon UFR II Printer",
    "OrientationsSupported": ["portrait", "landscape"],
    "OrientationsSupportedId": [1, 2],
    "PaperFormats": [{
            "Id": 1,
            "Name": "Letter",
            "XRes": 2159,
            "YRes": 2794,
            "Default": false
        }, {
            "Id": 5,
            "Name": "Legal",
            "XRes": 2159,
            "YRes": 3556,
            "Default": false
        }, {
            "Id": 9,
            "Name": "A4",
            "XRes": 2100,
            "YRes": 2970,
            "Default": true
        }, {
            "Id": 27,
            "Name": "Envelope DL",
            "XRes": 1100,
            "YRes": 2200,
            "Default": false
        }, {
            "Id": 28,
            "Name": "Envelope C5",
            "XRes": 1620,
            "YRes": 2290,
            "Default": false
        }
    ],
    "Default":{         
                "Duplex": "duplex_simplex",     
                "DuplexIndex": 1,        
                "Color": "color",        
                "Orientation": null,        
                "OrientationIndex": null,        
                "Resolution": "600",    
                "Paper": "A4",    
                "PaperId": 9,     
                "Tray": "Multi-Purpose Feeder",   
                "TrayIndex": 284     
              },
    "Resolutions": ["Auto", "600"],
    "TPUID": 2,
    "Trays": [{
            "Index": 284,
            "Name": "Multi-Purpose Feeder",
            "Default": true
        }, {
            "Index": 285,
            "Name": "Manual Paper",
            "Default": false
        }, {
            "Index": 286,
            "Name": "Envelope Feeder",
            "Default": false
        }
    ]
}]

Prepare File Upload

Prepares a file upload.

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

Type	Key	Value
Header	Authorization	`Bearer <access_token>`

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://examplestore.blob.core.windows.net/userstorage/ERI_be20b4d1-d6b8-41ee-8ca8-580905b9b4ed?sv=2018-03-28&sr=b&sig=ExAmPlEsIgNaTuReStRiNg1234567890ABCDEF%3D&se=2020-05-22T15%3A45%3A12Z&sp=wl"
}

File Upload

Uploads a file to print.

PUT <sasUri>

Type	Name	Value
Header	x-ms-blob-type	BlockBlob
Header	Content-Type	application/octet-stream
Body		raw bytes of the file

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.

Print an Uploaded File

Prints a file that you have uploaded.

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

Parameters:

Attribute	Type	Required	Description
`fileid`	string	yes	Id of the uploaded file. See `PrepareUpload`
`type`	string	no	Type of the file (e.g. `pdf`). Use `auto` or omit it when the file name extension, `Content-Type` or `Content-Disposition` identifies the format.
`alias`	string	no	Original name of file/document. If it is empty, the fileid will be used.
`printerid`	string	yes	Id of the printer. See `GetPrinter`.
`printanddelete`	bool	no	If `true` the uploaded document will be deleted after printing. If `false` the uploaded document remains on the server. Default is `false`.
`paperid`	int	no	Id of of paper size. See `GetPrinterProperties`
`paperlength`	int	no	If paperid == 256 (custom size): length of paper in tenths of mm
`paperwidth`	int	no	If paperid == 256 (custom size): width of paper in tenths of mm
`color`	bool	no	Enable color. See `GetPrinterProperties`
`duplex`	bool	no	Enable duplex. See `GetPrinterProperties`
`duplexmode`	int	no	Duplex mode. See `GetPrinterProperties`
`orientation`	int	no	Id of orientation mode. See `GetPrinterProperties`
`copies`	int	no	Count of copies. See `GetPrinterProperties`
`resolution`	string	no	DPI / quality . See `GetPrinterProperties`
`trayname`	string	no	Name of tray. See `GetPrinterProperties`
`defaultsource`	int	no	Index of tray(if this value has been set, trayname should be ignored). See `GetPrinterProperties`
`locale`	string	no	If this parameter has value (like “de-DE”, “en-US”), it will apply a specific Language settings(like date, numbers ,…) for documents, spreadsheets or presentations (.doc, .docx, .xls, .xlsx, .ppt, .pptx, …)
`pageRanges`	string	no	It can set a range or numbers (separated with a comma) of pages in the file that can be printed (like “1-2,4-5”, “1,2,3” or “1-2,4-5, 7,8,9”)

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"
}

Printed Document Naming Logic

Print is not idempotent. Every successful Print request 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 the Print request with the fileid from the response body. Don’t upload the file again or resend the fileurl. This applies to requests with fileid and with fileurl.

Print a File Referenced by URL

Target documents’s URL must be public 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, resend it with the returned fileid as described in Print an uploaded file. If the download of the fileurl fails, Print returns HTTP 428 without a fileid.

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

Parameters:

Attribute	Type	Required	Description
`fileurl`	string	yes	URL of the file to print
`type`	string	no	Type of the file (e.g. `pdf`). Use `auto` or omit it when the file name extension, `Content-Type` or `Content-Disposition` identifies the format.
`alias`	string	no	Original name of file/document. If it is empty, the fileid will be used.
`printerid`	string	yes	Id of the printer. See `GetPrinter`.
`printanddelete`	bool	no	If `true` the uploaded document will be deleted after printing. If `false` the uploaded document remains on the server. Default is `false`.
`paperid`	int	no	Id of of paper size. See `GetPrinterProperties`
`color`	bool	no	Enable color. See `GetPrinterProperties`
`duplex`	bool	no	Enable duplex. See `GetPrinterProperties`
`duplexmode`	int	no	Duplex mode. See `GetPrinterProperties`
`orientation`	int	no	Id of orientation mode. See `GetPrinterProperties`
`copies`	int	no	Count of copies. See `GetPrinterProperties`
`resolution`	string	no	DPI / quality . See `GetPrinterProperties`
`trayname`	string	no	Name of tray. See `GetPrinterProperties`
`defaultsource`	int	no	Index of tray(if this value has been set, trayname should be ignored). See `GetPrinterProperties`
`locale`	string	no	If this parameter has value (like “de-DE”, “en-US”), it will apply a specific Language settings(like date, numbers ,…) for documents, spreadsheets or presentations (.doc, .docx, .xls, .xlsx, .ppt, .pptx, …)
`pageRanges`	string	no	It can set a range or numbers (separated with a comma) of pages in the file that can be printed (like “1-2,4-5”, “1,2,3” or “1-2,4-5, 7,8,9”)

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/document.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 for HTTP 412:

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

Printed Document Naming Logic

Get Status

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

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

Parameters:

Attribute	Type	Required	Description
`id`	string	yes	The Job identifier. See `Print`. URL-encode it: it can contain `#` and spaces.

Example Request:

curl -X GET \
 "https://printapi.ezeep.com/sfapi/status/?id=ezprnds-p00000M:HP%20Co_tpcb_4936_114813343%231801071420:1" \
 --header "Authorization: Bearer <access_token>"

Example Response:

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

Status Codes

`jobstatus`	Description
1246	INFO: no status available yet, keep asking
129	INFO: print job processing is running
0	INFO: print job successfully finished
3011	ERROR: something went wrong - restart print job
2	ERROR: invalid print job identifier

Error codes

ezeep uses Microsoft system error codes, represented as integers. See the list of system error codes.