gPdf
Use cases · Logistica e spedizioni

PDF per etichette di spedizione su scala carrier-grade

Renderizza etichette termiche 4×6 con codici a barre GS1-128 vettoriali, codici collo ITF-14 e ID pallet SSCC-18. Il rendering edge mantiene il p99 sotto 15 ms anche durante picchi Black Friday.

Job to be done

Renderizzare etichette termiche di spedizione 4×6 pronte per il corriere, inclusi codici a barre vettoriali GS1-128, ITF-14 e SSCC-18, direttamente da JSON ordine, senza avviare un browser headless per ogni richiesta. L'output deve scansionarsi in modo affidabile a 203 dpi su stampanti Zebra/SATO/Honeywell e restare sotto 15 ms p99 durante i picchi retail.

Why gPdf for this

  • Code 128, QR, DataMatrix, PDF417 e GS1-128 / ITF-14 / SSCC-18 vettoriali, con precisione sub-pixel a 203 dpi, 300 dpi e 600 dpi.
  • Precisione delle coordinate a 0,1 mm, in linea con la tolleranza di lunghezza complessiva del corriere per le righe leggibili da persone.
  • Formato pagina `label_4_6_in` (oltre a `label_4_8_in`, `label_a6`) già configurato per i formati dominanti delle stampanti termiche.
  • Determinismo: lo stesso JSON ordine renderizza un PDF byte-identical, così le ristampe in magazzino non producono una etichetta diversa.
  • Rendering edge: p50 3 ms, p99 8 ms, anche quando 50K etichette vengono stampate nello stesso minuto al ritiro del corriere.
  • Stateless: l'etichetta esiste in memoria per circa 4 ms in un isolate Cloudflare Worker, poi viene liberata. Nessun archivio documenti, nessuna superficie di fuga dati del corriere.

Sample request

POST /api/v1/pdf/render — etichetta termica 4×6 minima con codice a barre Code 128 per tracking del corriere.

{
  "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 and conformance

  • GS1 General Specifications: larghezza modulo (X-dimension), quiet zone e lunghezza complessiva rispettano le tolleranze della sezione GS1 5.4 a 203 dpi.
  • Mandati dei corrieri: UPS, FedEx, DHL e USPS accettano l'output renderizzato come scansionabile; non serve post-processing per singolo corriere.
  • PDF/A-2b disponibile per archiviazione tramite `settings.profile = "pdfa-2b"` se dovete conservare il PDF dell'etichetta per ragioni fiscali o di audit.

Il carico di lavoro delle etichette di spedizione, in un paragrafo

Ogni ordine produce un PDF, ogni PDF viene stampato una volta su una stampante termica, e il modo in cui il sistema fallisce quando siete lenti non è “la pagina carica lentamente”: è “il ritiro in magazzino resta in coda dietro la vostra API di rendering delle etichette”. La spedizione è un lavoro in cui la latenza p99 è la metrica di prodotto, l’output deterministico conta perché le ristampe sono routine, e la qualità del codice a barre, misurata in tolleranze GS1 X-dimension e non in pixel, decide se gli scanner leggono l’etichetta al primo passaggio.

Gli stack PDF basati su browser headless faticano su tutti e tre i fronti insieme: il costo di cold start si somma durante i picchi, i codici a barre raster degradano sulle piccole etichette termiche e la rasterizzazione dei font cambia tra versioni Chromium, quindi una ristampa byte-identical diventa impossibile.

Perché gPdf è adatto

Una etichetta termica 4×6 è piccola (576 × 864 pixel a 203 dpi), con pochi elementi (blocchi testo + 1-2 codici a barre + logo corriere opzionale) e ad alto volume (un 3PL medio renderizza 50K-500K al giorno). È il carico per cui gPdf è costruito. Il motore:

  1. Compila il layout una volta: coordinate pagina, cascate font e geometria dei codici a barre vengono risolte al tempo della richiesta, non tramite un motore di layout browser.
  2. Vettorializza ogni codice a barre: i moduli vengono disegnati direttamente nello stream PDF, così un GS1-128 largo 30 mm resta leggibile a 203 dpi o 600 dpi senza logica di rasterizzazione DPI-aware lato vostro.
  3. Incorpora NotoSans CJK + Latin: gli stessi dati renderizzano correttamente un nome corriere cinese senza dover predisporre font su un container di rendering.

Il p99 resta piatto a 8 ms sul nostro carico di riferimento (1K invocazioni del campione sopra su EU-WEST), indipendentemente dal fatto che un singolo isolate abbia renderizzato una etichetta o 10K etichette.

Volume + matematica dei costi

Un tipico 3PL di medie dimensioni lavora intorno a 50K etichette/giorno = circa 1,5M/mese. Sul piano Basic (5 USD/mese per 100K pagine, eccedenza 0,00005 USD per pagina) significa:

1,5M pagine × 0,00005 USD     = 75,00 USD di eccedenza
+ base piano Basic             =  5,00 USD
─────────────────────────────────────
totale                          = 80,00 USD / mese

Lo stesso carico su Puppeteer-on-Lambda rientra nella fascia 200-400 USD/mese con impostazioni Lambda tipiche di concorrenza, prima di considerare la tassa di cold start durante il picco.

Black Friday: un esempio calcolato

Il picco è il carico in cui il rendering edge ripaga più chiaramente. Un cliente retail che raggiunge il 200% del volume normale di etichette nella prima ora del Black Friday, per esempio 100K etichette in 60 minuti, media di 1,7K etichette/minuto con burst di picco a 5K/minuto, completa dentro un pool regionale Cloudflare Workers senza tassa di cold start. Lo stesso carico su un pool Puppeteer caldo dimensionato per il traffico medio produce cold start da 1,5-2,5 s sui container avviati per il burst, e il banco ritiro del magazzino li sente tutti.

Dove guardare dopo

Keep reading