ZPLPrinter Web API for Docker

REST API to Convert, Preview & Render ZPL to PNG, JPG & PDF!

  Download   Buy

Key Features

  Convert raw ZPL to PNG, JPG, PCX, GRF & PDF
  Preview ZPL commands without wasting real labels!
  High Quality & Accuracy ZPL Rendering
  ZPL Parsing from Raw & Base64 Strings
  International Text & Barcodes Support

Zebra and ZPL are registered trademarks of ZIH Corp.
ZPLPrinter Web API for Docker
is not made by or endorsed by Zebra.

Convert, Preview & Render ZPL commands to PNG, JPG & PDF from Docker!

ZPLPrinter Web API for Docker allows you to Convert, Preview and Render raw ZPL (Zebra Programming Language) commands to well known image and document formats like PNG, JPG, PCX, GRF (ASCII Hex) & PDF from Any Development Platform and Programming Languages (.NET, Java, PHP, Javascript, Python, Ruby, and more!)

ZPL Virtual Printer ZPL Viewer ZPL Parser ZPL Converter ZPL Emulator ZPL2PNG ZPL2JPG ZPL2PCX ZPL2GRF ZPL2PDF ZPL2Image ZPL Docker ZPL Web API

Features at a Glance

 Convert ZPL to Images & Docs

Use ZPLPrinter Web API for Docker to easily convert ZPL commands to PNG, JPG, PCX, Zebra GRF ASCII hex & PDF formats by writing simple C# or VB.NET code.

 Preview ZPL Commands

Need to test ZPL commands and don't have a real Zebra printer device? No problem! Use ZPLPrinter Web API for Docker to preview ZPL commands without wasting any single label!

 High Accuracy ZPL Render

ZPLPrinter Web API for Docker renders ZPL commands generating high quality output by reproducing built-in and resident ZPL fonts for texts and barcodes with high accuracy.

 ZPL Parsing & Processing

ZPLPrinter Web API for Docker can parse ZPL commands from a .NET string, .NET Stream or physical file. It can detect UTF-8 encoding automatically. Most of the ZPL Formatting and Control Commands are supported.

 International Text Support

ZPLPrinter Web API for Docker can render ZPL commands for international text including Latin, EMEA, Asian and RTL languages like German, French, Italian, Spanish, Portuguese, Swedish, Danish, Polish, Cyrillic, Greek, Chinese, Japanese, Korean, Arabic, Hebrew, and more.

 Barcode Symbologies Support

ZPLPrinter Web API for Docker can generate most of the linear (1D), postal, composite, stacked and 2D barcodes shipped with real Zebra printer devices.

 Colored Label Simulation

ZPLPrinter Web API for Docker can be configured to convert ZPL to PNG, JPG & PDF formats simulating a color ribbon (for label items) and a background color label. Black & White 1bpp is also supported through PCX format.

 Custom ZPL Output Rotation

Besides ZPL rotation command, ZPLPrinter Web API for Docker can be configured to rotate ZPL outputs to 90, 180 & 270 clockwise degrees.

 Custom Background Image

ZPLPrinter Web API for Docker allows you to render ZPL commands on a specified Background Image (in PNG or JPG formats) which can be set from a system file path, URL, Base64 string or a binary buffer (Byte Array).

Overview

Designed by following some of the REST principles, ZPLPrinter Web API for Docker responds to a simple HTTP POST by specifying the ZPL commands and printer settings through a JSON object in the request body, returning the output rendering in the image or document format specified through the Accept header.

Help Doc Topics


Download and run ZPLPrinter Web API for Docker

ZPLPrinter Web API for Docker is available at Docker Hub registry.

  • To pull/download the Docker image, please type the following from a Terminal:

    docker pull neodynamic/zplprinterwebapi:1.1
  • To run the Docker image, please type the following from a Terminal:

    docker run -it --rm -p 8080:80 neodynamic/zplprinterwebapi:1.1

How To Use It - Basic Sample

The following source code invokes the ZPLPrinter Web API for Docker to generate a PNG image for the specified ZPL Commands. For more advanced settings please refer to the ZPLPrintJob JSON Object

                    
curl -X POST "http://localhost:8080/ZPLPrinter" \
     -H  "Accept: image/png" \
     -H  "Content-Type: application/json" \
     -d "{\"zplCommands\":\"^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ\"}" \
     --output label.png
                        
                
                    
