Use the SendFileToPrinter API for Your Cloud-Based Printing Needs

Use the SendFileToPrinter API for Your Cloud-Based Printing Needs

Why use the SendFileToPrinter API?

Zebra Data Services has recently released a cloud-based REST API for Zebra Print DNA printers featuring our powerful Link-OS operating system. It is called SendFileToPrinter API. This is good news for developers who want to take advantage of cloud-based printing without worrying about how to connect the printers securely to the cloud. The SendFileToPrinter API allows developers to send content quickly, easily and securely in one file to a Print DNA printer via the powerful Zebra Data Services platform*.

Here are some of the advantages of the SendFileToPrinter API.

  1. The SendFileToPrinter is a REST API that is language & platform agnostic, which means it can be used with any programming languages on any platform, because it is simply a matter of a HTTPS Multipart POST request. You simply choose the programming language and platform that you are familiar or comfortable with when using this API.
  2. The connection from your printer to Zebra Data Services cloud is secured through SSL/TLS. There is no need to reinvent the wheel to create a secured connection yourself. You can be assured that your printer is safely and securely connected to the Zebra Data Services cloud.
  3. Since it is cloud-based, you can print labels and receipts or send content, up to 10 MB in size, in a file to any connected Print DNA printer. There is no need to tether a printer through USB or Bluetooth to a computer or a mobile device. This provides great flexibility for your application.

What can the SendFileToPrinter API do?

This SendFileToPrinter API is unidirectional. It is a simple, yet very powerful API. It can be used to send a wide variety of content to the printer, including commands found in the ZPL Programming Guide*. For example, you can use this API to print labels or receipts by sending the ZPL format commands in a file format to the printer. You can use this API to download objects, such as fonts, graphics, or Wi-Fi® certificates, in a file format to the printer. This API can also be used to configure the printer by sending Set-Get-Do (SGD) configuration commands or JSON configuration strings in a file format to the printer. You can send any allowed content to the printer through this API. You have the option to send the content to one or multiple printers in one API call.

If you are familiar with Zebra ZPL format commands, you can create the label or receipt with ZPL and send the ZPL content in a file straight away with this API to a printer to print. If you are unfamiliar with ZPL, then you can use ZebraDesigner for Developers 3, a free tool, to create your design and generate the ZPL for you.

Since the SendFileToPrinter is a unidirectional API, do not expect to use this API to retrieve anything out from the printer. For example, you cannot retrieve the printer settings with this API by sending the related SGD or JSON commands, because this API does not return such content. However, the caller of this API gets acknowledged on whether the API call is successful or not through the response each time.

How to get started?

To use the SendFileToPrinter API, you need an API key and a Print DNA printer registered with the Zebra Data Services cloud platform. Here are the How-To articles to help you get started.

Apply for Zebra Developer Account and API Key

Getting Started with Zebra Data Services – A step-by-step guide on how to open a developer account, how to add API packages to your account, how to add an app and generate the API key, etc. on the Zebra Data Services developer portal. 

Notes:

  1. To gain access to the SendFileToPrinter API, you'll need to add a SendFileToPrinter package (Free or PPC) and select the package in your account when you create an app to generate the API key.
  2. Using the same API key for both Free and Pay Per Call (PPC) packages are treated as an API call to both packages at the same time. It is recommended to use a separate API key for the SendFileToPrinter (Free) and SendFileToPrinter (PPC) packages.

Printer Setup

Printer Setup Guide – A step-by-step guide on how to configure the network connection, the Weblink endpoint to the Zebra Data Services platform, and how to get the tools required to send the JSON configuration file to a Print DNA printer. For more details about Weblink, refer to the Using Weblink section in ZPL Programming Guide

Use the following JSON string for the Weblink configuration of your Print DNA printer. Replace the value of the query parameter r (The r must be in lowercase) with the printer enrollment code, an auto-generated code by clicking on Add Device button on My Devices page at https://developer.savanna.zebra.com/my-devices. To access My Devices page, you'll need to log into your developer account.

