4x6 PDF 라벨용 배송 라벨 API
주문 JSON에서 벡터 바코드, 라벨 페이지 크기, 결정적인 창고 재출력을 갖춘 인쇄 준비 완료 4x6 배송 라벨 PDF를 생성합니다.
/api/v1/pdf/render 주문, 수취인, 서비스, 운송장 데이터에서 라벨 크기 PDF를 렌더링하여 창고나 이커머스 백엔드가 풀필먼트 중 동일한 4x6 라벨을 안정적으로 인쇄하고, 필요할 때 같은 결과로 재출력할 수 있게 합니다.
이 API를 쓰는 경우
- 시스템에 운송장 번호, 목적지, 서비스 문구, 바코드 데이터가 이미 있습니다.
- Zebra, SATO, Honeywell 등 감열 프린터 워크플로에 쓸 PDF 출력이 필요합니다.
- PDF에 붙여 넣은 래스터 바코드 이미지가 아니라 벡터 바코드 모듈이 필요합니다.
- 재출력과 감사 증거를 위해 동일한 요청 데이터가 동일한 라벨을 렌더링해야 합니다.
대체하지 않는 것
- 운임 구매, 배송 요금 산정, 운송사 계정 기반 라벨 생성을 gPdf가 처리해야 합니다.
- ZPL 대체 엔드포인트가 필요합니다. gPdf는 프린터 명령어가 아니라 PDF를 반환합니다.
- gPdf가 운송사 인증을 제공해야 합니다. 스캐너 테스트와 운송사 승인 테스트는 사용자가 담당합니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/template-render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/pdf/render - 운송장 바코드가 포함된 최소 4x6 라벨.
{
"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": 13,
"content": "Acme Warehouse\n1200 Logistics Pkwy\nMemphis TN 38116",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "1Z999AA10123456784",
"x": 4,
"y": 62,
"width": 92,
"height": 22,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf가 처리하는 것
- 4x6인치 워크플로 같은 라벨 크기 PDF 페이지.
- 운송사와 창고 라벨 콘텐츠를 위한 벡터 바코드 렌더링.
- 텍스트, 주소 블록, 서비스 표시, 선, 박스, 선택적 템플릿 바인딩.
- 창고 재출력을 위한 결정적인 PDF 출력.
자체 시스템이 책임지는 것
- 운송사 계정, 운임 구매, 서비스 선택, 운송장 번호 생성.
- 정확한 바코드 데이터, 사람이 읽을 수 있는 텍스트, 주소, 라우팅 데이터.
- 프린터 설정, 라벨 용지, 스캔 테스트, 운송사 승인 확인.
운영 전 체크리스트
- 실제 프린터 모델과 라벨 용지로 테스트 라벨을 인쇄합니다.
- 목표 DPI와 스캐너 거리에서 바코드 스캔 성공률을 확인합니다.
- 재출력 정책에 따라 원본 배송 데이터 또는 반환된 PDF를 저장합니다.
- 라벨 레이아웃이 승인되어 여러 시스템에서 재사용되면 Template Render를 사용합니다.
- 운송사별 로직은 렌더링 요청 밖에 둡니다.
지원 범위의 경계
- gPdf는 라벨 PDF를 렌더링합니다. 운임을 구매하거나 운송사와 직접 통신하지 않습니다.
- gPdf는 운송사 라벨 인증 기관이 아닙니다.
- API 출력은 PDF이며 ZPL, EPL 또는 다른 감열 프린터 명령 스트림이 아닙니다.
배송 라벨 API의 형태
배송 라벨 페이지는 별도의 운송사 엔드포인트가 아닙니다. 라벨 크기 페이지, 텍스트 블록, 선, 선택적 이미지, 바코드 요소를 포함해 JSON Render를 호출합니다. 반복해서 쓰는 라벨은 승인된 레이아웃을 템플릿으로 게시한 뒤 배송 데이터와 함께 Template Render를 호출합니다.
이 구조는 책임 경계를 분명하게 유지합니다. gPdf는 PDF 렌더링과 바코드 그리기를 담당합니다. 운송사 거래, 배송 상태, 요청 데이터의 업무적 의미는 사용자 시스템이 담당합니다.
JSON Render와 Template Render
풀필먼트 시스템이 전체 레이아웃을 생성하거나 운영팀이 아직 좌표를 조정하는 중이라면 JSON Render를 사용하세요. 창고가 안정적인 라벨 레이아웃을 승인했고 모든 호출자가 동일한 데이터 필드만 보내야 한다면 Template Render를 사용하세요.
두 경로 모두 PDF 출력을 반환합니다. 차이는 호출자가 요청마다 레이아웃을
설명하는지, 아니면 게시된 template_id를 참조하는지입니다.
인쇄 테스트는 중요합니다
감열 라벨 품질은 물리적인 문제입니다. 실제 라벨 용지, 실제 프린터, 실제 스캐너에서 출력을 검증하세요. 바코드 데이터의 정확성, quiet zone, 프린터 농도, 운송사별 규칙은 렌더링 API 밖의 운영 책임입니다.
FAQ
- gPdf가 운송사 라벨을 대신 만들어 주나요?
- 아니요. 운송사 또는 배송 시스템이 운송사 배송 건과 바코드 데이터를 생성합니다. gPdf는 그 데이터를 PDF 라벨로 렌더링합니다.
- 배송 라벨에 Template Render를 사용할 수 있나요?
- 네. 라벨을 설계하거나 테스트하는 동안에는 JSON Render를 사용하고, 레이아웃이 안정되어 호출자가 데이터만 보내야 할 때는 Template Render를 사용하세요.
- gPdf가 ZPL을 출력하나요?
- 아니요. 공개 렌더 API는 PDF를 출력합니다. 출력 경로에 ZPL이 필요하다면 gPdf 밖에서 PDF를 변환하거나 라우팅하세요.
- 운영 전에 무엇을 검증해야 하나요?
- 실제 프린터와 라벨 용지에 인쇄하고, 운영 스캐너로 바코드를 스캔하며, 운송사별 텍스트와 바코드 데이터가 배송 시스템에서 온 것인지 확인하세요.