개발자 워크플로
안정적인 문서 계약을 위한 템플릿 PDF API
반복되는 레이아웃을 한 번 관리하고 ERP, OMS, WMS, SaaS 호출자가 재사용해야 할 때, 안정적인 template_id와 data 배열로 PDF를 렌더링합니다.
주 API Template Render
ENDPOINT
/api/v1/template-render 시스템 SaaS 백엔드 / ERP 연동 / OMS / WMS / 작업 큐
해결할 작업
호출자마다 매 요청에서 페이지, 좌표, 레이아웃 요소를 설명하게 하지 않고, 안정적인 template_id와 업무 데이터 배열을 보내 반복되는 PDF를 렌더링합니다.
이 API를 쓰는 경우
- 문서 레이아웃이 승인되었고 여러 호출자나 작업에서 재사용됩니다.
- 호출자가 좌표 수준의 레이아웃 JSON이 아니라 업무 데이터를 보내야 합니다.
- 인보이스, 포장 명세서, 배송 라벨, 맞춤 템플릿 출력이 필요합니다.
- 활성 템플릿 개정을 호출자 밖에서 통제하려고 합니다.
대체하지 않는 것
- 아직 레이아웃을 설계 중입니다. 좌표와 필드가 안정될 때까지 JSON Render를 사용하세요.
- 임의의 HTML-PDF 변환이 필요합니다.
- CII XML을 포함한 전자 인보이스 PDF/A-3b 패키징이 필요합니다.
호출할 endpoint
/api/v1/template-render
Template Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/pdf/render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/template-render - 템플릿에서 인보이스 하나를 렌더링합니다.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
gPdf가 처리하는 것
- 안정적인 template_id로 템플릿 조회.
- 각 data 항목을 활성 템플릿에 맞춰 렌더링.
- 공개 엔드포인트 한도 안에서 렌더링된 페이지를 하나의 PDF로 결합.
- 공통 인증, 요청 ID, 오류 envelope 동작.
자체 시스템이 책임지는 것
- 템플릿 선택, 필드 매핑, 업무 데이터, 호출자 권한 부여.
- 템플릿 게시 흐름, 변경 안내, 테스트 커버리지.
- 많은 문서를 렌더링할 때의 분할, 큐잉, 재시도.
운영 전 체크리스트
- template_id를 불투명하고 안정적인 계약으로 취급합니다.
- Template Render를 호출하기 전에 data 필드를 검증합니다.
- 활성 템플릿과 대표 데이터에 대한 golden PDF 테스트를 유지합니다.
- 대용량 배치는 공개 Template Render 한도에 맞게 나눕니다.
- 추적성을 위해 template_id, 요청 ID, 업무 객체 ID를 로깅합니다.
지원 범위의 경계
- Template Render 자체는 디자인 도구가 아닙니다. 템플릿은 이미 게시되어 있어야 합니다.
- gPdf는 템플릿에서 누락된 업무 데이터를 추론하지 않습니다.
- Template Render는 E-Invoice Render 엔드포인트를 대체하지 않습니다.
Template Render는 운영 계약 계층입니다
JSON Render는 레이아웃을 설계하는 동안에 적합합니다. Template Render는 레이아웃이 계약이 된 뒤 사용하는 계층입니다. 호출자는 template_id와 data를 보내고, 활성 템플릿이 문서 구조를 담당합니다.
이 방식은 호출자를 더 작게 유지하고 템플릿 변경을 검토, 테스트, 배포하기 쉽게 만듭니다.
FAQ
- 언제 JSON Render 대신 Template Render를 사용해야 하나요?
- 레이아웃이 승인되었고 호출자가 업무 데이터만 보내야 할 때 Template Render를 사용하세요.
- template_id는 안정적인가요?
- 예. 템플릿 API 문서는 template_id를 호출자에게 노출되는 안정적인 식별자로 설명합니다.
- 요청 하나로 여러 data 항목을 렌더링할 수 있나요?
- 예. Template Render는 공개 엔드포인트 한도 안에서 data 배열을 받습니다.
- Template Render로 전자 인보이스를 만들 수 있나요?
- 아니요. Factur-X / ZUGFeRD PDF/A-3b 패키징에는 E-Invoice Render 엔드포인트를 사용합니다.