{}{
"weblink.logging.max_entries":"500",
"weblink.ip.conn1.location":"https://savanna-device.zpc.zebra.com/weblink/connect?r=a6f47ecf23e841c8f5c94f82c3d2ede8",
"device.reset":"1"
}

The above JSON string can be sent to the printer as a file by using the Printer Setup Utilities for Windows, Android or iOS.

Notes:

  1. There should be no space between the braces in the above JSON string, i.e. no spaces in "{}{".
  2. You can have two Weblinks configured at the same time on a printer, i.e. weblink.ip.conn1.location and weblink.ip.conn2.location. However, they cannot point to the same Weblink URL. If they point to the same Weblink URL, they will cancel each other’s connection and cause a ping-pong effect. Refer to the Using Weblink section in ZPL Programming Guide for additional info.
  3. Zebra Data Services only supports one Weblink connection per Print DNA printer at a time. You can only use one Weblink on the printer to connect to Zebra Data Services. The other Weblink can be used for other services.
  4. Make sure the previous Weblink configuration is not unintentionally overwritten. The following commands can be used to check if the Weblink configurations are already in use, before overwriting either one of them.
{}{
"weblink.ip.conn1.location":null,
"weblink.ip.conn2.location":null
}
! U1 getvar "weblink.ip.conn1.location"
! U1 getvar "weblink.ip.conn2.location"

Unregister and disconnect the printer

{}{
"weblink.ip.conn1.location":"",
"device.reset":"1"
}

By passing an empty string ("") to the weblink.ip.conn1.location, the above JSON configuration string will remove the Weblink URL and disconnect the Weblink connection from weblink.ip.conn1.location. You can do the same for weblink.ip.conn2.location, if it is configured for connecting to the Zebra Data Services cloud platform. Note: When removing or reconfiguring a Weblink URL, please be cautious to not impact or disrupt other applications use of the Weblink connection.

Test Print

Once you complete the steps in Getting Started with Zebra Data Services and Printer Setup Guide, you can send the following HTTPS request in cURL to the printer. It will print out “Hello World” on a label, assuming you have the “^XA ^FO50,50^ADN,36,20^FDHello World^FS ^XZ” ZPL string (without the double quotes) stored in a file called HelloWorld.txt. Note: You'll need to replace the API key and the tenant account number in the request header and the printer’s serial number of the sn key-value pair in the request body with your values in order to see the action. The tenant account number can be retrieved from the Tenant Service.

$ curl -H "apikey: yourApiKey" -H "tenant: yourTenantAccountNumber" \
       -F "sn=printerSerialNumber" -F "zpl_file=@HelloWorld.txt" \
       https://api.zebra.com/v2/devices/printers/send

Note: If you want to send the HelloWorld.txt file to more than one printer, you simply add additional sn key-value pairs in the request body. The following cURL, for example, will print “Hello World” from two printers.

$ curl -H "apikey: yourApiKey" -H "tenant: yourTenantAccountNumber" \
       -F "sn=printerSerialNumber_1" \
       -F "sn=printerSerialNumber_2" -F "zpl_file=@HelloWorld.txt" \
       https://api.zebra.com/v2/devices/printers/send

If you prefer, you can also use Postman instead of cURL to do the test print.

NOTES:

  1. The maximum size of the file supported by the SendFileToPrinter API is 10MB at this moment. If the file size is larger than 10MB, unexpected error may occur.
  2. Only one file can be sent at a time. If multiple files are specified with multiple zpl_file key-value pairs in the request body, only one file is accepted and sent. All the other files in the request will be ignored.
  3. The file content of ZPL label, receipt format, or downloadable object must be complete. It cannot be divided into partial formats in multiple files to send, i.e. concatenating multiple files is not supported.
  4. It is recommended not to call the API to send file or content to the printer while the printer is updating its operating system, as the delivery of the file or the content is not guaranteed during the printer operating system update.

*Max file size is 10 MB

Steven Si

PrintFromCloud - A JavaScript example demonstrates how to use the SendFileToPrinter API to print labels and receipts from anywhere to any Link-OS printers connected to the Zebra Data Services cloud platform.