How to convert BarTender files to ZPL
To convert a BarTender file, send its bytes as the body of a POST request to /api/v2/convert/btw/to/zpl. The btw source reads both .btw documents and .btc components.
curl -X POST "https://api.labelzoom.com/api/v2/convert/btw/to/zpl?dpi=203" \ -H "Authorization: Bearer API_KEY" \ -H "Content-Type: application/octet-stream" \ --data-binary @label.btw \ --output label.zplReplace API_KEY with your API key. To get a PDF or an image instead, change the target, such as /btw/to/pdf.
Send the file
Section titled “Send the file”Send the file’s bytes with Content-Type: application/octet-stream. If your client can send only text, send the file as base64 with Content-Type: text/plain. Send the file with --data-binary; -d corrupts binary data, and a file converted to text before it’s sent can’t be read.
Fill data sources
Section titled “Fill data sources”To fill the label’s data sources, pass data with one object per label. Each key is the name of a named data source in the document:
POST /api/v2/convert/btw/to/zpl?params={"data":[{"ProductName":"Widget","SKU":"12345"}]}Only named data sources can be filled. Without data, each object prints the sample value saved in the document, and that value is fixed in the ZPL. Values that BarTender computes when it prints, such as dates and script results, have no saved sample, so they don’t appear, and a barcode that uses one isn’t drawn. For details, see Variable data.
To keep the data sources for later, convert to xml or json, or to ZPL with a dialect. Named data sources then stay as merge fields.
Set the label size
Section titled “Set the label size”For each dimension, the API uses label.width or label.height from the request, then the document’s template size, then the extent of the content. A .btc component has no template size. Set dpi to the density of the target printer. See Label size.
What converts
Section titled “What converts”Text, barcodes, pictures (including SVG), lines, boxes, and ellipses convert. Some objects change:
| Object | Output |
|---|---|
| Colors | Black or white, whichever is nearer |
| Italic text | Upright text |
| UPC and EAN add-ons | Left out |
| Barcode readable text | The raw barcode data, without BarTender’s masking or formatting |
| HIBC barcode | No + flag or check character |
| GS1 DataBar Stacked | GS1 DataBar Omnidirectional |
| Code 128 with non-ASCII data | Left out |
| Shapes turned at an angle other than a quarter turn | Left out |
These objects are left out: tables, grids, RFID, magnetic stripe, rich text, Digimarc, block arrows, objects with a border or shading, and barcode types such as GS1 Composite, Code 16K, and most postal codes. A document with more than one template isn’t supported.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Fix |
|---|---|
400 for a password-protected document |
Remove the password in BarTender and send the file again. |
400 that says the file has nothing to draw |
Every object in the file is one that doesn’t convert. Check the list in What converts. |
400 for a very old document, such as one from BarTender 7.10 |
Open the document in a current BarTender version, save it, and send it again. |
400 that says the file is too large |
Files over 64 MB aren’t read. Remove large pictures from the document. |
| A barcode is missing | It uses a value BarTender computes when it prints. Pass the value in data through a named data source. |
| The label is the wrong size | Set label.width and label.height, in inches, and dpi. |