$data = array(
  'zplCommands' => '^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ'
);

$options = array(
  'http' => array(
    'method'  => 'POST',
    'content' => json_encode( $data ),
    'header' =>  "Content-Type: application/json\r\n" .
                "Accept: image/png\r\n"
    )
);

$context  = stream_context_create( $options );
$url = 'http://localhost:8080/ZPLPrinter';
$response = file_get_contents( $url, false, $context );
file_put_contents('label.png', $response);
                        
                
                    
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://localhost:8080/ZPLPrinter")

header = {'Accept':'image/png', 'Content-Type': 'application/json'}

data = {zplCommands: '^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ'}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, header)
request.body = data.to_json

response = http.request(request)

open('/tmp/label.png', 'wb' ) { |file|
    file.write(response.body)
}
                        
                
                    
import requests
import json

url = "http://localhost:8080/ZPLPrinter"

jsondata = json.dumps( {"zplCommands": "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ"} )

headers = {
    'content-type': "application/json",
    'accept': "image/png"
    }

response = requests.request("POST", url, data=jsondata, headers=headers)

if response.status_code == 200:
    with open("label.png", 'wb') as f:
        f.write(response.content)

                        
                
                    
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $server_endpoint = "http://localhost:8080/ZPLPrinter";
my $req = HTTP::Request->new(POST => $server_endpoint);
$req->header('content-type' => 'application/json');
$req->header('accept' => 'image/png');

my $post_data = '{ "zplCommands" : "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ" }';

$req->content($post_data);

my $resp = $ua->request($req);
open FILEHANDLE, ">label.png";
print FILEHANDLE $resp->{_content};
close FILEHANDLE;
                        
                
                    
CloseableHttpClient client = HttpClients.createDefault();
HttpPost httpPost = new HttpPost("http://localhost:8080/ZPLPrinter");
 
String json = "{\"zplCommands\" : \"^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ\"}";
StringEntity entity = new StringEntity(json);
httpPost.setEntity(entity);
httpPost.setHeader("Accept", "image/png");
httpPost.setHeader("Content-type", "application/json");
 
CloseableHttpResponse response = client.execute(httpPost);
HttpEntity entity = response.getEntity();
if (entity != null) {
    try (FileOutputStream outstream = new FileOutputStream(new File("label.png"))) {
        entity.writeTo(outstream);
    }
}
client.close();     
                        
                
                    
string DATA = "{\"zplCommands\" : \"^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ\"}";

var request = (HttpWebRequest)WebRequest.Create("http://localhost:8080/ZPLPrinter");
request.Method = "POST";
request.ContentType = "application/json";
request.ContentLength = DATA.Length;
request.Accept = "image/png";

using (var requestWriter = new StreamWriter(request.GetRequestStream(), System.Text.Encoding.ASCII)){
    requestWriter.Write(DATA);
}

var webResponse = request.GetResponse();
using (var stream = webResponse.GetResponseStream())
using (var fileStream = File.OpenWrite("label.png"))
{
    var bytes = new byte[4096];
    var read=0;
    do
    {
        if (stream == null) {continue;}
        read = stream.Read(bytes, 0, bytes.Length);
        fileStream.Write(bytes, 0, read);
    } while (read != 0);
}

                        
                
                    
var data = JSON.stringify({
    "zplCommands": "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ"
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
    if (this.readyState === 4) {
    console.log(this.responseText);
    }
});

xhr.open("POST", "http://localhost:8080/ZPLPrinter");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("accept", "image/png");

xhr.send(data);
                        
                
                    
var request = require('request');
 
var headers = {
    'Accept': 'image/png',
    'Content-Type': 'application/json'
}
 
var options = {
    url: 'http://localhost:8080/ZPLPrinter',
    method: 'POST',
    headers: headers,
    json: {"zplCommands": "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ"}
}
 
request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
})
                        
                

The ZPLPrintJob Object

The ZPLPrintJob is a JSON Object that specifies the ZPL commands as well as the printer settings like DPI, Label Width & Height, Ribbon Color, Background Image & Color, and more.

