물류와 라벨
이커머스 역물류를 위한 반품 라벨 API
이커머스 또는 지원 데이터에서 라벨 크기 페이지, 바코드, 템플릿 재출력을 포함한 반품 라벨과 반품 안내 PDF를 생성합니다.
주 API JSON Render
ENDPOINT
/api/v1/pdf/render 시스템 이커머스 백엔드 / 반품 포털 / OMS / 3PL 백엔드
해결할 작업
RMA, 고객, 상품, 목적지, 바코드 데이터에서 반품 라벨 PDF 또는 반품 안내서를 렌더링하여 반품 포털이 고객에게 결정적인 문서를 다운로드, 이메일, 재출력 형태로 제공할 수 있게 합니다.
이 API를 쓰는 경우
- 시스템이 이미 RMA와 반품 승인을 생성했습니다.
- 운송사 또는 반품 시스템이 이미 라벨 데이터나 운송장 데이터를 제공했습니다.
- 다운로드, 이메일 발송, 재출력이 가능한 PDF 라벨 또는 안내서가 필요합니다.
- 동일한 반품 라벨 레이아웃을 Template Render로 재사용하고 싶습니다.
대체하지 않는 것
- gPdf가 반품을 승인하거나 운임을 구매하거나 운송사 배송 건을 생성해야 합니다.
- 운송사 API를 직접 오케스트레이션해야 합니다.
- ZPL 같은 프린터 명령 출력이 필요합니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/template-render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/pdf/render - RMA 바코드가 포함된 반품 라벨.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 5,
"y": 8,
"content": "RETURN TO",
"style": { "font_size": 9, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 5,
"y": 18,
"content": "Acme Returns\n500 Dock Door 4\nColumbus OH 43215",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "RMA-2026-77881",
"x": 5,
"y": 70,
"width": 88,
"height": 20,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf가 처리하는 것
- 라벨 크기의 반품 라벨과 안내 페이지를 위한 PDF 렌더링.
- 바코드, 텍스트, 주소, RMA, 서비스 블록.
- 승인된 반품 라벨 또는 안내 레이아웃을 위한 템플릿 바인딩.
- 고객 재다운로드와 지원팀 재출력을 위한 결정적인 출력.
자체 시스템이 책임지는 것
- 반품 가능 여부, RMA 상태, 운송사 계정, 운임, 운송장 번호, 고객 안내.
- 정확한 바코드 데이터, 목적지 주소, 상품 참조, 반품 기간 규칙.
- 이메일 발송, 포털 다운로드, 지원 감사 추적.
운영 전 체크리스트
- 렌더링 전에 운송사 또는 반품 제공자와 반품 데이터를 검증합니다.
- 고객이나 매장이 사용할 동일한 용지에 라벨을 인쇄하고 스캔합니다.
- X-Request-Id를 포함하고 RMA와 PDF 사이의 추적 정보를 지원 로그에 저장합니다.
- 고객 관점에서 반복 다운로드가 멱등적으로 동작하게 합니다.
- 라벨 렌더링과 환불 승인 로직을 분리합니다.
지원 범위의 경계
- gPdf는 반품 라벨 PDF를 렌더링합니다. 반품을 승인하거나 운임을 구매하지 않습니다.
- 운송사 승인과 바코드 데이터의 정확성은 사용자가 담당합니다.
- 공개 API는 ZPL이나 직접 프린터 명령이 아니라 PDF를 반환합니다.
역물류에는 명확한 책임 경계가 필요합니다
반품 라벨은 고객 경험과 운송사 규칙이 만나는 지점입니다. gPdf는 PDF 렌더링을 담당합니다. 반품 시스템은 반품 가능 여부, RMA 상태, 운송장, 운송사 데이터, 고객 커뮤니케이션을 담당합니다.
이 경계를 통합 과정에서 분명하게 유지하세요. 먼저 반품 결정을 생성한 뒤, 확정된 데이터에서 문서를 렌더링합니다.
FAQ
- gPdf가 반품 배송 건을 생성하나요?
- 아니요. 운송사 또는 반품 플랫폼이 배송 건과 데이터를 생성합니다. gPdf는 그 데이터를 PDF로 렌더링합니다.
- 반품 라벨을 템플릿에서 생성할 수 있나요?
- 네. 반품 라벨 또는 안내 레이아웃이 승인된 뒤에는 Template Render를 사용하세요.
- PDF에 반품 안내를 포함할 수 있나요?
- 네. 같은 렌더 요청으로 레이아웃에 따라 라벨 페이지, 안내 페이지 또는 둘 다 만들 수 있습니다.
- gPdf가 운송사 인증을 대체하나요?
- 아니요. 운송사 승인, 스캐너 테스트, 바코드 데이터 규칙은 사용자의 책임입니다.