gPdf
Casos de uso · Logística e envio

PDFs de etiquetas de envio em escala de transportadora

Renderize etiquetas térmicas 4×6 com códigos de barras GS1-128 vetoriais, códigos ITF-14 de caixa e IDs SSCC-18 de palete. A renderização na edge mantém p99 abaixo de 15 ms, mesmo em picos de Black Friday.

Job a ser feito

Renderizar etiquetas térmicas 4×6 prontas para transportadoras — incluindo códigos de barras vetoriais GS1-128, ITF-14 e SSCC-18 — diretamente a partir do JSON do pedido, sem iniciar um navegador headless por requisição. A saída precisa ser lida com confiabilidade a 203 dpi em impressoras Zebra/SATO/Honeywell e manter p99 abaixo de 15 ms durante picos do varejo.

Por que gPdf para isso

  • Code 128, QR, DataMatrix, PDF417 e GS1-128 / ITF-14 / SSCC-18 vetoriais — precisão subpixel a 203 dpi, 300 dpi e 600 dpi.
  • Precisão de coordenadas de 0,1 mm — atende à tolerância de comprimento total das transportadoras para linhas de interpretação legíveis por humanos.
  • Tamanho de página `label_4_6_in` (e `label_4_8_in`, `label_a6`) já configurado para os formatos dominantes de impressoras térmicas.
  • Determinismo — o mesmo JSON de pedido renderiza um PDF byte a byte idêntico, para que reimpressões no armazém nunca gerem uma etiqueta 'diferente'.
  • Renderização na edge — p50 de 3 ms, p99 de 8 ms, mesmo quando 50 mil etiquetas são impressas no mesmo minuto da coleta pela transportadora.
  • Sem estado: a etiqueta existe em memória por ~4 ms em um isolate do Cloudflare Worker e depois é liberada. Sem armazenamento de documentos, sem superfície de vazamento de dados de transportadora.

Requisição de exemplo

POST /api/v1/pdf/render — etiqueta térmica 4×6 mínima com código de barras Code 128 de rastreamento da transportadora.

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

Conformidade e aderência

  • GS1 General Specifications — largura do módulo (X-dimension), quiet zone e comprimento total seguem as tolerâncias da Seção 5.4 da GS1 a 203 dpi.
  • Exigências de transportadoras — UPS, FedEx, DHL e USPS aceitam a saída renderizada como escaneável; não é necessário pós-processamento por transportadora.
  • PDF/A-2b disponível para arquivo via `settings.profile = "pdfa-2b"` se você precisar manter o PDF da etiqueta por motivos fiscais ou de auditoria.

A carga de trabalho de etiquetas de envio, em um parágrafo

Cada pedido produz um PDF, cada PDF é impresso uma vez em uma impressora térmica, e o modo de falha quando você é lento não é “a página carrega devagar” — é “a coleta do armazém ficou esperando atrás da sua API de renderização de etiquetas”. Envio é uma carga em que a latência p99 é a métrica do produto, em que saída determinística importa porque reimpressões são rotina, e em que qualidade de código de barras — medida nas tolerâncias de X-dimension da GS1, não em pixels — decide se os scanners leem a etiqueta na primeira passagem.

Stacks de PDF baseadas em navegador headless têm dificuldade nos três pontos ao mesmo tempo: o custo de cold start se acumula durante picos, códigos de barras rasterizados degradam em etiquetas térmicas pequenas, e a rasterização de fontes muda entre versões do Chromium, tornando impossível uma reimpressão byte a byte idêntica.

Por que gPdf se encaixa

Uma etiqueta térmica 4×6 é pequena (576 × 864 pixels a 203 dpi), tem poucos elementos (blocos de texto + 1-2 códigos de barras + um logotipo opcional da transportadora) e alto volume (um 3PL de médio porte renderiza 50 mil a 500 mil por dia). Essa é a carga de trabalho para a qual o gPdf foi criado. O renderizador:

  1. Compila o layout uma vez — coordenadas de página, cascatas de fontes e geometria de códigos de barras são resolvidas no momento da requisição, não por um mecanismo de layout de navegador.
  2. Vetoriza cada código de barras — os módulos são desenhados diretamente no stream do PDF, então um GS1-128 de 30 mm de largura é lido com nitidez a 203 dpi ou 600 dpi sem lógica de rasterização sensível a DPI no seu lado.
  3. Incorpora NotoSans CJK + Latin — os mesmos dados renderizam corretamente o nome de uma transportadora em chinês sem que você provisione fontes em um contêiner de renderização.

O p99 fica plano em 8 ms na nossa carga de referência (1.000 invocações do exemplo acima em EU-WEST), independentemente de um isolate ter renderizado uma etiqueta ou 10 mil etiquetas.

Volume + cálculo de custo

Um 3PL típico de médio porte opera em torno de 50 mil etiquetas/dia = ~1,5 milhão/mês. No plano Basic (US 5/mês por 100 mil páginas, US 0,00005 por página excedente), isso fica assim:

1,5 milhão de páginas × US$ 0,00005 = US$ 75,00 em excedente
+ base do plano Basic                       = US$  5,00
────────────────────────────────────────────────────
total                                      = US$ 80,00 / mês

A mesma carga em Puppeteer-on-Lambda fica na faixa de US$ 200-400/mês com configurações típicas de concorrência em Lambda, antes de considerar o custo de cold start nos horários de pico.

Black Friday: um exemplo calculado

O pico é a carga em que a renderização na edge mostra mais claramente seu valor. Um varejista que chega a 200% do volume normal de etiquetas na primeira hora da Black Friday — digamos 100 mil etiquetas em 60 minutos, média de 1,7 mil etiquetas/minuto com rajadas de pico de 5 mil/minuto — conclui tudo dentro de um único pool regional do Cloudflare Workers, sem custo de cold start. A mesma carga em um warm pool de Puppeteer dimensionado para o tráfego médio gera cold starts de 1,5-2,5 s nos contêineres criados para a rajada, e a mesa de coleta do armazém sente cada um deles.

Para onde olhar agora

Continue lendo