• Requirements
• Starting
• Endpoints
• User Authentication
  • 1. Navigate user to our authorization endpoint
  • 2. User authenticates via Microsoft, Google, Apple or ezeep Login
  • 3. After successful authentication the user will be redirected to your provided URI with an authorized code
  • 4. With the authorized code, your application can request an access token and request token
• Use Refresh Token
• Get Printers
• Prepare Upload
• Upload file
• Print
• GetStatus
  • Status Codes
• 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. By using the ezeep printer driver, a web portal or an app for smartphone and tablet, users can print as easily as making a phone call.

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 for Azure 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 print job to a cloud connected printer
• Get information on the printjob status

Requirements

• ezeep for Azure administrator account
• Microsoft Azure user account
• your personal ezeep client id

To setup your ezeep administrator account and organization, sign up here

To receive an API key, just contact us: service@ezeep.com

For the full documentation on setting up your ezeep for Azure account, check our web documentation

To see our ezeep classic quick setup guide, visit this link

Starting

The printing workflow requires to

• autenticate the user
• get printers
• prepare upload
• upload a file
• print

Endpoints

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:

1. • Navigate user to our authorization endpoint
2. • User authenticates via Microsoft, Google, Apple or ezeep Login
3. • After successful authentication the user will be redirected to your provided URI with an authorized code
4. • With the authorized code, your application can request an access token and request token

1. Navigate user to our authorization endpoint

From your application navitate 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:

Optional query parameters:

2. User authenticates via Microsoft, Google, Apple or ezeep Login

The user will be prompted to signin window and can chose to sign in with their Microsoft, Google, Apple or ezeep account. If the user has an active session due to a preceding singin, the prompt will be skipped and the user will be redirected directly to the redirect_uri.

3. After successful authentication the user will be redirected to your provided URI with an authorized code

If the user signed in successfully, ezeep takes care of persisting a reference to the login account. The user is redirected to the redirect_uri that was provided in the inital request in 1. with an additional query parameter code appended to the URI. Your application needs to capture this code to trade it for an access token and refresh token.

Examples:

• http://localhost:8080/?code=<authorization_code>
• myapp://callback?code=<authorization_code>

4. With the authorized code, your application can request an access token and request token

Once the pairing code is authorized, you can trade it in for an access token and refresh token. Send a POST request to ezeep’s access token endpoint containing the following x-www-form-urlencoded data:

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

Parameters

Basic authentication scheme is used, meaning the Authorization header value is Basic followed by a space and the base64 encoded client_id and client_secret joined by a colon :. Native clients will not have a secret, in that case the base64 encoded string only contains the client_id followed by a colon :.

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

Parameters

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.

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

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

Parameters:

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 Upload

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

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

Parameters

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

Print

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:

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

GetStatus

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

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

Parameters:

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

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