Barcodes and retail
운영 시스템용 SSCC 라벨 API
SSCC 라벨을 구조화된 backend 데이터에서 브라우저 없이 생성합니다. gPdf는 PDF 렌더링을 맡고, 업무 규칙은 자체 시스템에 남습니다.
주 API JSON Render
ENDPOINT
/api/v1/pdf/render 시스템 운영 backend / 재무 시스템 / 컴플라이언스 workflow / 문서 서비스
해결할 작업
SSCC 라벨을 구조화된 데이터에서 재현 가능한 PDF로 생성합니다. gPdf는 문서를 렌더링하고, 데이터 의미와 프로세스 상태는 자체 시스템이 유지합니다.
이 API를 쓰는 경우
- Backend에 SSCC 라벨 데이터가 이미 있고 안정적인 PDF 응답이 필요합니다.
- 운영 문서에서 Chromium 또는 HTML-to-PDF를 피하고 싶습니다.
- 재출력, 감사, 배치 처리를 위해 반복 가능한 출력이 필요합니다.
대체하지 않는 것
- gPdf는 배송 구매, 세금 신고, 외부 주문 생성, 세무 시스템 역할을 하지 않습니다.
- 데이터 검증, 비즈니스 규칙, marketplace 연동을 대체하지 않습니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 워크플로의 기본 경로입니다.
/api/v1/template-render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
/api/v1/pdf/render - SSCC 라벨
{
"pages": [
{
"size": "label_100_150",
"elements": [
{
"type": "text",
"x": 6,
"y": 8,
"content": "SSCC",
"style": { "font_size": 12, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "sscc-18",
"content": "000123456789012345",
"x": 6,
"y": 28,
"width": 86,
"height": 30,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf가 처리하는 것
- 구조화된 request에서 SSCC 라벨 PDF 렌더링.
- Request에 따른 텍스트, 표, 선, 바코드, 페이지, metadata, 출력 설정.
- Retry, 재출력, 감사용 결정적 출력.
자체 시스템이 책임지는 것
- SSCC 라벨의 정확한 데이터, 비즈니스 규칙, 운영 상태.
- 인증, 저장, 외부 workflow, 수신 시스템 검증.
운영 전 체크리스트
- 실제 데이터와 PDF를 소비할 시스템으로 테스트합니다.
- 지원, 감사, 재출력을 위해 request ID와 검증 증거를 저장합니다.
- 승인된 layout을 여러 시스템이 쓰면 template으로 전환합니다.
지원 범위의 경계
- gPdf는 라벨 PDF를 렌더링하지만 배송 구매, shipment 생성, 운송사 인증은 하지 않습니다.
- Payload, 프린터, 라벨 용지, routing, 스캔 테스트는 자체 시스템 책임입니다.
API 형태
SSCC 라벨 API는 공개 gPdf API 위에서 동작하는 운영 workflow입니다. Request는 데이터, layout, settings, 렌더링할 PDF 요소를 명시합니다. gPdf는 PDF를 만들고, 비즈니스 이벤트의 의미는 자체 시스템이 유지합니다.
Endpoint 선택
이 workflow의 기본 endpoint는 /api/v1/pdf/render입니다. Layout이 승인되어 여러 시스템에서 재사용되면 Template Render를 사용합니다. EN 16931 CII XML을 포함한 Factur-X / ZUGFeRD PDF/A-3b 패키징이 필요할 때만 E-Invoice Render를 사용합니다.
운영 전 검증
SSCC 라벨을 실제 데이터와 downstream 시스템으로 검증하세요. 지원, 감사, 재출력을 위해 request ID, 렌더링 결과, 검증 증거를 저장합니다.
FAQ
- 별도 endpoint인가요?
- SSCC 라벨 API는 workflow를 공개 gPdf API 중 하나에 매핑합니다. 이 페이지는 호출할 path와 request가 책임질 내용을 설명합니다.
- Templates를 사용할 수 있나요?
- 네. Layout이 자주 바뀌면 JSON Render를 쓰고, layout이 승인되어 callers가 비즈니스 데이터만 보내면 Template Render를 사용합니다.
- 운영 전에 무엇을 검증해야 하나요?
- 실제 데이터와 프린터, 스캐너, validator, 회계 시스템 또는 marketplace 수신 경로로 검증합니다.