Compliance and archival
운영 시스템용 Factur-X 인보이스 API
Factur-X 인보이스을 구조화된 backend 데이터에서 브라우저 없이 생성합니다. gPdf는 PDF 렌더링을 맡고, 업무 규칙은 자체 시스템에 남습니다.
주 API E-Invoice Render
ENDPOINT
/api/v1/e-invoice/render 시스템 운영 backend / 재무 시스템 / 컴플라이언스 workflow / 문서 서비스
해결할 작업
Factur-X 인보이스을 구조화된 데이터에서 재현 가능한 PDF로 생성합니다. gPdf는 문서를 렌더링하고, 데이터 의미와 프로세스 상태는 자체 시스템이 유지합니다.
이 API를 쓰는 경우
- Backend에 Factur-X 인보이스 데이터가 이미 있고 안정적인 PDF 응답이 필요합니다.
- 운영 문서에서 Chromium 또는 HTML-to-PDF를 피하고 싶습니다.
- 재출력, 감사, 배치 처리를 위해 반복 가능한 출력이 필요합니다.
대체하지 않는 것
- gPdf는 배송 구매, 세금 신고, 외부 주문 생성, 세무 시스템 역할을 하지 않습니다.
- 데이터 검증, 비즈니스 규칙, marketplace 연동을 대체하지 않습니다.
호출할 endpoint
/api/v1/e-invoice/render
E-Invoice Render가 이 워크플로의 기본 경로입니다.
/api/v1/e-invoice/capabilities
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
/api/v1/e-invoice/render - Factur-X 인보이스
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Factur-X invoice",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf가 처리하는 것
- 구조화된 request에서 Factur-X 인보이스 PDF 렌더링.
- Request에 따른 텍스트, 표, 선, 바코드, 페이지, metadata, 출력 설정.
- Retry, 재출력, 감사용 결정적 출력.
자체 시스템이 책임지는 것
- Factur-X 인보이스의 정확한 데이터, 비즈니스 규칙, 운영 상태.
- 인증, 저장, 외부 workflow, 수신 시스템 검증.
운영 전 체크리스트
- 실제 데이터와 PDF를 소비할 시스템으로 테스트합니다.
- 지원, 감사, 재출력을 위해 request ID와 검증 증거를 저장합니다.
- 승인된 layout을 여러 시스템이 쓰면 template으로 전환합니다.
지원 범위의 경계
- gPdf는 Factur-X / ZUGFeRD PDF/A-3b에 공개 e-invoice endpoint를 사용합니다.
- 세금 포털, PDP, SDI, KSeF, ZATCA, IRP, Peppol 및 법적 의무는 범위 밖입니다.
- Buyer data, 세금 로직, routing, 현지 법적 판단은 자체 시스템 책임입니다.
API 형태
Factur-X 인보이스 API는 공개 gPdf API 위에서 동작하는 운영 workflow입니다. Request는 데이터, layout, settings, 렌더링할 PDF 요소를 명시합니다. gPdf는 PDF를 만들고, 비즈니스 이벤트의 의미는 자체 시스템이 유지합니다.
Endpoint 선택
이 workflow의 기본 endpoint는 /api/v1/e-invoice/render입니다. Layout이 승인되어 여러 시스템에서 재사용되면 Template Render를 사용합니다. EN 16931 CII XML을 포함한 Factur-X / ZUGFeRD PDF/A-3b 패키징이 필요할 때만 E-Invoice Render를 사용합니다.
운영 전 검증
Factur-X 인보이스을 실제 데이터와 downstream 시스템으로 검증하세요. 지원, 감사, 재출력을 위해 request ID, 렌더링 결과, 검증 증거를 저장합니다.
FAQ
- 별도 endpoint인가요?
- Factur-X 인보이스 API는 Factur-X / ZUGFeRD PDF/A-3b가 필요할 때 공개 e-invoice endpoint를 사용합니다. 별도 제품 표면은 아닙니다.
- 현지 세금 clearance 네트워크도 포함되나요?
- 아니요. gPdf는 PDF/e-invoice 파일을 렌더링하고 패키징합니다. 세금 포털과 법적 routing은 자체 시스템 범위입니다.
- JSON Render를 계속 써도 되나요?
- 일반 PDF에는 가능합니다. 구조화된 e-invoice 패키지가 필요할 때 E-Invoice Render를 사용합니다.