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ón N (normal, sin rotar), alto 40 dots, ancho 40 dots.
  • ^FD — field data: introduce el contenido del campo. Todo lo que sigue hasta ^FS es 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.

  • ^FS olvidado: 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 ^PW812 pero ^FO900,... el elemento no se imprime. Verifica siempre los valores contra ^PW y ^LL.
  • Fuente no disponible en la impresora: la fuente 0 siempre está presente, las demás dependen del firmware. En la duda, quédate con ^A0N.
  • Acentos que aparecen como ? o caracteres extraños: falta ^CI28 al 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 ^FO o reduce el ancho de módulo.

Recursos externos