gPdf
사용 사례 · 물류와 배송

운송사급 대량 처리를 위한 배송 라벨 PDF

벡터 GS1-128 바코드, ITF-14 박스 코드, SSCC-18 팔레트 ID가 포함된 4×6 감열식 배송 라벨을 생성합니다. Edge 렌더링으로 블랙프라이데이 피크에도 p99를 15 ms 미만으로 유지합니다.

해결할 작업

주문 JSON에서 운송사 제출에 바로 쓸 수 있는 4×6 감열식 배송 라벨을 생성한다. 벡터 GS1-128, ITF-14, SSCC-18 바코드를 포함하고, 요청마다 헤드리스 브라우저를 띄우지 않는다. 결과물은 Zebra, SATO, Honeywell 프린터의 203 dpi 환경에서 안정적으로 스캔되어야 하며, 리테일 피크 시간에도 p99 15 ms 미만을 유지해야 한다.

이 용도에 gPdf가 맞는 이유

  • 벡터 Code 128, QR, DataMatrix, PDF417, GS1-128 / ITF-14 / SSCC-18: 203 dpi, 300 dpi, 600 dpi에서 서브픽셀 수준으로 정밀합니다.
  • 0.1 mm 좌표 정밀도: 사람이 읽는 해석 라인의 전체 길이가 운송사 허용 오차 안에 들어가도록 맞출 수 있습니다.
  • `label_4_6_in`, `label_4_8_in`, `label_a6` 페이지 크기가 주요 감열 프린터 형식에 맞춰 미리 구성되어 있습니다.
  • 결정적 출력: 같은 주문 JSON은 바이트 단위로 동일한 PDF를 생성하므로, 창고 재출력 시 다른 라벨이 생기지 않습니다.
  • Edge 렌더링: 운송사 픽업 시간에 같은 1분 동안 5만 개 라벨을 출력해도 p50 3 ms, p99 8 ms를 유지합니다.
  • 상태 비저장: Cloudflare Worker isolate 안에서 라벨이 약 4 ms 동안 메모리에 존재한 뒤 해제됩니다. 문서 저장소나 운송사 데이터가 새는 별도 표면이 없습니다.

예시 요청

POST /api/v1/pdf/render: Code 128 운송장 추적 바코드가 포함된 최소 4×6 감열식 라벨 예시입니다.

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

컴플라이언스와 적합성

  • GS1 General Specifications: 모듈 폭(X-dimension), quiet zone, 전체 길이가 203 dpi에서 GS1 Section 5.4 허용 오차에 맞습니다.
  • 운송사 요구사항: UPS, FedEx, DHL, USPS가 생성 결과물을 스캔 가능한 출력으로 받아들이며, 운송사별 후처리가 필요하지 않습니다.
  • 세무 또는 감사 목적으로 라벨 PDF를 보관해야 한다면 `settings.profile = "pdfa-2b"`로 PDF/A-2b 보관 프로파일을 사용할 수 있습니다.

배송 라벨 워크로드를 한 문단으로 정리하면

주문 하나가 PDF 하나를 만들고, 각 PDF는 감열 프린터에서 한 번 출력됩니다. 이때 느려졌을 때의 실패 모드는 “페이지 로딩이 느리다”가 아닙니다. “운송사 픽업 대기열이 라벨 렌더링 API 뒤에 막힌다”입니다. 배송 라벨에서는 p99 지연 시간이 곧 제품 지표입니다. 재출력이 일상적이기 때문에 결정적 출력도 중요합니다. 또한 바코드 품질은 픽셀이 아니라 GS1 X-dimension 허용 오차로 판단되며, 스캐너가 첫 번째 스캔에서 라벨을 읽을 수 있는지가 실제 운영 결과를 결정합니다.

헤드리스 브라우저 기반 PDF 스택은 이 세 가지를 동시에 만족시키기 어렵습니다. 피크 시간에는 콜드 스타트 비용이 누적되고, 작은 감열식 라벨에서는 래스터 바코드 품질이 떨어지며, Chromium 버전에 따라 폰트 래스터라이제이션이 달라져 “바이트 단위로 동일한 재출력”을 보장하기 어렵습니다.

gPdf가 맞는 이유

4×6 감열식 라벨은 작고(203 dpi 기준 576 × 864픽셀), 요소 수가 적으며(텍스트 블록 + 바코드 12개 + 선택적 운송사 로고), 출력량은 큽니다. 중간 규모 3PL도 하루 5만50만 장을 생성합니다. gPdf는 바로 이런 부하를 위해 설계되었습니다. 렌더러는 다음을 수행합니다.

  1. 레이아웃을 한 번에 해석합니다. 페이지 좌표, 폰트 cascade, 바코드 형상을 브라우저 레이아웃 엔진이 아니라 요청 처리 시점에 확정합니다.
  2. 모든 바코드를 벡터화합니다. 모듈을 PDF 스트림에 직접 그리기 때문에, 30 mm 폭의 GS1-128도 호출자 쪽에서 DPI별 래스터 처리 로직을 만들지 않고 203 dpi와 600 dpi에서 선명하게 읽힙니다.
  3. NotoSans CJK + Latin을 내장합니다. 렌더 컨테이너에 폰트를 따로 준비하지 않아도 같은 요청 데이터로 중국어 운송사 이름을 올바르게 렌더링할 수 있습니다.

위 예시를 EU-WEST에서 1,000회 호출한 기준 워크로드에서 p99는 8 ms로 평탄하게 유지됩니다. 하나의 isolate가 라벨 하나를 렌더링했는지, 1만 개를 렌더링했는지와 무관합니다.

물량과 비용 계산

일반적인 중간 규모 3PL은 하루 약 5만 장, 즉 월 약 150만 페이지의 라벨을 처리합니다. Basic 플랜(월 5달러에 10만 페이지, 초과분은 페이지당 0.00005달러) 기준 계산은 다음과 같습니다.

1.5M pages × $0.00005       = $75.00 in overage
+ Basic plan base            =   $5.00
─────────────────────────────────────
total                         = $80.00 / month

같은 워크로드를 Puppeteer-on-Lambda로 운영하면 일반적인 Lambda 동시성 설정에서 월 200~400달러 범위가 되며, 피크 시간의 콜드 스타트 비용은 여기에 포함되지 않습니다.

블랙프라이데이 예시

피크 스파이크는 Edge 렌더링의 가치가 가장 분명하게 드러나는 워크로드입니다. 예를 들어 한 리테일 고객이 블랙프라이데이 첫 1시간 동안 평소 라벨 물량의 200%를 처리한다고 가정해 보겠습니다. 60분 동안 10만 장, 평균 분당 1,700장, 순간 피크 분당 5,000장 수준입니다. 이 작업은 콜드 스타트 비용 없이 하나의 Cloudflare Workers 리전 풀 안에서 완료됩니다. 반면 평균 트래픽에 맞춰 둔 Puppeteer 웜풀은 버스트로 새로 생성된 컨테이너에서 1.5~2.5초 콜드 스타트를 만들고, 창고 픽업 데스크는 그 지연을 그대로 체감합니다.

다음 단계

계속 읽기