ZPL to PDF Microservice - Agent Orchestration

Este microservicio actúa como un sidecar local para el ecosistema GT:Sync / Pampero. Resuelve la incompatibilidad de versiones de Node.js en el backend principal (Next.js con Node 12), renderizando etiquetas ZPL a formato PDF de forma aislada y 100% offline utilizando un entorno gráfico simulado en memoria.

Infraestructura y Ejecución

Puerto del servicio: 3040
Host: 127.0.0.1 (Localhost)
Host remoto/LAN/ZeroTier: usar 0.0.0.0 al levantar el proceso para escuchar en todas las interfaces.
Motor Node: Binario aislado (v24.15.0) para no afectar el PATH global.
Core Stack: fastify (Web Server), zpl-js (Parser), canvas (Render gráfico), jspdf (Exportación binaria).

Control De Versiones

Repositorio oficial Gitea: https://gitea.globaltechscm.com/gt-microservices/zpl-pdf-microservice.git
Este microservicio usa Gitea, no Bonobo. Para este proyecto, configurar siempre origin contra el remoto Gitea anterior.
No versionar node_modules/, .cache/ ni el runtime local node-v24.15.0/. El runtime aislado se instala/restaura localmente en la ruta documentada abajo.

Ruta Absoluta del Intérprete

Para ejecutar el servidor o instalar paquetes a través de PM2 o consola, se DEBE utilizar obligatoriamente la siguiente ruta absoluta: C:\Users\Dorado\Desktop\Pampero\Proyectos\zpl-pdf-microservice\node-v24.15.0\node.exe

Comandos de Gestión (Usar CMD/PowerShell)

Levantar el servicio manualmente:

C:\Users\Dorado\Desktop\Pampero\Proyectos\zpl-pdf-microservice\node-v24.15.0\node.exe server.js

Levantarlo para acceso desde LAN/ZeroTier:

C:\Users\Dorado\Desktop\Pampero\Proyectos\zpl-pdf-microservice\node-v24.15.0\node.exe server.js --host=0.0.0.0 --port=3040

El default sigue siendo 127.0.0.1:3040 para uso local. También se puede configurar con variables de entorno HOST y PORT.

Parámetros de Render

El endpoint POST /convert acepta, además de zpl, los parámetros width, height, dpi, sourceDpi, fontWidthScale, code128WidthScale y qrSizeScale.

Para etiquetas Mercado Libre 4x6 con coordenadas Zebra a 203 DPI y PDF de salida a 300 DPI, usar como base:

{
  "width": 4,
  "height": 6,
  "dpi": 300,
  "sourceDpi": 203,
  "fontWidthScale": 0.82,
  "code128WidthScale": 1.42,
  "qrSizeScale": 0.5
}

code128WidthScale ajusta el ancho visual de ^BC porque bwip-js genera Code128 más angosto que Labelary/Zebra para algunas etiquetas ML con ^BY3. qrSizeScale ajusta el tamaño visual de ^BQ porque bwip-js incluye una matriz QR más grande que la salida observada en etiquetas ML/Zebra para ^BQN.

2.7 KiB Raw Blame History