ZPLPrintJob JSON

{
  "dpi": 203,
  "zplCommands": "^XA^FO30,40^ADN,36,20^FDHello World^FS^FO30,80^BY4^B3N,,200^FD12345678^FS^XZ",
  "zplCommandsCodePage": 850,
  "isZplCommandsBase64": false,
  "renderOutputRotation": 0,
  "antiAlias": true,
  "labelWidthInchUnit": 4,
  "labelHeightInchUnit": 6,
  "labelBackColorHex": "#ffffff",
  "ribbonColorHex": "#000000",
  "backgroundImageBase64": "",
  "thumbnailSizePixelUnit": 0,
  "pdfMetadataAuthor": "",
  "pdfMetadataCreator": "",
  "pdfMetadataProducer": "",
  "pdfMetadataSubject": "",
  "pdfMetadataTitle": ""
}    
Attributes
dpi integer($int32) default: 203
The printer resolution in DPI (Dots per inch) value. Valid values are: 152 (6 dpmm), 203 (8 dpmm), 300 (12 dpmm) or 600 (24 dpmm).
zplCommands string default: empty REQUIRED
The ZPL commands to be processed. The string containing the ZPL commands is converted to an array of bytes prior processing it. That conversion will use CodePage or Encoding 850 (Latin Character Set).
zplCommandsCodePage integer($int32) default: 850
The Encoding or CodePage of the ZPL string content. Default is CodePage 850 (Latin Character Set). List of valid CodePage numbers...
isZplCommandsBase64 boolean default: false
Whether the specified ZPL Commands string is in Base64 format. Useful for ZPL commands containing non-readable/printable chars.
renderOutputRotation integer($int32) default: 0
The rotation for the output rendering process. Default is 0 (None). Valid values are: 0 (None), 90 (Clockwise), 180, 270 (Clockwise).
antiAlias boolean default: true
Whether anti-aliasing rendering is enabled.
labelWidthInchUnit integer($float) default: 4
The default label width in Inch units.
labelHeightInchUnit integer($float) default: 6
The default label height in Inch units.
labelBackColorHex string default: #ffffff
The label's background color in hex notation. Default is #fff (White). The Color Hex notation is as follows #[AA]RRGGBB where A, R, G, B refers to Aplha, Red, Green and Blue pixels. The following options would also be valid: #RGB or #ARGB (in this short format all channel values must be the same), #RRGGBB or #AARRGGBB. Note: # is optional and can be omitted.
ribbonColorHex string default: #000000
The label's ribbon color in hex notation. Default is #000 (Black). The Color Hex notation is as follows #[AA]RRGGBB where A, R, G, B refers to Aplha, Red, Green and Blue pixels. The following options would also be valid: #RGB or #ARGB (in this short format all channel values must be the same), #RRGGBB or #AARRGGBB. Note: # is optional and can be omitted.
backgroundImageBase64 string default: empty
The label's custom background image from a string in Base64 format. Image format mut be PNG or JPG.
thumbnailSizePixelUnit integer($int32) default: 0
The thumbnail size for the output rendering in Pixel unit. Default is 0 (zero) which means thumbnail generation is disabled.
pdfMetadataAuthor string default: empty
The PDF Metadata Author attribute. Used if Accept header is specified to PDF format.
pdfMetadataCreator string default: empty
The PDF Metadata Author attribute. Used if Accept header is specified to PDF format.
pdfMetadataProducer string default: empty
The PDF Metadata Producer attribute. Used if Accept header is specified to PDF format.
pdfMetadataSubject string default: empty
The PDF Metadata Subject attribute. Used if Accept header is specified to PDF format.
pdfMetadataTitle string default: empty
The PDF Metadata Title attribute. Used if Accept header is specified to PDF format.

The Accept Header

The desired output rendering format must be specified through the Accept header. The supported formats are the following:

