gPdf
Casos de uso · Logística y envíos

Archivos PDF de etiquetas de envío a escala de transportista

Genere etiquetas térmicas 4×6 con códigos de barras vectoriales GS1-128, códigos ITF-14 para cajas e IDs SSCC-18 para pallets. El renderizado en el edge mantiene el p99 por debajo de 15 ms incluso en picos de Black Friday.

Trabajo a resolver

Generar etiquetas térmicas 4×6 listas para transportista, con códigos de barras vectoriales GS1-128, ITF-14 y SSCC-18, directamente desde el JSON del pedido y sin iniciar un navegador sin interfaz gráfica por solicitud. La salida debe escanearse de forma fiable a 203 dpi en impresoras Zebra, SATO y Honeywell, y mantenerse por debajo de 15 ms p99 durante picos de comercio minorista.

Por qué gPdf encaja aquí

  • Code 128, QR, DataMatrix, PDF417 y GS1-128 / ITF-14 / SSCC-18 vectoriales: precisión subpíxel a 203 dpi, 300 dpi y 600 dpi.
  • Precisión de coordenadas de 0,1 mm: ajusta la tolerancia de longitud total que exigen los transportistas para las líneas legibles por humanos.
  • Los tamaños de página `label_4_6_in`, `label_4_8_in` y `label_a6` vienen preconfigurados para los formatos dominantes de impresoras térmicas.
  • Determinismo: el mismo JSON de pedido genera un PDF idéntico byte a byte, de modo que una reimpresión en almacén no produce una etiqueta distinta.
  • Renderizado en el edge: p50 de 3 ms y p99 de 8 ms, incluso cuando se imprimen 50.000 etiquetas en el mismo minuto antes de la recogida del transportista.
  • Sin estado: la etiqueta existe en memoria durante unos 4 ms dentro de un isolate de Cloudflare Worker y después se libera. No hay almacén documental ni una superficie adicional donde puedan filtrarse datos del transportista.

Solicitud de ejemplo

POST /api/v1/pdf/render: etiqueta térmica 4×6 mínima con un código de barras Code 128 para seguimiento del transportista.

{
  "pages": [{
    "size": "label_4_6_in",
    "elements": [
      {
        "type": "text",
        "x": 4, "y": 6,
        "content": "SHIP TO",
        "style": { "font_size": 8, "font_family": "NotoSans-Regular" }
      },
      {
        "type": "text",
        "x": 4, "y": 12,
        "content": "Acme Distribution Centre\n1200 Logistics Pkwy\nMemphis TN 38116",
        "style": { "font_size": 11, "font_family": "NotoSans-Regular" }
      },
      {
        "type": "barcode",
        "format": "code128",
        "content": "1Z999AA10123456784",
        "x": 4, "y": 60,
        "width": 92, "height": 22,
        "barcode_text": { "enabled": true, "position": "bottom" }
      }
    ]
  }]
}

Cumplimiento y conformidad

  • GS1 General Specifications: el ancho de módulo (dimensión X), la zona silenciosa y la longitud total cumplen las tolerancias de GS1 Section 5.4 a 203 dpi.
  • Requisitos de transportistas: UPS, FedEx, DHL y USPS aceptan la salida renderizada como escaneable; no se requiere posprocesamiento por transportista.
  • PDF/A-2b está disponible para archivo mediante `settings.profile = "pdfa-2b"` si necesita conservar el PDF de la etiqueta por motivos fiscales o de auditoría.

La carga de trabajo de una etiqueta de envío, en un párrafo

Cada pedido produce un PDF, cada PDF se imprime una vez en una impresora térmica y, si el sistema va lento, el modo de fallo no es “la página tarda en cargar”: es “la recogida del almacén queda esperando detrás de la API que renderiza etiquetas”. En envíos, la latencia p99 es el indicador de producto. La salida determinista importa porque las reimpresiones son rutina. Y la calidad del código de barras, medida en tolerancias de dimensión X de GS1 y no en píxeles, decide si el escáner lee la etiqueta al primer intento.

Las pilas de PDF basadas en navegadores sin interfaz gráfica tienen dificultades para cumplir las tres cosas a la vez: el coste de arranque en frío se acumula durante los picos, los códigos de barras rasterizados se degradan en etiquetas térmicas pequeñas y la rasterización de fuentes cambia entre versiones de Chromium, por lo que una “reimpresión idéntica byte a byte” deja de ser posible.

Por qué gPdf encaja

Una etiqueta térmica 4×6 es pequeña (576 × 864 píxeles a 203 dpi), tiene pocos elementos (bloques de texto, uno o dos códigos de barras y, opcionalmente, el logotipo del transportista) y se genera en alto volumen: un 3PL mediano renderiza entre 50.000 y 500.000 al día. Ese es el tipo de carga para el que se diseñó gPdf. El renderizador:

  1. Compila la composición una vez: las coordenadas de página, las cascadas de fuentes y la geometría de los códigos de barras se resuelven al procesar la solicitud, no mediante un motor de maquetación de navegador.
  2. Vectoriza cada código de barras: los módulos se dibujan directamente en el flujo PDF, de modo que un GS1-128 de 30 mm de ancho se lee con nitidez a 203 dpi o 600 dpi sin que usted tenga que implementar lógica de rasterización sensible al DPI.
  3. Integra NotoSans CJK + Latin: el mismo dato de entrada renderiza correctamente el nombre de un transportista en chino sin que deba aprovisionar fuentes en un contenedor de renderizado.

El p99 se mantiene plano en 8 ms en nuestra carga de referencia (1.000 invocaciones del ejemplo anterior en EU-WEST), sin importar si un isolate ha renderizado una etiqueta o 10.000 etiquetas.

Volumen y cálculo de coste

Un 3PL mediano típico opera alrededor de 50.000 etiquetas al día, es decir, cerca de 1,5 millones al mes. Con el plan Basic (5 USD/mes para 100.000 páginas, con excedente a 0,00005 USD por página), el cálculo es:

1,5M páginas × 0,00005 USD  = 75,00 USD de excedente
+ base del plan Basic        =  5,00 USD
─────────────────────────────────────
total                         = 80,00 USD/mes

La misma carga en Puppeteer-on-Lambda suele quedar en el rango de 200-400 USD/mes con configuraciones habituales de concurrencia en Lambda, antes de sumar el coste operativo de los arranques en frío durante los picos.

Black Friday: un ejemplo trabajado

Los picos son la carga donde el renderizado en el edge demuestra su valor con más claridad. Imagine un cliente de comercio minorista que alcanza el 200% de su volumen normal de etiquetas durante la primera hora de Black Friday: 100.000 etiquetas en 60 minutos, un promedio de 1.700 etiquetas/minuto y ráfagas máximas de 5.000/minuto. Esa carga termina dentro de un único pool regional de Cloudflare Workers, sin coste de arranque en frío. La misma carga sobre un pool precalentado de Puppeteer dimensionado para el tráfico medio genera arranques en frío de 1,5 a 2,5 s en los contenedores creados para absorber la ráfaga, y el mostrador de recogida del almacén siente cada uno de ellos.

Qué leer después

Seguir leyendo