gPdf
Anwendungsfälle · Logistik und Versand

Versandlabel-PDFs in Carrier-tauglichem Maßstab

Rendern Sie 4x6-Thermo-Versandlabel mit Vektor-Barcodes für GS1-128, ITF-14-Kartonkennzeichnungen und SSCC-18-Paletten-IDs. Edge-Rendering hält p99 unter 15 ms, auch bei Black-Friday-Spitzen.

Zu erledigende Aufgabe

Carrier-taugliche 4x6-Thermo-Versandlabel direkt aus Bestell-JSON rendern - inklusive Vektor-Barcodes für GS1-128, ITF-14 und SSCC-18, ohne pro Anfrage einen Headless Browser zu starten. Die Ausgabe muss bei 203 dpi auf Zebra-, SATO- und Honeywell-Druckern zuverlässig scanbar sein und bei Retail-Spitzen unter 15 ms p99 bleiben.

Warum gPdf dafür passt

  • Vektor-Code 128, QR, DataMatrix, PDF417 sowie GS1-128 / ITF-14 / SSCC-18 - subpixelgenau bei 203 dpi, 300 dpi und 600 dpi.
  • 0,1 mm Koordinatengenauigkeit - erfüllt die Carrier-Toleranzen für die Gesamtlänge menschenlesbarer Interpretationszeilen.
  • Seitengröße `label_4_6_in` sowie `label_4_8_in` und `label_a6` sind für die wichtigsten Thermodruckerformate vorkonfiguriert.
  • Determinismus: Dasselbe Bestell-JSON rendert zu einem byte-identischen PDF, sodass Nachdrucke im Lager nie ein anderes Label erzeugen.
  • Edge-Rendering: p50 3 ms, p99 8 ms, selbst wenn 50.000 Labels in derselben Minute zur Carrier-Abholung gedruckt werden.
  • Zustandslos: Das Label liegt etwa 4 ms im Speicher eines Cloudflare Worker Isolates und wird danach freigegeben. Kein Dokumentenspeicher, keine zusätzliche Angriffsfläche für Carrier-Daten.

Beispiel-Request

POST /api/v1/pdf/render - minimales 4x6-Thermolabel mit einem Code-128-Barcode für Carrier-Tracking.

{
  "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" }
      }
    ]
  }]
}

Compliance und Konformität

  • GS1 General Specifications: Modulbreite (X-dimension), Quiet Zone und Gesamtlänge entsprechen bei 203 dpi den Toleranzen aus GS1 Section 5.4.
  • Carrier-Vorgaben: UPS, FedEx, DHL und USPS akzeptieren die gerenderte Ausgabe als scanbar; keine Carrier-spezifische Nachbearbeitung erforderlich.
  • PDF/A-2b ist über `settings.profile = "pdfa-2b"` für Archivierung verfügbar, wenn Sie das Label-PDF aus Steuer- oder Audit-Gründen aufbewahren müssen.

Der Versandlabel-Workload in einem Absatz

Jede Bestellung erzeugt ein PDF, jedes PDF wird genau einmal auf einem Thermodrucker gedruckt, und der Ausfallmodus bei langsamer Generierung ist nicht “die Seite lädt langsam”, sondern “die Abholung im Lager steht hinter Ihrer Label-Rendering-API an”. Versand ist ein Workload, bei dem p99-Latenz die Produktmetrik ist, deterministische Ausgabe zählt, weil Nachdrucke alltäglich sind, und Barcode-Qualität - gemessen an GS1-Toleranzen für die X-dimension statt an Pixeln - darüber entscheidet, ob Scanner das Label im ersten Durchlauf lesen.

PDF-Stacks auf Basis von Headless Browsern haben mit allen drei Punkten gleichzeitig zu kämpfen: Kaltstartkosten häufen sich bei Lastspitzen, Raster-Barcodes verlieren auf kleinen Thermolabeln an Qualität, und Font-Rasterisierung driftet zwischen Chromium-Versionen. Ein “byte-identischer Nachdruck” ist damit praktisch nicht erreichbar.

Warum gPdf passt

Ein 4x6-Thermolabel ist klein (576 x 864 Pixel bei 203 dpi), hat wenige Elemente (Textblöcke plus 1 bis 2 Barcodes und optional ein Carrier-Logo) und entsteht in hohem Volumen. Ein mittelgroßer 3PL rendert etwa 50.000 bis 500.000 Labels pro Tag. Genau für diese Last ist gPdf gebaut. Der Renderer:

  1. Kompiliert das Layout einmal - Seitenkoordinaten, Font-Kaskaden und Barcode-Geometrie werden zur Anfragezeit aufgelöst, nicht über eine Browser-Layout-Engine.
  2. Vektorisiert jeden Barcode - Module werden direkt in den PDF-Stream gezeichnet, sodass ein 30 mm breiter GS1-128 bei 203 dpi oder 600 dpi sauber lesbar bleibt, ohne dass Sie eigene DPI-bewusste Rasterlogik schreiben müssen.
  3. Bettet NotoSans CJK und Latin ein - dieselben Anfragedaten rendern einen chinesischen Carrier-Namen korrekt, ohne dass Sie Fonts auf einem Render-Container bereitstellen.

p99 bleibt in unserer Referenzlast konstant bei 8 ms (1.000 Aufrufe des obigen Beispiels in EU-WEST), unabhängig davon, ob ein einzelnes Isolate ein Label oder 10.000 Labels gerendert hat.

Volumen- und Kostenrechnung

Ein typischer mittelgroßer 3PL liegt bei etwa 50.000 Labels/Tag, also rund 1,5 Mio. Labels/Monat. Im Basic-Plan (5 USD/Monat für 100.000 Seiten, 0,00005 USD pro zusätzlicher Seite) ergibt das:

1,5 Mio. Seiten x 0,00005 USD       = 75,00 USD Mehrverbrauch
+ Basic-Plan Grundpreis             =  5,00 USD
──────────────────────────────────────────────
Summe                                 = 80,00 USD/Monat

Derselbe Workload mit Puppeteer auf Lambda liegt bei typischen Lambda-Concurrency-Einstellungen im Bereich von 200 bis 400 USD/Monat, noch bevor Kaltstartkosten während Lastspitzen berücksichtigt werden.

Black Friday: ein durchgerechnetes Beispiel

Lastspitzen sind der Workload, bei dem Edge-Rendering seinen Wert am deutlichsten zeigt. Ein Retail-Kunde mit 200 % des normalen Label-Volumens in der ersten Stunde des Black Friday - zum Beispiel 100.000 Labels in 60 Minuten, durchschnittlich 1.700 Labels/Minute mit Burst-Spitzen von 5.000 Labels/Minute - bleibt innerhalb eines einzigen Cloudflare-Workers-Region-Pools, ohne Kaltstartaufschlag. Derselbe Workload auf einem Puppeteer-Warm-Pool, der auf Durchschnittsverkehr dimensioniert ist, erzeugt bei den zusätzlich gestarteten Burst-Containern Kaltstarts von 1,5 bis 2,5 s. Diese Verzögerung spürt der Abholplatz im Lager bei jedem einzelnen Label.

Wo Sie weiterlesen sollten

Weiterlesen