Accept Description
image/png Returns the first rendered label in PNG format. If the specified commands generate more than one label, then you should specify image/png+json or image/png+zip values instead.
image/jpeg Returns the first rendered label in JPEG/JPG format. If the specified commands generate more than one label, then you should specify image/jpeg+json or image/jpeg+zip values instead.
application/pdf Returns all the rendered labels as a single PDF document. The PDF file will contain as many pages as rendered labels.
image/vnd.zbrush.pcx Returns the first rendered label in PCX format. If the specified commands generate more than one label, then you should specify image/vnd.zbrush.pcx+json or image/vnd.zbrush.pcx+zip values instead.
text/plain Returns the first rendered label in Zebra GRF ASCII Hex format. If the specified commands generate more than one label, then you should specify text/plain+json or text/plain+zip values instead.
image/png+json Returns all the rendered labels as a JSON Array containing each label in Base64 PNG Data URI scheme. The returned JSON Object will have this structure: {labels:["data:image/png;base64,<BASE64-STRING>", "data:image/png;base64,<BASE64-STRING>", ... ]}
image/jpeg+json Returns all the rendered labels as a JSON Array containing each label in Base64 JPEG Data URI scheme. The returned JSON Object will have this structure: {labels:["data:image/jpeg;base64,<BASE64-STRING>", "data:image/jpeg;base64,<BASE64-STRING>", ... ]}
application/pdf+json Returns all the rendered labels as a JSON Array containing a single PDF in Base64 Data URI scheme. The PDF file will contain as many pages as rendered labels. The returned JSON Object will have this structure: {labels:["data:application/pdf;base64,<BASE64-STRING>"]}
image/vnd.zbrush.pcx+json Returns all the rendered labels as a JSON Array containing each label in Base64 PCX Data URI scheme. {labels:["data:image/vnd.zbrush.pcx;base64,<BASE64-STRING>", "data:image/vnd.zbrush.pcx;base64,<BASE64-STRING>", ... ]}
text/plain+json Returns all the rendered labels as a JSON Array containing each label in Base64 Zebra GRF ASCII Hex Data URI scheme. The returned JSON Object will have this structure: {labels:["data:text/plain;base64,<BASE64-STRING>", "data:text/plain;base64,<BASE64-STRING>", ... ]}
image/png+zip Returns all the rendered labels as a ZIP file containing each label in PNG format. Each file name is named to Label_01.png, Label_02.png, etc.
image/jpeg+zip Returns all the rendered labels as a ZIP file containing each label in JPEG/JPG format. Each file name is named to Label_01.jpg, Label_02.jpg, etc.
application/pdf+zip Returns all the rendered labels as a ZIP file containing a single PDF. The PDF file will contain as many pages as rendered labels. Label_01.pdf
image/vnd.zbrush.pcx+zip Returns all the rendered labels as a ZIP file containing each label in PCX format. Each file name is named to Label_01.pcx, Label_02.pcx, etc.
text/plain+zip Returns all the rendered labels as a ZIP file containing each label in Zebra GRF ASCII Hex format. Each file name is named to Label_01.grf, Label_02.grf, etc.

Errors

Conventional HTTP response codes will indicate the success or failure of an API request. Upon an error, the ZPLPrinter Web API will return one of the following 'error' responses.

HTTP Status Code Content-type Description
500
applications/json ProblemDetails Object
{
  "type": "string",
  "title": "string",
  "status": 500,
  "detail": "string",
  "traceId": "string"
}
An unexpected error occurred in our code while processing the specified ZPLPrinterJob. Please contact our support if you encounter this error.

ZPL Commands Support

ZPLPrinter Web API for Docker supports most of the ZPL formatting and control commands. The following table lists the supported commands as well as the ones which are under work. Not listed or unsupported commands will be skipped in the parsing stage.

