바코드와 리테일
문서와 라벨을 위한 QR 코드 PDF API
JSON Render 또는 템플릿을 사용해 영수증, 티켓, 라벨, 온보딩 패킷, 문서 조회 워크플로용 QR 코드를 PDF 안에 렌더링합니다.
주 API JSON Render
ENDPOINT
/api/v1/pdf/render 시스템 SaaS 백엔드 / 이커머스 백엔드 / 티켓팅 백엔드 / 문서 자동화 서비스
해결할 작업
사용자가 링크, 식별자 또는 조회 토큰을 스캔할 수 있도록 호출 시스템이 통제하는 QR 코드를 PDF 문서, 라벨, 영수증, 티켓 또는 양식에 배치합니다.
이 API를 쓰는 경우
- 시스템에 인코딩할 URL, 토큰, 주문 ID, 티켓 ID 또는 조회 값이 있습니다.
- QR 코드를 외부 비트맵으로 합성하는 대신 PDF 안에 직접 그려야 합니다.
- Template Render를 통해 반복되는 QR 기반 레이아웃이 필요합니다.
- 텍스트, 레이아웃, PDF 출력, QR 코드 렌더링에 하나의 API 경로를 사용하고 싶습니다.
대체하지 않는 것
- gPdf에서 URL 단축, 접근 토큰 발급 또는 결제 링크 생성을 받아야 합니다.
- 스캐너 분석 또는 모바일 앱 로직이 필요합니다.
- PDF 출력 밖에서 QR 코드가 필요합니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/template-render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/pdf/render - QR 조회 코드가 있는 문서 페이지.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Scan to view this document online",
"style": { "font_size": 14, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "qrcode",
"content": "https://example.com/documents/DOC-2026-001",
"x": 20,
"y": 44,
"width": 32,
"height": 32
}
]
}
]
}
gPdf가 처리하는 것
- PDF 출력 내부의 벡터 QR 바코드 렌더링.
- QR 코드 주변의 텍스트, 레이아웃, 영수증, 티켓, 라벨 또는 문서 맥락.
- 반복되는 QR 워크플로를 위한 템플릿 바인딩.
- 공개 Render API를 통한 PDF 응답 전달.
자체 시스템이 책임지는 것
- 인코딩된 URL 또는 토큰, 접근 제어, 만료, 리다이렉트 동작, 모바일 목적지.
- 스캐너 테스트, 사용자 여정, 부정 사용 방지 규칙.
- 스캔 후 트리거되는 결제, 티켓, 반품 또는 계정 작업.
운영 전 체크리스트
- 문서 수명 동안 인코딩된 URL이 안정적이거나 리다이렉트 가능하도록 유지합니다.
- 스캔 거리, 대비, 크기, 인쇄 소재를 테스트합니다.
- 민감한 원시 데이터를 QR 데이터에 직접 넣지 않습니다.
- 요청 ID를 사용하고 각 생성 PDF와 연결된 비즈니스 객체를 기록합니다.
- 안정된 QR 레이아웃은 Template Render로 옮깁니다.
지원 범위의 경계
- gPdf는 PDF 안에 QR 코드를 렌더링하며, 목적지를 호스팅하거나 보호하지 않습니다.
- 토큰 만료, 리다이렉트, 권한, 스캐너 UX는 호출 시스템의 책임입니다.
- QR 코드 자체는 결제 시스템이나 티켓팅 시스템이 아닙니다.
QR 코드 페이지에도 명확한 의미가 필요합니다
QR 코드는 눈에 보이는 전달 수단일 뿐입니다. 운영 워크플로는 그 뒤의 목적지나 토큰에 달려 있습니다. gPdf는 QR 코드를 PDF 안에 그립니다. 스캔 후 어떤 일이 일어나는지는 호출 시스템이 책임집니다.
FAQ
- gPdf가 QR 코드 이미지를 생성하나요?
- gPdf는 PDF 출력 안에 QR 코드 바코드 요소를 렌더링합니다. 공개 응답은 독립 이미지 서비스가 아니라 PDF입니다.
- 템플릿에서 QR 코드를 사용할 수 있나요?
- 예. 템플릿에 QR 필드를 포함할 수 있으며, 호출자는 가변 요청 데이터를 보낼 수 있습니다.
- QR 목적지는 누가 관리하나요?
- URL, 토큰, 리다이렉트, 권한, 만료 동작은 호출 시스템이 관리합니다.
- QR 코드에 민감한 데이터를 넣을 수 있나요?
- 보낸 데이터는 무엇이든 인코딩할 수 있지만, 운영 시스템에서는 일반적으로 원시 민감 데이터 대신 조회 토큰이나 URL을 인코딩해야 합니다.