- Requirements
- Starting
- Endpoints
-
User Authentication
- 1. Navigate user to our authorization endpoint
- 2. User authenticates via one of the supported authentication providers
- 3. After successful authentication the user will be redirected to your provided URI with an authorization_code
- 4. With the authorization_code, your application can request an access token and refresh token
- Use Refresh Token
- GetConfiguration
- Get Printers
- Prepare Printing
- Printing
- GetStatus
- Error codes
About ezeep Blue
ezeep is the future of Printing. With ezeep, printing will become dramatically simpler and any device will be able to print on any printer. ezeep Blue combines the simplicity of ezeep with the stability, scalability and high printing speed of ThinPrint’s remote desktop solution.
Thanks to ezeep, organizations can simplify their administration and provide printing to their users with fewer requirements on their infrastructure. With a few clicks, they can manage access to their printers and monitor print activity. That leads to lower overall costs for printing.
ezeep’s API first approach ensures open interfaces that allow easy integrations with existing solutions for user and resource management, cost control, compliance monitoring and others to achieve maximum savings through automation. A continuously growing ecosystem of standard integrations by development partners benefits non-technical customers as well.
By lowering costs, removing technical requirements and providing the ability to share printers in a managed and secure way with anyone anywhere, ezeep ensures that printing becomes easy.
Introduction
ezeep Blue supports a Print API that enables 3rd Party developers to use the ezeep platform and fully integrate printers into their workflows. In this document you will go through a full print workflow and will learn to
- Connect a user account with the authorization code workflow
- Authenticate a user with access and refresh tokens
- Pick a cloud connected printer
- Create and upload a document
- Adjust settings for a print job
- Trigger a print job to an ezeep-connected printer
- Get information on the printjob status
Requirements
- ezeep Blue administrator account
- Your personal ezeep Client ID
- an ezeep Blue print API subscription (after the trial period expires). For more information follow this link
To setup your ezeep administrator account and organization, sign up here
To receive your Client ID, contact us at helpdesk@ezeep.com and provide your redirect URI(s)
For the full documentation on setting up your ezeep Blue account, check our web documentation
Starting
The printing workflow requires to
- authenticate the user
- get printers
- prepare an upload
- upload a file
Endpoints
URL | Name |
---|---|
https://account.ezeep.com | Account Management API |
https://printapi.ezeep.com | Print Management API |
User Authentication
To connect any account with ezeep, the user has to authorize ezeep with an authorization code. This authorization code enables your application to receive your required access token for interacting with the ezeep API. This process contains the following steps, which will be described more detailed:
- Navigate user to our authorization endpoint
- User authenticates via one of the supported authentication providers (e.g. Microsoft, Google, Apple or ezeep Login)
- After successful authentication the user will be redirected to your provided URI with an authorized code
- With the authorized code, your application can request an access token and refresh token
1. Navigate user to our authorization endpoint
From your application navigate your user to the following authorization endpoint:
https://account.ezeep.com/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>
Required query parameters:
name | description |
---|---|
response_type | defines the OAuth2 grant, code is preferred as authorization grant |
client_id | the Client ID you received from ezeep |
redirect_uri | has to match one of the redirect URIs you provided to ezeep when you requested your Client ID |
Optional query parameters:
name | description |
---|---|
social |
azure to automatically redirect to Microsoft for authentication |
prompt |
none to prevent Microsoft from showing the account selection prompt |
scope | should be printing
|
state | can be used to maintain state after redirecting the user agent |
2. User authenticates via one of the supported authentication providers
The user will be prompted a login window and can chose to sign-in with one of several authentication providers. If the user has an active session due to a preceding sign-in, the prompt will be skipped and the user will be redirected to the redirect_uri.
3. After successful authentication the user will be redirected to your provided URI with an authorization_code
If the user signed in successfully, ezeep takes care of persisting a reference to the sign-in. The user is redirected to the redirect_uri that was provided in the initial request in 1. with an additional query parameter code
appended to the URI.
Your application needs to capture this code to exchange it for an access token and refresh token.
Examples:
http://localhost:8080/?code=<authorization_code>
myapp://callback?code=<authorization_code>
4. With the authorization_code, your application can request an access token and refresh token
Once you receive the authorization_code on your redirect_uri endpoint, you can exchange it in for an access token and refresh token from the ezeep backend.
Send a POST request to ezeep’s access token endpoint containing the following x-www-form-urlencoded
data:
https://account.ezeep.com/oauth/access_token/
POST /oauth/access_token/ HTTP/1.1
Host: account.ezeep.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded client_id:client_secret>
code=<authorization_code>&grant_type=authorization_code
Header
Header | Value |
---|---|
Authorization | Basic {{base_64_encoded_client_id::client_secret}} |
Parameters
Key | Value |
---|---|
grant_type | authorization_code |
scope | printing |
code | {{auth_code}} |
base_64_encoded_client_id
Basic authentication scheme is used, meaning the Authorization header value is Basic
followed by a space
and the base64 encoded client_id followed by a colon :
For example: If your client id is g34ibgu2fhon
you need to base64-encode it as g34ibgu2fhon:
which results in ZzM0aWJndTJmaG9uOg==
You can use a base64 encoding tool like this one.
The server will respond with an access token, a refresh token, scopes and information about the expiration time, using JSON as content type:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "<access_token>",
"refresh_token": "<refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "printing accounts.me",
}
If the authorization code is faulty or expired, you will receive the following response:
{
"error": "invalid_grant",
"error_description": "Wrong code or grant is expired"
}
Use Refresh Token
You can use the refresh token once to generate a new access token and refresh token:
Request
POST https://account.ezeep.com/oauth/access_token/
Header
Header | Value |
---|---|
Authorization | Basic {{base_64_encoded_client_id}} |
Parameters
Key | Value |
---|---|
grant_type | refresh_token |
scope | printing |
refresh_token | {{refresh_token}} |
Example request:
curl -X POST \
https://account.ezeep.com/oauth/access_token/ \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Basic TXV5eTJZbGlhYjdGbTk5eDN0Qk1NVlE5dnczVDIyNnFJR2JtNzhMMzo=' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 434' \
-H 'Content-Type: multipart/form-data; boundary=--------------------------710431197666476907779887' \
-H 'Host: account.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F grant_type=refresh_token \
-F scope=printing \
-F refresh_token=wT5GTKk8s4eL1khJqdkaEFhth23459OQV
Example Response
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "",
"refresh_token": "vT5GTKk8s4eL1MhJqdkaEFhth23459OQV"
}
You will need to replace and store the new refresh token securely from the response for future usage.
GetConfiguration
With this request, you can retreive details of the currently authenticated user and related system configuration parameters . It is used to determine which filetypes are supported for printing (System:FILEEXT)
Request
shell
GET https://printapi.ezeep.com/sfapi/GetConfiguration/
curl -X GET \
https://printapi.ezeep.com/sfapi/GetConfiguration/ \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...' \
-H 'Connection: keep-alive' \
-H 'Host: printapi.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2'
Example response:
{
"Drivers": {
"PrinterDynamic": "0e651413e003e36de6781cfe227a9cc2",
"PrinterFull": "926f4fb3ccefa24cf7ad8e23601d5101",
"PrinterStatic": "ee527381ab6ab5d4aba89f8ec2fd5d2c"
},
"Folders": [
{
"export": "",
"id": 1,
"op": 3
},
{
"export": "",
"id": 2,
"op": 0
}
],
"GUI": {
"DENY": 3073,
"PPARAMS": 0,
"SHOW": 4261355519,
"SHOWEXP": 2431,
"SHOWRST": 4261355519
},
"Schema": {
"Version": "1.0"
},
"Server": {
"VERSION": "1.0"
},
"SFForms": {
"$Count": 0
},
"Shell": [],
"System": {
"BBMailGW": "",
"BW": 0,
"CONNECT": ":4001",
"CONNECTEX": ":4001",
"DBG": 0,
"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://vm-mfkym5000000:443",
"HOSTEX": "https://vm-mfkym5000000:443",
"MaxLocalPreviewFileSize": 16777216,
"PACKETSIZE": 0,
"RECONNECT": 0,
"TESTIV": 0,
"TOOPENPRINTER": 0,
"TOPRINT": 0,
"VALIDITY": 900
},
"User": {
"$LoggedUserCount": 0,
"ACCOUNT": 1,
"ATTACHMENTSIZEMAX": 5,
"PWEXPIRATIONDATE": -1,
"TPUID": "0:0"
},
"Workplace": {
"DiskQuotaFree": -1.000000,
"DiskQuotaLimit": -1.000000,
"DiskQuotaUsed": -1.000000
}
}
| Section | Attribute | Type | Description |
| —————– | ———– | ——– | —————————————————————————————————— |
| System
| FILEEXT
| string | list of supported file formats (file extension) |
Get Printers
With this request, you can receive a list of printers and meta information about them:
Request
shell
GET https://printapi.ezeep.com/sfapi/GetPrinter/
curl -X GET \
https://printapi.ezeep.com/sfapi/GetPrinter/ \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...' \
-H 'Connection: keep-alive' \
-H 'Host: printapi.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2'
The response contains a list of available printers:
[
{
"id": "2fd4f571-7c2e-4042-8fc5-1d736f532e88",
"location": "Parallel Universe 2b-α-3187",
"name": "printer 6"
},
{
"id": "9620e656-b39b-49ba-a653-a3f168575ec2",
"location": "",
"name": "printer01"
},
{
"id": "e5ca2805-4027-4a29-ac8b-dc4aa6260548",
"location": "Parallel Universe 2b-α-3189",
"name": "printer1"
}, {
"id": "1d223089-55fd-4dcb-8dd2-0a597133f27c",
"location": "",
"name": "test99"
}
]
GetPrinterProperties
To get further information about the printer, you can query a specific printer this way:
GET https://printapi.ezeep.com/sfapi/GetPrinterProperties/?printer={{printer_name}}&id={{printer_id}}
Specify either printer_name or printer_id. ezeep is following Microsofts DEVMODE for printer properties. You can find a detailed specification here
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
printer |
string | no | The name of the printer. If it is empty, printerproperties of all available printers will be returned. |
id |
string | no | The id of the printer. If it is empty, printerproperties of all available printers will be returned. |
You can get the printer properties by printer_id:
curl -X GET \
'https://printapi.ezeep.com/sfapi/GetPrinterProperties/?id=9620e656-b39b-49ba-a653-a3f168575ec2' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2...' \
-H 'Connection: keep-alive' \
-H 'Host: printapi.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2'
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 Printing
To print a document you have to provide it to the printing service. So you can upload document’s file directly or alternatively you can provide an URL pointing to the document to print (see Print a file referenced by URL).
Prepare uploading a file to print
To upload a document, you first have to create a blank “file blob” which you can fill with your data in the second step. To create this file blob, just send the following request:
Request
GET https://printapi.ezeep.com/sfapi/PrepareUpload/
Example request:
curl -X GET \
https://printapi.ezeep.com/sfapi/PrepareUpload/ \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9....' \
-H 'Connection: keep-alive' \
-H 'Host: printapi.ezeep.com'
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://rndsvcezp.blob.core.windows.net/userstorage/ERI_be20b4d1-d6b8-41ee-8ca8-580905b9b4ed?sv=2018-03-28&sr=b&sig=FxuLjL2Kids9Ww60dqQ6FlqscTTccKFBwk%2Ft0Tyf%2BM0%3D&se=2020-05-22T15%3A45%3A12Z&sp=wl"
}
Uploading the file
Now that you have successfully created a file blob, you can use the returned SAS URI to upload your file.
Request
shell
PUT {{sasURI}}
Header | Value |
---|---|
Host | {{hostname from sasUri}} |
x-ms-blob-type | BlockBlob |
Parameters
Key | Value |
---|---|
file | {{file}} |
Example request
curl -X PUT \
'https://rndsvcezp.blob.core.windows.net/userstorage/ERI_cf44e7b9-3725-43e6-8ead-edfaec6cfcd2?sv=2018-03-28&sr=b&sig=sJQjCHuO4zHMnLF2QzEwYxPEh%2FHI4ycnV8fH5G02olo%3D&se=2020-06-04T16%3A42%3A28Z&sp=wl' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 211' \
-H 'Content-Type: multipart/form-data; boundary=--------------------------759498512080189801667215' \
-H 'Host: rndsvcezp.blob.core.windows.net' \
-H 'User-Agent: PostmanRuntime/7.15.2' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'x-ms-blob-type: BlockBlob' \
-F file=@/path/to/file/cool.txt
If successful, you will receive an empty HTTP 201 (created) response.
Further information on the file upload API and its capabilities can be found here:
https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob
https://docs.microsoft.com/en-us/rest/api/storageservices/service-sas-examples
https://markheath.net/post/upload-azure-blob-storage-sas
https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-requests-to-azure-storage
Printing
Print an uploaded file
Once a the printjob is complete and the payload is uploaded, you can trigger the print job by sending a print request. In this request you can set the final printing properties. The request parameters need to be sent in the body in JSON format.
Request
shell
POST https://printapi.ezeep.com/sfapi/Print/
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
fileid |
string | yes | Id of the uploaded file. See PrepareUpload
|
type |
string | yes | Type of the file. (e.g. txt) |
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 GetPrinterProperties . |
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 . |
properties[paper] |
string | no | Size of the paper. See GetPrinterProperties
|
properties[paperid] |
int | no | Id of of paper size. See GetPrinterProperties
|
properties[color] |
bool | no | Enable color. See GetPrinterProperties
|
properties[duplex] |
bool | no | Enable duplex. See GetPrinterProperties
|
properties[duplexmode] |
int | no | Duplex mode. See GetPrinterProperties
|
properties[orientation] |
int | no | Orientation mode. See GetPrinterProperties
|
properties[copies] |
int | no | Count of copies. See GetPrinterProperties
|
properties[resolution] |
string | no | DPI / quality . See GetPrinterProperties
|
Example request
curl -X POST \
https://printapi.ezeep.com/sfapi/Print/ \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 399' \
-H 'Content-Type: application/json' \
-H 'Host: printapi.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2' \
-d '{
"fileid": "ERI_cf44e7b9-3725-43e6-8ead-edfaec6cfcd2",
"printerid": "86f7288e-9369-47c4-99e7-d9336bfd00f1",
"type": "txt",
"alias": "cool.txt",
"properties": {
"color": false,
"copies": 1,
"duplex": false,
"duplexmode": 1,
"orientation": 1,
"paper": "Auto",
"paperid": 0,
"resolution": "Auto"
},
"printanddelete": false
}'
In the response you will find the job id of the sent print job. You can use this job id to parse the print job status (next step):
{
"jobid": "ezprnds-d000001:HP Un_tpcb_788_7863578#2031753094:4"
}
If the JSON in your request body is formatted incorrectly the following error message will be returned:
{
"code": 1008,
"message": "provided data is invalid ''"
}
Further error messages:
json
{
"code": 806,
"message": "printing failed"
}
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 more or less the same as for Print an uploaded file. But the JSON attribute fileid is replaced by fileurl. Since the file is downloaded in background it’s not unlikely (depending on file’s size) that printing can’t start immediately. In this case you will receive HTTP 412 Precondition failed and the response provides you a fileid you can use for Print an uploaded file.
Request
shell
POST https://printapi.ezeep.com/sfapi/Print/
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
fileurl |
string | yes | URL of the file to print |
type |
string | yes | Type of the file. (e.g. txt) |
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 GetPrinterProperties . |
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 . |
properties[paper] |
string | no | Size of the paper. See GetPrinterProperties
|
properties[paperid] |
int | no | Id of of paper size. See GetPrinterProperties
|
properties[color] |
bool | no | Enable color. See GetPrinterProperties
|
properties[duplex] |
bool | no | Enable duplex. See GetPrinterProperties
|
properties[duplexmode] |
int | no | Duplex mode. See GetPrinterProperties
|
properties[orientation] |
int | no | Orientation mode. See GetPrinterProperties
|
properties[copies] |
int | no | Count of copies. See GetPrinterProperties
|
properties[resolution] |
string | no | DPI / quality . See GetPrinterProperties
|
Example request
curl -X POST \
https://printapi.ezeep.com/sfapi/Print/ \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 399' \
-H 'Content-Type: application/json' \
-H 'Host: printapi.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2' \
-d '{
"fileurl": "https://file-examples-com.github.io/uploads/2017/10/file-sample_150kB.pdf",
"printerid": "86f7288e-9369-47c4-99e7-d9336bfd00f1",
"type": "txt",
"alias": "cool.txt",
"properties": {
"color": false,
"copies": 1,
"duplex": false,
"duplexmode": 1,
"orientation": 1,
"paper": "Auto",
"paperid": 0,
"resolution": "Auto"
},
"printanddelete": false
}'
When printing got started the response gives you the job id of the print job. You can use this job id to parse the print job status (next step):
{
"jobid": "ezprnds-d000001:HP Un_tpcb_788_7863578#2031753094:4"
}
When the file is still downloaded in the background you will get:
json
{
"fileid": "ERI_be20b4d1-d6b8-41ee-8ca8-580905b9b4ed",
"sasUri": ""
}
This fileid should be used for further print requests.
If the JSON in your request body is formatted incorrectly the following error message will be returned:
{
"code": 1008,
"message": "provided data is invalid ''"
}
Further error messages:
json
{
"code": 806,
"message": "printing failed"
}
GetStatus
You can retrieve information on the printjob state with the following request:
GET https://printapi.ezeep.com/sfapi/Status/?:id
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id |
string | yes | The Job identifier. See Print . |
Example request
curl -X GET \
'https://printapi.ezeep.com/sfapi/status/?id=%22WIN-JVEK9G286TL:HP%20Un_tpcb_3468_1291956828#2031753094:4%22#2031753094:4%22' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...' \
-H 'Connection: keep-alive' \
-H 'Host: printapi.ezeep.com' \
-H 'User-Agent: PostmanRuntime/7.15.2'
Example response:
{
"jobpagesprinted": 0,
"jobpagestotal": 1,
"jobposition": 1,
"jobstatus": 129,
"jobstatusstring": "PRINTING|RETAINED|"
}
Status Codes
Status Code | 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 |
These codes are expected and should be handled adequately. Any other code is an (unexpected) error on server side (see Error codes).
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