Factur-X와 ZUGFeRD PDF/A-3b를 위한 E-Invoice API
공개 gPdf e-invoice 엔드포인트를 통해 EN 16931 CII XML이 내장된 Factur-X 및 ZUGFeRD PDF/A-3b 전자 인보이스를 생성합니다.
/api/v1/e-invoice/render 사람이 읽을 수 있는 인보이스 PDF와 호출자가 제공한 EN 16931 CII XML을 Factur-X 또는 ZUGFeRD PDF/A-3b 전자 인보이스로 패키징해, 외부 PDF/A 및 전자 인보이스 레퍼런스 엔진으로 검증할 수 있게 합니다.
이 API를 쓰는 경우
- 일반 인보이스 PDF만이 아니라 Factur-X 또는 ZUGFeRD 출력이 필요합니다.
- 자체 시스템이 인보이스에 대해 올바른 EN 16931 CII XML을 제공할 수 있습니다.
- PDF/A-3b 패키징, 첨부 메타데이터, 전자 인보이스 XMP 연결이 필요합니다.
- 공개 capabilities 엔드포인트로 지원 표준과 프로파일을 확인하고 싶습니다.
대체하지 않는 것
- 일반 고객용 인보이스 PDF만 필요합니다. JSON Render 또는 Template Render를 사용하세요.
- OpenAPI 목록에 나열되기 전에 XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e, GST의 기본 지원 출력이 필요합니다.
- 불완전한 비즈니스 데이터에서 gPdf가 법적으로 올바른 인보이스 XML을 만들어주기를 기대합니다.
호출할 endpoint
/api/v1/e-invoice/render
E-Invoice Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/e-invoice/capabilities
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/e-invoice/render - 최소 Factur-X PDF/A-3b 요청.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf가 처리하는 것
- POST /api/v1/e-invoice/render를 통한 Factur-X 또는 ZUGFeRD PDF/A-3b 패키징.
- 호출자가 제공한 EN 16931 CII XML을 연관 파일로 내장.
- PDF/A-3b 래퍼 메타데이터와 표준별 전자 인보이스 XMP 연결.
- GET /api/v1/e-invoice/capabilities를 통한 기능 조회.
자체 시스템이 책임지는 것
- 인보이스의 비즈니스 의미, 세금 규칙, 구매자/판매자 식별자, EN 16931 XML 정확성.
- 수신자 업무 흐름에 Factur-X 또는 ZUGFeRD가 적합한지 선택.
- 수신자, AP 자동화 시스템, 현지 컴플라이언스 프로세스와의 외부 수락 테스트.
운영 전 체크리스트
- 표준이나 프로파일을 가정하기 전에 /api/v1/e-invoice/capabilities를 호출합니다.
- EN 16931 CII XML을 내장하기 전에 검증합니다.
- 출력을 /validator/ 또는 자체 레퍼런스 엔진 검증 흐름으로 검증합니다.
- 일반 인보이스 PDF 생성과 법적 전자 인보이스 패키징을 코드에서 분리합니다.
- 요청 ID, 표준, 프로파일, XML 원본 버전, 검증 증거를 로그로 남깁니다.
지원 범위의 경계
- 공개 기본 지원 전자 인보이스 출력은 EN 16931 CII XML을 포함한 Factur-X / ZUGFeRD입니다.
- 다른 국가별 전자 인보이스 명칭은 OpenAPI가 지원 표준으로 나열하지 않는 한 시장 맥락입니다.
- gPdf는 호출자가 제공한 XML을 패키징하며, XML의 비즈니스 정확성은 자체 시스템이 계속 책임집니다.
전자 인보이스 패키지를 위한 하나의 엔드포인트
전자 인보이스 엔드포인트가 존재하는 이유는 이 업무 흐름이 단순히 “인보이스 PDF를 렌더링“하는 일이 아니기 때문입니다. 호출자가 제공한 EN 16931 CII XML을 내장하면서, 올바른 연관 파일 메타데이터와 표준별 XMP를 가진 PDF/A-3b 래퍼를 만들어야 합니다.
필요한 출력이 Factur-X 또는 ZUGFeRD라면 POST /api/v1/e-invoice/render를
호출하세요. 통합 시스템이 작업을 보내기 전에 지원 표준, 프로파일, 문서 유형,
XML 형식을 확인해야 한다면 GET /api/v1/e-invoice/capabilities를
사용하세요.
gPdf 밖에 남는 것
XML의 비즈니스 의미는 자체 책임입니다. gPdf는 인보이스 번호가 법적으로 유효한지, 세액이 맞는지, 구매자 식별자가 거래 상대와 일치하는지, 특정 수신자가 업무 프로세스 변형을 받아들일지 알 수 없습니다. XML을 상위 시스템에서 생성하고 검증한 뒤, PDF/A-3b 패키징과 렌더링에 gPdf를 사용하세요.
로드맵 용어를 기본 지원 주장에 넣지 마세요
XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e, GST를 시장 맥락으로 언급하는 것은 타당합니다. 하지만 OpenAPI capabilities 계약이 해당 이름을 나열하지 않는 한, 공개 렌더러의 기본 지원 출력으로 제시하지 마세요.
FAQ
- 현재 공개 기본 지원 출력으로 제공되는 전자 인보이스 표준은 무엇인가요?
- 공개 기본 지원 출력은 EN 16931 CII XML이 내장된 Factur-X 및 ZUGFeRD PDF/A-3b입니다. 현재 계약은 /api/v1/e-invoice/capabilities에서 확인하세요.
- gPdf가 EN 16931 XML을 생성해 주나요?
- 아니요. 자체 시스템이 XML 내용을 제공합니다. gPdf는 필요한 첨부 메타데이터와 함께 이를 PDF/A-3b 전자 인보이스 래퍼에 패키징합니다.
- JSON Render에 settings.e_invoice를 보낼 수 있나요?
- 아니요. 전자 인보이스 패키징은 POST /api/v1/e-invoice/render에서 처리합니다. 공개 문서는 settings.e_invoice가 라우트별 설정이라고 명시합니다.
- 출력은 어떻게 검증해야 하나요?
- gPdf validator 또는 자체 레퍼런스 엔진 검증 흐름을 사용해 PDF/A 계층과 내장된 전자 인보이스 XML 계층을 모두 확인하세요.