Migrar de la API de Labelary a OpenZPL

Para mover un cliente de Labelary v1 a OpenZPL, cambie el host de api.labelary.com a api.openzpl.com y mantenga las rutas, encabezados y cuerpos de solicitud. Luego revise los pocos códigos de estado y límites que difieren, listados a continuación junto con las pruebas que realizamos.

Actualizado 2026-10-20 · Renderizados hechos con el motor de OpenZPL

1. Cambiar el host

La ruta de renderización es la misma, por lo que solo cambia la URL base:

- https://api.labelary.com/v1/printers/8dpmm/labels/4x6/0/
+ https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/

curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/ \
  --data-binary @label.zpl > label.png

curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/ \
  -H "Accept: application/pdf" --data-binary @labels.zpl > labels.pdf

En Python, mantén la URL base en una configuración para que puedas volver:

import os
import requests

BASE = os.environ.get("ZPL_API", "https://api.openzpl.com")  # was https://api.labelary.com


def render_pdf(zpl: str, size: str = "4x6", dpmm: int = 8) -> bytes:
    res = requests.post(
        f"{BASE}/v1/printers/{dpmm}dpmm/labels/{size}/",
        data=zpl.encode("utf-8"),
        headers={"Accept": "application/pdf"},
        timeout=15,
    )
    res.raise_for_status()
    return res.content

2. Mantenga sus encabezados

Accept (image/png o application/pdf), X-Quality y X-Rotation funcionan como lo hacen en Labelary, y la respuesta lleva X-Total-Count. X-Page-Size, X-Page-Layout, X-Label-Border y X-Linter no están soportados: OpenZPL devuelve una etiqueta por página al tamaño de la etiqueta. Otros valores de Accept como application/epl devuelven 406.

3. Añada una clave si necesita más que el plan gratuito

El plan gratuito no necesita clave y está limitado por IP. Con una clave de su panel de control, envíela en X-API-Key y se aplican los límites de su espacio de trabajo. Un nombre de host privado de Labelary no tiene equivalente: todos usan api.openzpl.com.

curl https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/0/ \
  -H "X-API-Key: oz_live_…" --data-binary @label.zpl > label.png

4. Recuente sus límites

La cuota diaria de Labelary cuenta solicitudes; la de OpenZPL cuenta etiquetas. Si tus solicitudes devuelven PDFs con múltiples etiquetas, divide tus solicitudes diarias por las etiquetas por solicitud para ver qué cabe en 5,000 etiquetas, o en tu plan en la página de precios.

5. Manejar 429 y 503

En 429, espere los segundos en Retry-After: 1 para el límite por segundo, hasta la medianoche UTC para el diario. En 503 (una etiqueta con más de 10 segundos de tiempo de renderizado, o el servicio a plena capacidad), intente nuevamente una vez con un breve retraso.

import time


def post_with_retry(url, body, headers, attempts=3):
    for _ in range(attempts):
        res = requests.post(url, data=body, headers=headers, timeout=15)
        if res.status_code == 429:
            wait = int(res.headers.get("Retry-After", "1"))
            if wait > 60:
                res.raise_for_status()  # daily allowance used up
            time.sleep(wait)
            continue
        if res.status_code == 503:
            time.sleep(1)
            continue
        res.raise_for_status()
        return res
    res.raise_for_status()

Lo que probamos

probado el 2026-10-20 con etiquetas sintéticas, la misma solicitud enviada a api.labelary.com (nivel gratuito) y al motor de OpenZPL. Comparamos códigos de estado, encabezados, conteos de páginas y tamaño de imagen, no píxeles.

Diferencias a tener en cuenta

• Los formatos de salida distintos a PNG y PDF responden con 406; mantenga esas solicitudes en Labelary o elimínelas.
• Los píxeles pueden diferir donde las fuentes difieren. Compare imágenes visualmente o por la posición de campos clave, no byte por byte.
• Los textos de error difieren. Ambos comienzan con ERROR:; no se comparan en el resto.
• Los comandos que el motor no admite aún se imprimen de manera diferente o no se imprimen en absoluto; consulte compatibilidad.

Revirtiendo

Dado que nada más cambia, revertir es restablecer la URL base a api.labelary.com nuevamente. Mantenlo en la configuración, no en el código, y cambia primero una parte del tráfico: renderiza un día de etiquetas reales en ambos, compara una muestra, luego mueve el resto.