청구 및 재무 시스템을 위한 인보이스 PDF API
세금과 회계 로직은 자체 시스템에 둔 채, JSON Render 또는 Template Render로 청구 데이터를 일반 인보이스 PDF로 생성합니다.
/api/v1/pdf/render 청구, ERP, SaaS 시스템의 인보이스 데이터를 읽기 쉬운 PDF 인보이스로 변환하되, 번호 체계, 세금, 결제 상태, 회계상 의미는 호출자 시스템 안에 유지합니다.
이 API를 쓰는 경우
- 고객용 인보이스, 영수증, 명세서, 회계 내보내기에 사용할 일반 인보이스 PDF가 필요합니다.
- 인보이스 번호, 세금 계산, 품목 라인, 결제 상태를 이미 자체 시스템이 관리합니다.
- 브라우저를 운영하지 않고 표, 합계, 메타데이터, 선택적 PDF/A 설정이 필요합니다.
- 반복되는 인보이스 레이아웃에 대해 안정적인 template_id 계약을 원합니다.
대체하지 않는 것
- Factur-X 또는 ZUGFeRD 같은 법적 전자 인보이스 패키지가 필요합니다. 이 경우 E-Invoice Render를 사용하세요.
- gPdf가 세금을 계산하거나, 회계 규칙을 검증하거나, 결제를 대사하기를 기대합니다.
- 구조화된 JSON 또는 템플릿이 아니라 임의의 HTML 인보이스 변환을 원합니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/template-render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
/api/v1/e-invoice/render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/pdf/render - 최소 인보이스 헤더와 합계.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
gPdf가 처리하는 것
- JSON 페이지 또는 템플릿 데이터에서 인보이스 PDF를 렌더링합니다.
- 텍스트, 표, 합계 블록, 페이지 나누기, 메타데이터, 선택적 PDF/A 출력을 처리합니다.
- 여러 시스템에서 쓰는 안정적인 인보이스 레이아웃에는 Template Render를 제공합니다.
- 바이너리 PDF 응답과 일관된 API 오류 envelope를 제공합니다.
자체 시스템이 책임지는 것
- 인보이스 번호, 결제 상태, 세금 계산, 할인, 크레딧, 원장상 의미.
- 고객 및 발행자 데이터, 품목 라인 매핑, 통화, 반올림 규칙.
- 보관, 전달, 이메일, 결제 링크, 회계 시스템 대사.
운영 전 체크리스트
- 화면에 보이는 모든 인보이스 필드가 원본 청구 데이터에 매핑되는지 확인합니다.
- 품목 라인 overflow, 긴 고객명, 여러 페이지 인보이스, 합계를 테스트합니다.
- 레이아웃을 JSON Render에 둘지, 게시된 템플릿에 둘지 결정합니다.
- 일반 인보이스 PDF 생성과 법적 전자 인보이스 패키징을 코드에서 분리합니다.
- 요청 ID와 출력 파일명을 인보이스 기록과 함께 저장합니다.
지원 범위의 경계
- 일반 인보이스 PDF는 법적 전자 인보이스 의무와 동일하지 않습니다.
- gPdf는 인보이스 문서를 렌더링하지만 세금이나 회계 상태를 계산하지 않습니다.
- Factur-X / ZUGFeRD 출력은 POST /api/v1/e-invoice/render에서 처리합니다.
일반 인보이스와 전자 인보이스
일반 인보이스 PDF는 고객이 읽는 문서입니다. JSON Render 또는 Template Render에서 생성할 수 있습니다. 인보이스 번호, 세금, 품목 라인, 통화, 결제 상태는 자체 시스템이 결정하고, gPdf는 보이는 PDF를 렌더링합니다.
법적 전자 인보이스는 다릅니다. Factur-X와 ZUGFeRD는 읽을 수 있는 PDF/A-3b
인보이스와 내장된 EN 16931 CII XML을 결합합니다. 이 패키지에는
POST /api/v1/e-invoice/render를 사용하세요.
Template Render가 보통 프로덕션 엔드포인트입니다
재무 팀은 각 서비스가 인보이스 좌표를 매번 다시 만들기를 원하지 않습니다.
일반적인 경로는 인보이스를 한 번 디자인해 템플릿으로 게시하고, 호출자에게
안정적인 template_id와 데이터 schema를 제공하는 것입니다. JSON Render는
커스텀 레이아웃, 내부 도구, 템플릿 프로토타이핑에 계속 유용합니다.
회계 로직은 upstream에 유지하세요
gPdf에는 아직 확정되지 않은 회계 판단이 아니라 최종 표시 값을 보내야 합니다. 렌더 API를 호출하기 전에 세금, 할인, 반올림, 결제 상태, 인보이스 발행 가능 여부를 계산하세요. 이렇게 하면 PDF 출력은 결정적으로 유지되고, 재무 시스템은 단일 기준으로 남습니다.
FAQ
- 인보이스 PDF와 전자 인보이스는 같은 것인가요?
- 아니요. 일반 인보이스 PDF는 사람이 읽는 출력물입니다. Factur-X 또는 ZUGFeRD 전자 인보이스는 PDF/A-3b 래퍼 안에 EN 16931 CII XML도 포함합니다.
- 반복 발행되는 인보이스에는 어느 엔드포인트를 써야 하나요?
- 인보이스 레이아웃이 안정적이고 호출자가 template_id와 data만 보내야 한다면 Template Render를 사용하세요. 코드가 레이아웃을 직접 관리한다면 JSON Render를 사용하세요.
- gPdf가 세금을 계산하나요?
- 아니요. 청구 또는 회계 시스템이 세금, 합계, 할인, 결제 상태를 계산한 뒤 렌더링 데이터를 보냅니다.
- 인보이스 PDF에 PDF/A를 사용할 수 있나요?
- 네, JSON Render는 PDF/A 설정을 지원합니다. 인보이스를 Factur-X 또는 ZUGFeRD로 패키징해야 할 때는 E-Invoice Render를 사용하세요.