개발자 워크플로
큐와 작업을 위한 배치 PDF 생성 API
자체 시스템이 분할, 재시도, 멱등성, 저장을 담당하는 동안, 큐에 안전한 JSON Render 또는 Template Render 흐름으로 많은 PDF를 생성합니다.
주 API Template Render
ENDPOINT
/api/v1/template-render 시스템 작업 큐 / SaaS 백엔드 / ERP 내보내기 서비스 / 청구 워커
해결할 작업
큐나 예약 작업에서 안전한 요청 단위로 작업을 나누고, 각 문서 또는 템플릿 data 항목을 gPdf로 보낸 뒤, 반환된 PDF를 자체 시스템에 저장하거나 전달해 많은 PDF를 렌더링합니다.
이 API를 쓰는 경우
- 인보이스, 명세서, 라벨, 보고서를 예약 또는 이벤트 기반 배치로 생성해야 합니다.
- 안정적인 템플릿이 있고 엔드포인트 한도 안에서 여러 data 항목을 보낼 수 있습니다.
- 브라우저 워커를 운영하지 않고 큐 친화적인 렌더링이 필요합니다.
- 중복 제거, 재시도, 출력 저장을 자체 시스템에서 담당할 수 있습니다.
대체하지 않는 것
- gPdf가 배치 스케줄러, 큐, 저장 시스템, 멱등성 장부 역할을 해야 합니다.
- 공개 rate-limit headers 또는 서버 측 idempotency-key 계약이 필요합니다.
- 캠페인의 모든 문서를 요청 하나에 제한 없이 담아 렌더링해야 합니다.
호출할 endpoint
/api/v1/template-render
Template Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/pdf/render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/template-render - 인보이스 data 항목 두 개로 구성된 작은 배치.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
gPdf가 처리하는 것
- 각 JSON Render 또는 Template Render 요청의 PDF 렌더링.
- 문서화된 공개 한도 안의 Template Render data 배열.
- 큐 워커에 적합한 빠르고 상태 없는 렌더링 응답.
- 공통 요청 ID와 오류 envelope 동작.
자체 시스템이 책임지는 것
- 큐 설계, 분할, 동시성, 재시도, 중복 제거, 출력 저장.
- 업무 객체 선택, 템플릿 선택, 전달 흐름.
- 부분 실패 이후의 backoff 정책, 알림, 복구.
운영 전 체크리스트
- 각 요청이 문서화된 항목 수와 요청 데이터 한도 안에 있도록 작업을 나눕니다.
- 요청마다 하나의 X-Request-Id를 생성하고 자체 job ID에 매핑합니다.
- 네트워크 또는 5xx 실패만 제한된 지수 backoff로 재시도합니다.
- 요청 데이터를 바꾸지 않고 4xx 검증 실패를 재시도하지 않습니다.
- 보관 정책에 따라 출력 PDF 또는 원본 데이터를 저장합니다.
지원 범위의 경계
- gPdf는 렌더링 API이지 큐나 저장 계층이 아닙니다.
- 현재 공개 API는 rate-limit headers나 서버 측 idempotency keys를 공개하지 않습니다.
- 재시도가 안전하도록 만드는 책임은 자체 시스템에 있습니다.
배치 생성은 연동 패턴입니다
배치 PDF 생성은 별도의 엔드포인트가 아닙니다. 자체 큐가 공개 렌더링 API를 사용하는 방식입니다. 작업은 작고 관측 가능하며 재시도에 안전하게 유지하세요.
반복되는 레이아웃에는 보통 Template Render가 가장 깔끔한 계약을 제공합니다. 맞춤 레이아웃으로 프로그램이 생성하는 문서에는 JSON Render를 계속 사용할 수 있습니다.
FAQ
- gPdf가 배치 작업 API를 제공하나요?
- 별도의 배치 스케줄러는 공개되어 있지 않습니다. 자체 큐나 워커 시스템에서 JSON Render 또는 Template Render를 호출하세요.
- Template Render가 여러 data 항목을 받을 수 있나요?
- 예, 공개 엔드포인트 한도 안에서 가능합니다. 더 큰 작업은 여러 요청으로 나누세요.
- 재시도는 누가 담당하나요?
- 재시도, backoff, 중복 제거, 멱등성은 자체 시스템이 담당합니다. gPdf는 추적성을 위해 요청 ID를 echo합니다.
- 요청 하나로 여러 다른 레이아웃을 렌더링할 수 있나요?
- 레이아웃이나 template ID가 다르면 별도 요청을 사용하세요. 각 요청을 단순하고 추적 가능하게 유지하는 것이 좋습니다.