보관 및 전자 인보이스 워크플로를 위한 PDF/A-3b API
gPdf로 PDF/A-3b 출력을 생성하고, PDF/A-3b가 단순 보관 프로파일인 경우와 전자 인보이스 래퍼인 경우를 구분합니다.
/api/v1/pdf/render 보관 워크플로를 위해 PDF/A-3b 문서를 생성하고, PDF/A-3b가 내장 Factur-X 또는 ZUGFeRD EN 16931 XML을 담아야 할 때 전자 인보이스 엔드포인트를 선택합니다.
이 API를 쓰는 경우
- 렌더링된 문서에 PDF/A-3b 보관 프로파일이 필요합니다.
- 일반 PDF/A와 전자 인보이스 패키징의 경계를 설명해야 합니다.
- 컴플라이언스 워크플로가 veraPDF 또는 다른 기준 엔진으로 생성된 PDF를 검증합니다.
- PDF/A-3b 검색 의도를 올바른 엔드포인트로 연결하는 공개 페이지가 필요합니다.
대체하지 않는 것
- 공개 API에 문서화되지 않은 임의 파일 첨부 워크플로가 필요합니다.
- JSON Render를 통해 Factur-X 또는 ZUGFeRD 전자 인보이스가 필요합니다. E-Invoice Render를 사용하세요.
- 검증기 API가 필요합니다. 현재 공개 검증 표면은 /validator/ 페이지입니다.
호출할 endpoint
/api/v1/pdf/render
JSON Render가 이 처리 흐름의 기본 경로입니다.
/api/v1/e-invoice/render
관련 API 경로, 템플릿 계약 또는 capability 조회가 필요할 때 사용합니다.
최소 request
POST /api/v1/pdf/render - 렌더링된 문서에 PDF/A-3b 출력을 요청.
{
"settings": {
"profile": "pdfa-3b"
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Archive copy",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf가 처리하는 것
- JSON Render 설정을 통한 PDF/A 프로파일 선택.
- POST /api/v1/e-invoice/render 사용 시 PDF/A-3b 전자 인보이스 패키징.
- 외부 기준 엔진 검증에 사용할 수 있는 렌더링 가능한 PDF 출력.
- 보관 프로파일과 법적 전자 인보이스 워크플로의 명확한 분리.
자체 시스템이 책임지는 것
- 보존 정책과 PDF/A-3b가 필요한 이유.
- 비즈니스 데이터, XML의 업무상 의미, 외부 컴플라이언스 승인 기준.
- 렌더링 이후의 검증 증거, 감사 기록, 장기 저장.
운영 전 체크리스트
- 일반 PDF/A-3b 출력에는 JSON Render를 선택합니다.
- 내장 EN 16931 XML이 필요하면 E-Invoice Render를 선택합니다.
- /validator/ 또는 자체 veraPDF 워크플로로 PDF/A 출력을 검증합니다.
- 요청한 프로파일과 요청 ID를 저장된 문서와 함께 기록합니다.
- 공개 문서에 명시되지 않은 임의 첨부 지원을 주장하지 않습니다.
지원 범위의 경계
- PDF/A-3b는 보관 프로파일이며, 전자 인보이스 패키징은 그 위에 얹히는 더 좁은 워크플로입니다.
- 모든 임의 내장 파일 워크플로가 지원된다고 암시하지 마세요.
- Factur-X와 ZUGFeRD PDF/A-3b 패키지에는 전자 인보이스 경로가 필요합니다.
PDF/A-3b는 래퍼이지 전체 워크플로가 아닙니다
PDF/A-3b는 PDF 보관 프로파일입니다. 하이브리드 전자 인보이스의 래퍼가 될 수 있기 때문에 중요하지만, 프로파일만으로 문서가 법적 전자 인보이스가 되지는 않습니다. 일반 보관 문서도 내장 인보이스 XML 없이 PDF/A-3b를 사용할 수 있습니다.
Factur-X와 ZUGFeRD에는 POST /api/v1/e-invoice/render를 사용하세요. 이
엔드포인트가 전자 인보이스 전용 메타데이터와 관련 파일 연결을 담당합니다.
의도에 따라 엔드포인트를 선택하세요
목표가 “이 문서를 PDF/A-3b로 렌더링“하는 것이라면 JSON Render를 사용하세요. 목표가 “이 인보이스를 EN 16931 CII XML이 포함된 Factur-X 또는 ZUGFeRD로 패키징“하는 것이라면 E-Invoice Render를 사용하세요. 이 구분은 코드를 명확하게 유지하고, 일반 보관 작업이 전자 인보이스 전제를 실수로 포함하지 않도록 합니다.
외부에서 검증하세요
PDF/A는 마케팅 문구가 아니라 기준 엔진으로 검증해야 합니다. 공개 검증기 또는 자체 검증 파이프라인을 사용하고, 보고서를 감사 증거와 함께 보관하세요.
FAQ
- PDF/A-3b는 항상 전자 인보이스인가요?
- 아니요. PDF/A-3b는 보관용 PDF 프로파일입니다. Factur-X와 ZUGFeRD 전자 인보이스는 내장 EN 16931 XML을 담는 래퍼로 PDF/A-3b를 사용합니다.
- 어떤 엔드포인트가 PDF/A-3b를 생성하나요?
- 일반 PDF/A-3b에는 settings.profile을 지정해 POST /api/v1/pdf/render를 사용하세요. 출력이 Factur-X 또는 ZUGFeRD 전자 인보이스여야 하면 POST /api/v1/e-invoice/render를 사용하세요.
- 이 페이지를 통해 임의 파일을 첨부할 수 있나요?
- 공개 API 문서에 해당 워크플로가 명시되어 있지 않다면 임의 첨부 지원을 가정하지 마세요. 이 페이지는 문서화된 PDF/A-3b와 전자 인보이스 사용에 초점을 둡니다.
- PDF/A 출력은 어떻게 검증하나요?
- /validator/ 또는 자체 기준 엔진 파이프라인을 사용하세요. 전자 인보이스의 경우 PDF/A 계층과 내장 XML 계층을 모두 검증하세요.