IMPORTANT NOTE
Barcode symbols, particularly 2D-type like QR Code, Data Matrix, Aztec Code, Maxicode..., might look different to the one printed by a real printer because ZPLPrinter Web API for Docker leverages on its own barcode encoder. However, this does not mean that the rendered barcodes will not be readable at all.
Status ZPL Command Comments
^A Scalable/Bitmapped Font
^A@ Use Font Name to Call Font .FNT extension is not supported
^B0 Aztec Bar Code Parameters ECICs and Structured Appended format are not supported
^B1 Code 11 Bar Code
^B2 Interleaved 2 of 5 Bar Code
^B3 Code 39 Bar Code
^B5 Planet Code bar code
^B7 PDF417 Bar Code
^B8 EAN-8 Bar Code
^B9 UPC-E Bar Code
^BA Code 93 Bar Code
^BC Code 128 Bar Code (Subsets A, B, and C)
^BD UPS MaxiCode Bar Code
^BE EAN-13 Bar Code
^BF MicroPDF417 Bar Code
^BI Industrial 2 of 5 Bar Codes
^BJ Standard 2 of 5 Bar Code
^BK ANSI Codabar Bar Code
^BL LOGMARS Bar Code
^BM MSI Bar Code
^BO Aztec Bar Code Parameters ECICs and Structured Appended format are not supported
^BP Plessey Bar Code
^BQ QR Code Bar Code Model 1, Mask value and Data Encoding Switches are not supported
^BR GS1 Databar
^BS UPC/EAN Extensions
^BU UPC-A Bar Code
^BX Data Matrix Bar Code Quality Level < 200 is not supported
^BY Bar Code Field Default
^BZ POSTAL Bar Code
^CC Change Caret
^CD Change Delimiter
^CF Change Alphanumeric Default Font
^CI Change International Font/Encoding Character remapping is not supported
^CT Change Tilde
^CW Font Identifier
^DF Download Format
~DG Download Graphics
~DU Download Unbounded TrueType Font
~DY Download Objects AR-compressed format and bitmap, .pcx, .nrd, .pac, .wml, .htm, .get extensions are not supported
~EG Erase Download Graphics
^FB Field Block
^FC Field Clock Planned for vNext...
^FD Field Data
^FH Field Hexadecimal Indicator
^FM Multiple Field Origin Locations Planned for vNext...
^FN Field Number
^FO Field Origin
^FP Field Parameter
^FR Field Reverse Print
^FS Field Separator
^FT Field Typeset
^FV Field Variable
^FW Field Orientation
^FX Comment
^GB Graphic Box
^GC Graphic Circle
^GD Graphic Diagonal Line
^GE Graphic Ellipse
^GF Graphic Field
^GS Graphic Symbol
^ID Object Delete
^IL Image Load
^IM Image Move
^IS Image Save
~JR Power On Reset
^LH Label Home
^LL Label Length
^LR Label Reverse Print
^LS Label Shift
^LT Label Top
^MC Map Clear
^MU Set Units of Measurement
^PA Advanced Text Properties
^PM Printing Mirror Image of Label
^PO Print Orientation
^PQ Print Quantity
^PW Print Width
^SF Serialization Field Planned for vNext...
^SN Serialization Data Planned for vNext...
^TB Text Blocks
^TO Transfer Object Planned for vNext...
~WC Print Configuration Label
^XA Start Format
^XF Recall Format
^XG Recall Graphic
^XZ End Format

Licensing

On-Premise - Full Deployment Control

ZPLPrinter Web API is licensed for Private On-Premise environments giving you full control on the infrastructure where our product will run on. Please refer to Licensing model and prices...

 License Registration

When you buy a commercial license of ZPLPrinter Web API for Docker, you are provided with license information (LicenseOwner & LicenseKey) to register the product. The license information must be specified to the Docker image as environment variables as folows:

docker run -it --rm -e "LICENSE_OWNER=YOUR-COMPANY-NAME" -e "LICENSE_KEY=YOUR_KEY" -p 8080:80 neodynamic/zplprinterwebapi:1.1

Evaluation Mode

The Trial Version of ZPLPrinter Web API for Docker is fully functional and has no expiry date. However, while in TRIAL mode, the output rendering has the following limitations:

  • Any text that uses the Resident fonts (i.e. font names A, B, C, D, E, F, G, GS, H, 0-zero, P, Q, R, S, T U, V and TT0003M_) any chars which byte value is greater than dec 127 (hex 7F) will be replaced by an X. If you want to see how a text will look like before purchasing a license then contact our support team.
  • A TRIAL stamp will be rendered at the top of the rendering output.

Change Log

  • 1.1 2020-02-06
    • Fixed! Codabar (^BK) data encoding.
    • Fixed! Wrong text rendering when specifying right text alignment for Field Block (^FB).

  • 1.0 2020-01-21
    • New! Initial release.