ZPL Labels |
[This is preliminary documentation and is subject to change.]
ZPL is a Zebra printer specific printer control language we can use to send commands to the printer in raw ZPL byte code (i.e. not as documents or PNG images) to store label images and print labels.
![]() |
---|
ZPL printers from UPS are configured to be incompatible with retail/Purolator Zebra printers so you cannot use the same printer for UPS package labels and Purolator package labels. Retail Zebra (and ZPL compatible) printers should be completely compatible. |
The printer driver model for Vista and later prevents raw text from being sent directly to the printer without calling the Win32 API. The .NET sample applications includes sample code to demonstrate sending ZPL encoded text to the printers: C#, VB.NET
Storing the image contents before printing labels allows the software to just send the ZPL commands for the labels (with a reference to any stored image) and greatly reduces the size of the ZPL needed to print each label. Some Zebra printers will store the images in flash memory, but smaller ones need to be initialized each time the printer is turned on so it is advisable to initialize the printer when your application starts.
If the images have been stored in the ZPL printer's memory then set the LabelType to ZPL. If the images have not been stored in the printer's memory then use ZPLIMAGES instead.
We recommended that the encoded images be retrieved from the web service when the application starts (instead of being hard coded into the application) in case they are updated. The current (uncompressed) image text (from GetZPLInitializationImages(CredentialInfo)) is currently about 120 KB.
This is a helper class to help send ZPL encoded commands directly to the ZPL printer using the Win32 API.
// See http://support.microsoft.com/kb/322091 public class RawDataPrinterHelper { [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] public struct DOCINFO { [MarshalAs(UnmanagedType.LPWStr)] public string pDocName; [MarshalAs(UnmanagedType.LPWStr)] public string pOutputFile; [MarshalAs(UnmanagedType.LPWStr)] public string pDataType; } [DllImport("winspool.Drv", EntryPoint = "OpenPrinterW", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool OpenPrinter(string src, ref IntPtr hPrinter, IntPtr pd); [DllImport("winspool.Drv", EntryPoint = "ClosePrinter", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool ClosePrinter(IntPtr hPrinter); [DllImport("winspool.Drv", EntryPoint = "StartDocPrinterW", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool StartDocPrinter(IntPtr hPrinter, Int32 level, ref DOCINFO pDI); [DllImport("winspool.Drv", EntryPoint = "EndDocPrinter", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool EndDocPrinter(IntPtr hPrinter); [DllImport("winspool.Drv", EntryPoint = "StartPagePrinter", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool StartPagePrinter(IntPtr hPrinter); [DllImport("winspool.Drv", EntryPoint = "EndPagePrinter", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool EndPagePrinter(IntPtr hPrinter); [DllImport("winspool.Drv", EntryPoint = "WritePrinter", SetLastError = true, CharSet = CharSet.Unicode, ExactSpelling = true, CallingConvention = CallingConvention.StdCall)] private static extern bool WritePrinter(IntPtr hPrinter, IntPtr pBytes, Int32 dwCount, ref Int32 dwWritten); public static void SendStringToPrinter(string printerName, string text) { IntPtr pBytes = Marshal.StringToCoTaskMemAnsi(text); Int32 dwCount = text.Length; SendBytesToPrinter(printerName, pBytes, dwCount); Marshal.FreeCoTaskMem(pBytes); } public static void SendBytesToPrinter(string printerName, IntPtr byteCount, Int32 dwCount) { IntPtr hPrinter = default(IntPtr); DOCINFO di = default(DOCINFO); Int32 dwWritten = default(Int32); di.pDocName = "ZPL"; di.pDataType = "RAW"; if (OpenPrinter(printerName.Normalize(), ref hPrinter, (IntPtr)0)) { if (StartDocPrinter(hPrinter, 1, ref di)) { if (StartPagePrinter(hPrinter)) { WritePrinter(hPrinter, byteCount, dwCount, ref dwWritten); EndPagePrinter(hPrinter); } EndDocPrinter(hPrinter); } ClosePrinter(hPrinter); } } }
Make a GetZPLInitializationImages(CredentialInfo) request to get the ZPL encoded images.
CredentialInfo credentials = new CredentialInfo { UserName = "User", Password = "****", ClientID = "0000000" }; ShippingServicesSoapClient client = new ShippingServicesSoapClient("PurolatorWebService"); ZPLInitializationResponse response = client.GetZPLInitializationImages(credentials);
Send the response ZPLCode to the ZPL printer as raw text.
Create an OrderRequest object with the shipment data and the LabelType set to ZPL (if image contents have already been saved to the printer’s memory) or ZPLIMAGES.
CredentialInfo credentials = new CredentialInfo { UserName = "User", Password = "****", ClientID = "0000000" }; OrderRequestV3 orderRequest = new OrderRequestV3 { Credentials = credentials, ShipToAddress = new Address { Name = "Test Customer Name", Add1 = "560 Kings Road", City = "Sydney", StateProv = "NS", PostalCode = "B1S1B8", Country = "CA" }, OrderNumber = "Order-13544364-1", ShipMethod = "GROUND", LabelType = "ZPLIMAGES", ShipDate = DateTime.Today, Packages = new List<RequestPackageV3> { new RequestPackageV3 { PackageID = "PKG-13544364-01", WeightUOM = "LB", Weight = 10.0m, } }.ToArray(), Items = new List<RequestItemV3> { new RequestItemV3 { SKU = "x35135", CustomsDesc = "Documents", Quantity = 2, TotalValue = 10, Currency = "CAD", CountryOfOrigin = "United States", } }.ToArray() };
If the Status is Error (2), then the order data needs to be fixed and resubmitted.
ShippingServicesSoapClient client = new ShippingServicesSoapClient("PurolatorWebService"); OrderResponse orderResponse = client.AddOrder(orderRequest); if (orderResponse.Status == (int)SeverityEnum.Error) { foreach (ResponseMessage message in orderResponse.Messages) { Console.Write(message.Message); } } return orderResponse;
Otherwise send each ZPLCode in the response.Packages collection to the ZPL printer as raw text.
Make a GetLabel(LabelRequest) request with the LabelType set to ZPL,
CredentialInfo credentials = new CredentialInfo { UserName = "User", Password = "****", ClientID = "0000000" }; LabelRequest labelRequest = new LabelRequest { Credentials = credentials, LabelType = "ZPL", OrderNumber = orderNumber, PackageID = packageID, }; // We could have provided the package.TrackingNumber returned from an AddOrder response package instead of using PackageID. LabelResponse response = client.GetLabel(labelRequest);
If the Status is Error (2), then the package was not found or the request was invalid.
Otherwise send the ZPLCode to the ZPL printer as raw text.
This is ZPL code for a bar code:
^XA^PR5,5^LH25,0^FO55,600^BY3^BCN,250,N,N,N,N^FD>;0830351221208070000100331000000000^FS^XZ
This is ZPL code for a label:
^XA^PR5,5^LH25,0^FO5,30^XGR:PCLLOGO.GRF,1,1^FS^FO8,93^GB18,120,23^FS^FO12,107^A0B,20,23^FR^FDFROM/DE^FS^FO43,90^A0N,22,23^FDThe Lighthouse Group, LLC Shipping^FS^FO43,114^A0N,22,23^FD123 Shipping Street^FS^FO43,138^A0N,22,23^FDSuite 1001^FS^FO43,162^A0N,22,23^FDNew York, New York 10020^FS^FO43,186^A0N,22,23^FD(703) 123-4567^FS^FO40,207^GB65,25,25^FS^FO40,211^A0N,22,25^FB65,,,C^FR^FDRef:^FS^FO110,211^A0N,22,23^FDMyRef007^FS^FO8,264^GB18,80,23^FS^FO12,283^A0B,20,23^FR^FDTO/A^FS^FO43,260^A0N,28,29^FDMontreal Canadiens^FS^FO43,294^A0N,28,29^FD1275 St. Antoine Street West^FS^FO43,328^A0N,28,29^FDSuite 99^FS^FO41,362^A0N,33,35^FDMONTREAL, QC H3C5L2^FS^FO43,401^A0N,28,29^FD(514) 790-2525^FS^FO4,473^GB102,26,26^FS^FO4,477^A0N,25,27^FB102,,,C^FR^FDNOTE:^FS^FO111,476^A0N,28,29^FDComment noted.^FS^FO625,420^A0N,117,125^FDE3^FS^FO4,523^GB102,26,26^FS^FO0,527^A0N,25,27^FB102,,,C^FR^FDDATE^FS^FO0,557^A0N,25,29^FB162,,,C^FD5/12/2010^FS^FO334,523^GB131,26,26^FS^FO336,527^A0N,25,27^FB131,,,C^FR^FDPIECES^FS^FO305,557^A0N,25,29^FB191,,,C^FD1 of/de 2^FS^FO569,523^GB225,26,26^FS^FO569,527^A0N,25,27^FB225,,,C^FR^FDWEIGHT/POIDS^FS^FO569,557^A0N,25,29^FB225,,,C^FD75.00 lb^FS^FO0,655^A0B,20,24^FDSD: 3/1/2010^FS^FO55,600^BY3^BCN,250,N,N,N,N^FD>;0830351221208070000100331000060000^FS^FO0,865^A0N,33,43^FB800,,,C^FDPUROLATOR PIN: LHG000010033^FS^FO0,855^A0B,20,24^FDLHG000010033^FS^FO5,890^XGR:SATURDAY.GRF,1,1^FS^FO413,910^A0N,117,125^FDYUL^FS^FO663,910^A0N,61,64^FD07Y^FS^FO5,1035^XGR:DANGER.GRF,1,1^FS^FO30,1200^A0N,22,23^FDFully Regulated as per Shipper's Declaration^FS^FO450,1035^XGR:HEAVY.GRF,1,1^FS^FO400,90^A0N,22,23^FDIf undeliverable, use re-delivery^FS^FO400,114^A0N,22,23^FDlabel to route to: / Si non livrable,^FS^FO400,138^A0N,22,23^FDutilisez l'auto-collant de nouvelle^FS^FO400,162^A0N,22,23^FH^FDlivraison pour l'exp_82dier _85:^FS^FO450,186^A0N,22,23^FDPurolator USA^FS^FO450,210^A0N,22,23^FD1151 Martin Grove Road^FS^FO450,234^A0N,22,23^FDEtobicoke, ON^FS^XZ
The label was based on the following information:
FROM/DE | TO/A |
The Lighthouse Group, LLC Shipping | Montreal Canadiens |
WorldPak User | Wayne Gretzky |
123 Shipping Street | 1275 St. Antoine Street West |
Suite 1001 | Suite 99 |
New York, New York 10020 | MONTREAL, QC H3C5L2 |
703 123-4567 | (514) 790-2525 |
NOTE | Comment noted. |
Sort code | E3 |
DATE | 5/12/2010 |
PIECES | 1 of/de 2 |
WEIGHT/POIDS | 75.00 lb |
SD | 3/1/2010 |
PIN | LHG000010033 |
AirportCode | YUL |
Fully regulated, Saturday delivery |
This is ZPL code for a single image (the Purolator logo):
~DGR:PCLLOGO,02295,045,000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 000000000001E07FFFF003FFFC0000000000000000000000000000000000000000000000000000000000000000 00000000000FE07FFFE003FFFFF000000000000000000000000000000000000000000000000000000000000000 00000000001FC0FFFFE007FFFFFE00000000000000000000000000000000000000000000000000000000000000 00000000003FC0FFFFC007FFFFFF00000000000000000000000000000000000000000000000000000000000000 00000000007F81FFFFC00FFFFFFF80000000000000000000000000003FE000000000007FC00000000000000000 0000000000FF81FFFF800FFFFFFF80000000000000000000000000007FE00000000000FF800000000000000000 0000000000FF03FFFF801FFFFFFFC000000000000000000000000000FFC00000000001FF800000000000000000 0000000000FF03FFFF001FFC3FFFC000000000000000000000000001FFC00000000003FF000000000000000000 0000000001FE07FFFF003FF803FFC000000000000000000000000003FF800000000007FF000000000000000000 0000000001FE07FFFF003FF801FFC000000000000000000000000003FF800000000007FF000000000000000000 0000000003FC07FFFE007FF001FFC000000000000000000000000003FF00000000000FFE000000000000000000 0000000003FC0FFFFE007FF001FFC000000000000000000000000007FF00000000000FFE000000000000000000 0000000007F80FFFFC00FFE001FF8000000000000000000000000007FE00000000000FFC000000000000000000 0000000007F81FFFFC00FFE001FF83FF801FFC07FC0FC001FFF0000FFE000FFFE003FFFFF0001FFF0000FF81F8 000000000FF81FFFF800FFC003FF87FF001FF807FC3FC00FFFFC000FFC00FFFFF003FFFFF0007FFFC000FF87F8 000000000FF03FFFF801FFC003FF07FF003FF80FF8FF803FFFFE001FFC03FFFFF807FFFFE003FFFFE001FF0FF0 000000001FF03FFFF001FF8007FF0FFE003FF00FF9FF807FFFFF001FF807FFFFFC07FFFFE007FFFFF001FF3FF0 000000001FE07FFFF003FF8007FF0FFE007FF01FFBFF01FFFFFF003FF807FFFFFC0FFFFFC01FFFFFF003FF7FE0 000000003FE07FFFE003FF000FFE0FFC007FE01FFFFF03FFFFFF003FF80FFFFFFC0FFFFFC03FFFFFF803FFFFE0 000000003FC0FFFFE007FF001FFC1FFC00FFE03FFFFE07FFFFFF807FF00FFCFFFC0FFFFF807FFFFFF807FFFFC0 000000007FC0FFFFC007FE003FFC1FF800FFC03FFFFE0FFE07FF807FF01F003FFC01FFE000FFF07FF807FFFFC0 000000007F81FFFFC00FFE00FFF83FF801FFC03FFFFC1FFC07FF80FFE018001FFC01FFC001FFC07FF807FFFF80 000000007F81FFFF800FFE07FFF03FF001FFC07FFF803FF803FF80FFE000001FFC01FF8003FF803FF80FFFF000 00000000FF03FFFF801FFFFFFFE07FF003FF807FFC007FF003FF81FFC000001FFC03FF8007FF003FF80FFF8000 00000000FF03FFFF801FFFFFFFC07FE003FF80FFF800FFE003FF81FFC000001FF803FF800FFE003FF81FFF0000 00000001FE03FFFF003FFFFFFF80FFE007FF00FFF001FFC007FF01FF800003FFF807FF001FFC003FF01FFE0000 00000001FE07FFFF003FFFFFFE00FFE007FF01FFE001FF8007FF03FF8000FFFFF807FF001FF8007FF03FFC0000 3FFFFF03FE07FFFE007FFFFFFC01FFC00FFE01FFC003FF8007FF03FF0007FFFFF007FE003FF8007FF03FF80000 7FFFFF03FC0FFFFE007FFFFFF001FFC00FFE03FF8007FF000FFE07FF001FFFFFF00FFE007FF0007FF07FF00000 7FFFFE07FC0FFFFC007FFFFF8003FF800FFC03FF8007FF000FFE07FE007FFFFFE00FFC007FF000FFE07FF00000 3FFFFE07F81FFFFC00FFFFE00003FF801FFC07FF000FFE000FFE0FFE01FFFFFFE01FFC00FFE000FFE0FFE00000 1FFFFC0FF81FFFF800FFC0000007FF001FF807FF000FFE001FFC0FFC03FFFDFFC01FF800FFE001FFC0FFE00000 0FFFFC0FF03FFFF801FFC0000007FF003FF80FFE001FFC001FFC1FFC07FF81FFC03FF800FFC001FFC1FFC00000 07FFF81FF03FFFF001FF80000007FE003FF00FFE001FFC003FF81FFC0FFE01FF803FF001FFC003FF81FFC00000 03FFF81FE07FFFF003FF8000000FFE007FF01FFC001FF8007FF03FF81FF803FF807FF001FFC003FF81FF800000 01FFF01FE07FFFE003FF0000000FFC007FE01FFC003FF8007FF03FF83FF003FF007FE001FF8007FF03FF800000 00FFF03FC0FFFFE007FF0000001FFC00FFE01FF8003FF800FFE07FF07FF007FF00FFE003FF800FFE03FF000000 007FE03FC0FFFFC007FE0000001FFC01FFE03FF8003FF801FFC07FF07FE007FE00FFE003FF800FFE07FF000000 003FE07F80FFFFC00FFE0000001FFC01FFC03FF0003FF801FFC0FFE0FFE00FFE00FFC003FF801FFC07FE000000 001FE07F81FFFFC00FFE0000003FFC07FFC07FF0003FF807FF80FFE0FFC01FFE01FFE003FF803FF80FFE000000 000FC0FF01FFFF801FFC0000003FFE1FFF807FE0003FF80FFF00FFC0FFE03FFC01FFE003FF80FFF00FFC000000 0007C0FF03FFFF801FFC0000003FFFFFFF80FFE0003FFC3FFE01FFC1FFE0FFFC01FFFF03FFC1FFE01FFC000000 000381FF03FFFF003FF80000003FFFFFFF00FFC0003FFFFFFC01FF81FFFFFFF803FFFF03FFFFFFC01FF8000000 000181FE07FFFF003FF80000003FFFFFFF01FFC0003FFFFFF003FF81FFFFFFF803FFFE03FFFFFF803FF8000000 000003FE07FFFE003FF00000003FFFFFFE01FF80003FFFFFE003FF01FFFFFFF003FFFE01FFFFFE003FF8000000 000003FC0FFFFE007FE00000003FFFF3FE03FF80001FFFFFC007FF01FFFFFFF003FFFC01FFFFFC007FF0000000 000007FC0FFFFC007FE00000003FFFC7FE03FF00000FFFFF0007FE00FFFF3FE001FFFC00FFFFF0007FE0000000 000007F81FFFF000FF800000001FFF07FC07FE000007FFFC000FFC007FFC3FE000FFF8007FFFC000FFC0000000 00000FF81FFFC000FC000000000FFC0FFC07F0000001FFC0000FC0003FE07FE0007FF0001FFE0000FE00000000 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000