Guía introductoria a ZPL
Guía introductoria a ZPL
Qué es ZPL
ZPL (Zebra Programming Language) es un lenguaje basado en texto para controlar impresoras térmicas Zebra y compatibles. Una etiqueta ZPL no es más que un bloque de texto: se abre con ^XA, se cierra con ^XZ, y en medio se declaran elementos gráficos, texto y códigos de barras.
La ventaja es que el "archivo" es legible, versionable y editable a mano. Sin formato propietario: basta un editor de texto para producir una etiqueta lista para imprimir.
Hello world
^XA
^FO50,50^A0N,40,40^FDHola Mundo^FS
^XZ
Eso es todo. Enviado a una impresora Zebra (o a un visor como Labelary), produce una etiqueta con "Hola Mundo" impreso arriba a la izquierda.
Anatomía de una etiqueta
Línea por línea, el ejemplo anterior significa:
^XA— start format: marca el inicio de la etiqueta. Todo lo que sigue forma parte de la etiqueta actual.^FO50,50— field origin: coloca el siguiente elemento a 50 dots del margen izquierdo y 50 dots de arriba.^A0N,40,40— fuente: selecciona la fuente 0, orientaciónN(normal, sin rotar), alto 40 dots, ancho 40 dots.^FD— field data: introduce el contenido del campo. Todo lo que sigue hasta^FSes el texto a imprimir.^FS— field separator: cierra el campo. Olvidarlo es uno de los errores más comunes: el parser interpretará los comandos siguientes como datos.^XZ— end format: cierra la etiqueta.
Comandos esenciales
| Comando | Qué hace |
|---|---|
^XA / ^XZ |
Abre / cierra el formato de la etiqueta |
^PW |
Ancho del área de impresión (dots) |
^LL |
Largo de la etiqueta (dots) |
^LH |
Desplaza el origen lógico de la etiqueta |
^CI28 |
Establece la codificación UTF-8 (imprescindible para acentos) |
^FO x,y |
Posiciona el siguiente elemento |
^A0N,h,w |
Fuente escalable 0, alto/ancho en dots |
^FD ... ^FS |
Delimita el campo de datos |
^BC |
Código de barras Code 128 |
^BQ |
Código QR |
^GB w,h,t |
Caja o línea (ancho, alto, grosor) |
^GF |
Bitmap en escala de grises |
^FX |
Comentario (ignorado por la impresora) |
Sistema de coordenadas
ZPL razona en dots (puntos individuales de impresión), no en milímetros. La conversión depende de la resolución de la impresora:
dot = mm * DPI / 25.4
Ejemplos prácticos:
- 50 mm a 203 dpi ≈ 400 dots
- 50 mm a 300 dpi ≈ 591 dots
- 100 mm a 203 dpi ≈ 800 dots
El origen (0,0) es la esquina superior izquierda. Una impresora de 203 dpi con etiquetas de 4 pulgadas suele usar ^PW812.
Placeholders dinámicos
En ZPL Archive usamos la notación {{nombre}} para campos sustituibles al vuelo. Ejemplo de etiqueta de envío paramétrica:
^XA
^CI28
^FO30,30^A0N,28,28^FDDestinatario:^FS
^FO30,70^A0N,36,36^FD{{customer_name}}^FS
^FO30,120^A0N,28,28^FDTracking:^FS
^FO30,160^BCN,80,Y,N,N^FD{{tracking_number}}^FS
^XZ
El editor de personalización lee los {{...}}, muestra un formulario con un campo por cada uno y produce el ZPL final con los valores sustituidos antes de enviarlo a la impresora o a la vista previa.
Errores comunes
Le pasan a todo el mundo, al menos una vez. Conviene aprender a reconocerlos enseguida.
^FSolvidado: los comandos siguientes son "tragados" por el campo anterior y la etiqueta sale vacía o desalineada.- Coordenadas fuera del área de impresión: con
^PW812pero^FO900,...el elemento no se imprime. Verifica siempre los valores contra^PWy^LL. - Fuente no disponible en la impresora: la fuente
0siempre está presente, las demás dependen del firmware. En la duda, quédate con^A0N. - Acentos que aparecen como
?o caracteres extraños: falta^CI28al inicio. Añádelo justo después de^XA. - Código de barras que no escanea: a menudo la zona de quietud (margen blanco alrededor) es insuficiente. Aumenta el
^FOo reduce el ancho de módulo.
Recursos externos
- Guía oficial Zebra ZPL (PDF) — el manual de referencia completo.
- Labelary Viewer — renderiza ZPL a PNG/PDF en línea, muy útil para iterar sin imprimir.
- Portal de desarrolladores Zebra — documentación, SDKs, ejemplos.