gPdf
Use cases · Lojistik ve gönderi

Kargo firması ölçeğinde gönderi etiketi PDF'leri

Vektör GS1-128 barkodları, ITF-14 koli kodları ve SSCC-18 palet ID'leri içeren 4×6 termal gönderi etiketleri oluşturun. Edge rendering, Black Friday sıçramalarında bile p99'u 15 ms altında tutar.

Job to be done

Sipariş JSON'undan doğrudan kargo firmasına hazır 4×6 termal gönderi etiketleri render edin; vektör GS1-128, ITF-14 ve SSCC-18 barkodları dahil olsun ve her istek için headless browser başlatılmasın. Çıktı Zebra/SATO/Honeywell yazıcılarda 203 dpi'de güvenilir şekilde taranmalı ve perakende tepe dönemlerinde p99 15 ms altında kalmalıdır.

Why gPdf for this

  • Vector Code 128, QR, DataMatrix, PDF417 ve GS1-128 / ITF-14 / SSCC-18: 203 dpi, 300 dpi ve 600 dpi'de sub-pixel doğruluk.
  • 0,1 mm koordinat hassasiyeti: human-readable interpretation line için kargo firması overall-length toleranslarını karşılamaya yardımcı olur.
  • `label_4_6_in` sayfa boyutu (`label_4_8_in`, `label_a6` ile birlikte) yaygın termal yazıcı formatları için önceden yapılandırılmış olarak gelir.
  • Determinizm: aynı sipariş JSON'u bayt düzeyinde aynı PDF olarak render edilir; depodaki reprint hiçbir zaman 'farklı' bir etiket üretmez.
  • Edge rendering: kargo firması teslim alma anında aynı dakika içinde 50.000 etiket basıldığında bile p50 3 ms, p99 8 ms.
  • Stateless: etiket Cloudflare Worker isolate içinde yaklaşık 4 ms bellekte kalır ve sonra serbest bırakılır. Document store yoktur, kargo firması verisi için ek sızıntı yüzeyi yoktur.

Sample request

POST /api/v1/pdf/render: Code 128 kargo takip barkodu içeren minimal 4×6 termal etiket.

{
  "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: module width (X-dimension), quiet zone ve overall length, 203 dpi'de GS1 Section 5.4 toleranslarıyla uyumludur.
  • Kargo firması gereksinimleri: UPS, FedEx, DHL ve USPS render edilen çıktıyı taranabilir kabul eder; kargo firması başına ayrı son işlem gerekmez.
  • Etiket PDF'ini vergi veya denetim gerekçesiyle saklamanız gerekiyorsa `settings.profile = "pdfa-2b"` ile arşivleme için PDF/A-2b kullanılabilir.

Gönderi etiketi iş yükü, tek paragrafta

Her sipariş bir PDF üretir, her PDF termal yazıcıda bir kez basılır ve yavaş kaldığınızda yaşanan hata “sayfa yavaş yükleniyor” değildir; “depo çıkışı, etiket-rendering API’nizin kuyruğunda bekliyor“dur. Gönderi etiketi işi, p99 latency’nin asıl ürün metriği olduğu bir iştir. Reprint rutin olduğu için deterministik çıktı önemlidir; barkod kalitesi de piksel üzerinden değil GS1 X-dimension toleransları üzerinden ölçülür ve tarayıcıların etiketi ilk geçişte okuyup okumayacağını belirler.

Headless-browser tabanlı PDF stack’leri bu üç noktayı aynı anda karşılamakta zorlanır: trafik sıçramasında cold-start maliyeti birikir, küçük termal etiketlerde raster barkodlar bozulur ve font rasterizasyonu Chromium sürümleri arasında kayar. Bu yüzden “byte-identical reprint” mümkün olmaz.

gPdf neden uygundur

4×6 termal etiket küçüktür (203 dpi’de 576 × 864 piksel), öğe sayısı düşüktür (metin blokları + 1-2 barkod + isteğe bağlı kargo firması logosu) ve hacmi yüksektir (orta ölçekli bir 3PL günde 50.000-500.000 etiket render eder). gPdf’in tasarlandığı iş yükü budur. Renderer:

  1. Layout’u bir kez derler: sayfa koordinatları, font cascade’leri ve barkod geometrisi browser layout engine’i üzerinden değil, istek sırasında çözülür.
  2. Her barkodu vektörleştirir: modüller doğrudan PDF stream içine çizilir; böylece 30 mm genişliğinde bir GS1-128, sizin tarafınızda DPI’ı dikkate alan rasterizasyon mantığı olmadan 203 dpi veya 600 dpi’de temiz okunur.
  3. NotoSans CJK + Latin’i gömer: aynı payload, Çincedeki bir kargo firması adını render container’ınıza font sağlamadan doğru şekilde render eder.

Referans iş yükümüzde p99 düz biçimde 8 ms’dir: yukarıdaki örneğin EU-WEST üzerinde 1.000 kez çalıştırılması. Tek bir isolate ister bir etiket render etmiş olsun ister 10.000 etiket, sonuç değişmez.

Hacim + maliyet hesabı

Tipik orta ölçekli bir 3PL yaklaşık 50.000 etiket/gün, yani ayda yaklaşık 1,5 milyon etiket üretir. Basic plan (100.000 sayfa için US5/ay, aşım için sayfa başına US0,00005) ile hesap:

1,5 milyon sayfa × US$0,00005   = US$75,00 aşım ücreti
+ Basic plan taban ücreti        =  US$5,00
─────────────────────────────────────
toplam                            = US$80,00 / ay

Aynı iş yükü, tipik Lambda concurrency ayarlarında Puppeteer-on-Lambda üzerinde US$200-400/ay aralığında çalışır; tepe dönemdeki cold-start vergisi buna dahil değildir.

Black Friday: çalışılmış bir örnek

Peak spike, Edge rendering’in değerini en net gösterdiği iş yüküdür. Black Friday’in ilk saatinde normal etiket hacminin %200’üne çıkan bir perakende müşterisini düşünün: 60 dakikada 100.000 etiket, ortalama 1,7K etiket/dakika ve peak burst sırasında 5K etiket/dakika. Bu yük, tek bir Cloudflare Workers region pool içinde cold-start vergisi olmadan tamamlanır. Ortalama trafiğe göre boyutlandırılmış bir Puppeteer warm pool üzerinde aynı iş yükü, burst sırasında yeni açılan container’larda 1,5-2,5 s cold-start üretir; depo teslim alma masası bu gecikmelerin her birini hisseder.

Sırada ne var?

Keep reading