Enterprise 에디션

Invoice — 심층 참조

한눈에 보기

Invoice 모듈에는 임베딩, 검증, Schematron 규칙 실행이라는 세 개의 독립적인 표면이 있습니다. ZugferdEmbedder와 PeppolEmbedder는 호출자가 제공한 송장 XML을 PDF/A-4f 또는 PDF/A-3b 캐리어에 첨부하고 구조화된 결과를 반환합니다. InvoiceXmlValidator는 선택 가능한 COMPAT 또는 STRICT 심각도로 EN 16931 구조 사전 점검을 실행합니다. SchematronValidator는 사전 컴파일된 Schematron 규칙 팩을 인프로세스로 실행하고 SVRL 발견 사항을 파싱합니다. NextPDF는 송장 XML을 생성하지 않습니다. 호출자가 페이로드를 공급하고 소유합니다.

가용성 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되며 Enterprise 등급 라이선스 엔벨로프로 활성화됩니다. 해당 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

등급별 차이: 전자송장 탐지 및 검증은 Pro 등급 표면(Pro Compliance 모듈)입니다. 하이브리드 송장 임베딩, XRechnung CIUS 프로필, 인프로세스 Schematron 엔진은 Enterprise 전용입니다. nextpdf/enterprise 패키지 경계를 넘어서는 별도의 기능별 기능 코드는 없습니다.

공개 API 표면

composer require nextpdf/enterprise:^3

심볼	매개변수	기본 동작	반환	발생시키거나 실패하는 예외	비고
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	BASIC 프로필 CII XML 임베드: XmlGuard 통과, 구조 검증, XMP 스키마 주입, 첨부	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	빠른 경로. 권장 시작점
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	MINIMUM 프로필에서 동일한 파이프라인	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	빠른 경로
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	빌더 진입점. 빈 XML 거부	`self`	`InvalidArgumentException`	`withoutValidation()`, `withDescription()`로 구성
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	기본 `/Alternative` 관계 재정의. 연관 파일 규칙집으로 게이트됨	`self`	`InvalidArgumentException`	송장에는 `Schema`, `EncryptedPayload`, `FormData` 거부
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	종단 빌더 호출: XmlGuard, 선택적 검증, 캐리어 확인, XMP, 첨부	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	검증 실패 시 첫 번째 오류를 명시
`ZugferdProfile` (enum)	—	케이스 MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG은 `xrechnung.xml` 첨부. CII 프로필은 `factur-x.xml` 첨부
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Factur-X RDF 서술과 PDF/A 확장 스키마 항목 등록	`XmpMetadata`	없음	`embed()`가 호출. 직접 사용도 가능
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Peppol BIS 3.0 UBL 송장 또는 대변표 XML 임베드	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	기본 파일명 `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	빌더 진입점. 빈 XML 또는 파일명 거부	`self`	`InvalidArgumentException`	`withFilename()`, `withDescription()`, `withoutSanitization()`로 구성
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	XmlGuard 통과, 캐리어 확인, 규칙집 게이트, 첨부	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	임베드 시점의 캐리어 인식 규칙집 재검사
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	EN 16931 구조 사전 점검. 기본 COMPAT 심각도	`InvoiceValidationResult`	예외를 발생시키지 않음. 실패는 오류 발견 사항으로 표면화	모드는 인자, 다음 환경, 다음 COMPAT 순으로 해석
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	CII 페이로드에 대한 루트 요소 및 네임스페이스 확인	`bool`	예외를 발생시키지 않음. `false` 반환	저비용 탐지 프로브
`InvoiceValidatorMode` (enum)	—	`COMPAT`(기본값)는 BT-24 발견 사항을 경고로 유지. `STRICT`는 오류로 승격	—	—	`fromEnvironment()`는 미설정 또는 미인식 값에서 COMPAT로 폴백
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	불변 집계: `isValid`, `getErrors()`, `getWarnings()`. 발견 사항별 level, code, message	—	—	`InvoiceValidationResult::fail()`은 단일 오류를 래핑
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	사전 컴파일된 Schematron XSLT 실행. SVRL을 발견 사항으로 파싱	`SchematronResult`	누락되거나 읽을 수 없는 XSLT에 대해 `InvalidArgumentException`. 엔진 실패는 오류 결과 반환	소요 시간은 `durationMs`에 기록
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	등급 간 어댑터. 오류 발견 사항을 계약 `RuleViolation` 객체로 매핑	`list<RuleViolation>`	`validate()`와 동일	정보 수준 발견 사항은 건너뜀
`SchematronResult` / `SchematronFinding`	—	판정, 발견 사항, 소요 시간. `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()`는 엔진 실패를 무효로 표시
`SchematronCacheInterface`	—	변조 탐지 캐시 계약: `getVerified()`, `set()`, `computeKey()`	—	—	다이제스트 불일치 시 실패 폐쇄
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	원자적 이름 변경 쓰기를 사용하는 SHA-256 검증 파일 캐시	—	`InvalidArgumentException`, `SchematronCacheException`	디렉터리는 존재하거나 생성 가능해야 하며 쓰기 가능해야 함
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	SHA-256 잠금 규칙 팩 핀: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	잘못된 잠금 JSON에 대해 `VersionPinException`, `InvalidArgumentException`, `JsonException`	빈 또는 잘못된 다이제스트는 실패 폐쇄
`InvoiceContractValidator`	`?SemanticValidator`	등급 간 `ValidatorInterface` 어댑터. 구조 사전 점검과 EN 16931 심층 시맨틱 규칙	`ContractResult`	실패 폐쇄. 엔진 오류는 오류 발견 사항으로 표면화	`nextpdf/premium` 설치 시 프레임워크 경로에 바인딩
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	등급 간 `EmbedderInterface` 어댑터. 바이트 입력 / 바이트 출력 임베드	`string` (PDF 바이트)	위임 실패를 전파	Pro 등급 바이트 재작성 엔진에 위임
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	모듈 실패 분류 체계	—	—	모두 `RuntimeException`을 확장

public static function basic(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $xmlData,
): ZugferdEmbedResult

public function embed(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
): ZugferdEmbedResult

public static function invoice(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $ublXml,
): PeppolEmbedResult

public static function validate(
    string $xmlData,
    ZugferdProfile $profile,
    ?InvoiceValidatorMode $mode = null,
): InvoiceValidationResult

public function validate(string $xsltPath, string $xmlData): SchematronResult

동작 계약

임베딩. ZugferdEmbedder는 호출자가 제공한 ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII XML 페이로드를 PDF/A 캐리어에 첨부합니다. 두 가지 캐리어를 지원합니다. 선호되는 최신 캐리어인 PDF/A-4f(ISO 19005-4:2020)와 하위 호환성을 위한 PDF/A-3b(ISO 19005-3:2012)입니다. embed()는 항상 먼저 XmlGuard 보안 통과를 실행하고, withoutValidation()이 설정되지 않았다면 구조 검증을 수행하며, 캐리어가 임베디드 파일을 지원하는지 확인하고, ZugferdXmpSchema를 통해 XMP 확장 스키마 선언을 주입한 다음, XML을 연관 파일로 첨부합니다. 첨부 관계는 기본적으로 규칙집 권장 값인 /Alternative입니다. 재정의는 동일한 규칙집을 거치며, 이 규칙집은 ISO 32000-2:2020 §14.13 관계 집합과 EN 16931 송장 서브셋을 강제합니다. PeppolEmbedder는 호출자가 제공한 Peppol BIS Billing 3.0 UBL 2.1 송장 또는 대변표 XML에 대해 동등한 작업을 수행합니다. 두 임베더 모두 송장 XML을 생성하지 않습니다.

검증. InvoiceXmlValidator는 CII XML을 EN 16931 구조 기대 사항에 대해 검사합니다: 루트 요소, 필수 섹션, 헤더 카디널리티, 프로필이 요구하는 경우의 라인 항목, 그리고 비즈니스 규칙 BR-1이 의무화하는 BT-24 사양 식별자입니다. InvoiceValidatorMode가 심각도를 선택합니다. COMPAT(기본값)는 누락되거나 불일치하는 BT-24를 경고로 보고하여 불리언 유효성 게이트가 회귀하지 않도록 합니다. STRICT는 둘 다 하드 오류로 만들고, 선언된 ZugferdProfile에 대한 프로필 일관성도 단언하여 외부 KoSIT / Mustang 검증기 시맨틱을 반영합니다. 모드는 명시적 인자, 다음 INVOICE_VALIDATOR_MODE 환경 재정의, 다음 COMPAT 순으로 해석됩니다. 결과는 구조화된 InvoiceValidationResult / InvoiceValidationFinding 객체입니다. 검증기는 예외를 발생시키지 않고 발견 사항을 반환합니다.

Schematron. SchematronValidator는 사전 컴파일된 Schematron 규칙 집합 — 빌드 시점에 XSLT로 컴파일된 CEN EN 16931 .sch 규칙 — 을 인프로세스 PHP XSLT 프로세서를 사용해 실행합니다. SVRL 보고서를 SchematronFinding / SchematronResult 객체로 파싱합니다: 실패한 어서션은 오류 발견 사항이 되고, 성공한 보고는 정보 발견 사항이 됩니다. 선택적 캐시(SchematronCacheInterface, 원자적 이름 변경 파일 구현 포함)는 콘텐츠 다이제스트와 컴파일러 버전으로 키가 지정된 검증된 스타일시트 바이트를 제공합니다. VersionPinRegistry는 모든 외부 규칙 팩을 SHA-256 잠금 버전으로 고정하고 드리프트 또는 잘못된 다이제스트에서 실패 폐쇄합니다.

이 모듈은 구조화된 송장 데이터를 생성하고 검사합니다. 어떤 문서가 법적으로 적합한 송장이라거나, 세무 당국의 승인을 받았다거나, 어떤 당국에 의해 수용이 보장된다고 단언하지 않습니다. 검증기는 EN 16931 시맨틱 모델과 ZUGFeRD / Factur-X / UBL 컨테이너만 검사합니다. 국가 확장(예: 이탈리아 SDI, 프랑스 Chorus Pro, 독일 XRechnung 전송)은 제외합니다. EN 16931-1이 명시하듯, 관련 법규의 규칙을 충족하는 것은 송장 발행자의 책임입니다. 이는 세무 당국 검증기가 아닙니다. 표준 지원은 그 표준에 대한 적합성이 아닙니다.

엣지 케이스 및 실패 모드

빈 XML은 즉시 실패합니다: 빌더는 InvalidArgumentException을 발생시키고, InvoiceXmlValidator::validate()는 실패 결과를 반환합니다.
XmlGuard는 DOCTYPE 선언, 엔티티 확장, 과대 페이로드, 제어 문자를 거부합니다. 임베더는 이를 원인을 보존한 채 ZugferdEmbeddingException 또는 PeppolEmbeddingException으로 표면화합니다.
withoutValidation()과 withoutSanitization()은 XmlGuard 보안 통과를 결코 우회하지 않습니다. 구조적 비즈니스 용어 검사만 건너뛸 수 있습니다.
임베디드 파일 지원이 없는 캐리어(PDF/A-4f 또는 PDF/A-3b 이외의 모든 것)는 허용 버전을 명시하는 InvalidArgumentException을 발생시킵니다.
허용되지 않는 AFRelationship 값은 빌더 경계에서 거부됩니다. 캐리어 인식 규칙집 재검사가 embed() 내부에서 다시 실행됩니다.
COMPAT는 누락된 BT-24를 경고 심각도로 유지합니다. STRICT는 누락되거나 프로필이 불일치하는 BT-24 값을 하드 오류로 만듭니다.
SchematronValidator는 누락되거나 읽을 수 없는 XSLT 경로에 대해서만 예외를 발생시킵니다. 변환 또는 SVRL 파싱 실패는 isValid가 false인 SchematronResult::error()를 반환합니다.
저장된 바이트가 다이제스트 검증에 실패한 캐시 항목은 축출되고 스타일시트는 디스크에서 다시 읽힙니다. 오염된 바이트는 결코 반환되지 않습니다.
XSLT 프로세서는 파일 및 네트워크 리소스 로딩이 차단된 상태로 실행되며 결코 PHP 함수를 등록하지 않습니다. document(), xsl:include, xsl:import, result-document는 리소스를 로드할 수 없습니다.
VersionPinRegistry는 수집 시점과 재생성 시점에 빈 또는 잘못된 SHA-256 다이제스트를 거부합니다. verifyArtefact()는 검증 불가능한 핀을 통과시키지 않고 false를 반환합니다.
이 모듈은 어떠한 암호화 서명도 수행하지 않습니다. FIPS 모드 동작은 여기서 범위 밖입니다(Signature 모듈 참조).

적합성

동작	참조	상태
핵심 송장 시맨틱 모델	EN 16931-1:2026 §4	부합 대상. 발행자가 책임을 유지함
사양 식별자(BT-24)	EN 16931-1:2026 BR-1	COMPAT에서 경고, STRICT에서 오류
UN/CEFACT CII 구문 바인딩	CEN/TS 16931-3-3:2020	임베드 지원
UBL 2.1 구문 바인딩	CEN/TS 16931-3-2:2020	임베드 지원
PDF/A-3 연관 파일	ISO 19005-3:2012 §6.7.8	캐리어 지원
PDF/A-4f 임베디드 파일	ISO 19005-4:2020 Annex A	캐리어 지원
연관 파일 관계 값	ISO 32000-2:2020 §14.13	규칙집 게이트
Schematron / SVRL 보고서 파싱	ISO/IEC 19757-3	부합 대상(제품 근거. 표준은 인용 코퍼스에 없음)

부합 대상이며, 인증이나 세무 당국 승인이 아닙니다. NextPDF는 이러한 표준 중 어느 것에 대해서도 인증을 보유하지 않습니다. NextPDF는 EN 16931 데이터 모델에 적합한 구조화된 송장을 생성하고 규칙 발견 사항을 보고합니다. 법적으로 적합한 송장을 생성하거나, 세무 당국 승인 출력을 제공하거나, 수용을 보장하지 않습니다. 세무 및 법률 자문에게 문의하십시오.

개발 참고 사항

Schematron 엔진은 ext-xsl PHP 확장을 필요로 합니다. 이를 프로비저닝하고 활성화하는 것은 운영자의 책임입니다.
처리는 인프로세스이며 로컬입니다. 임베딩 또는 검증 중에 아웃바운드 네트워크 호출이 발생하지 않습니다. 국가 전자송장 전송, 클리어런스 플랫폼, 보관 시스템은 이 모듈의 외부입니다.
규칙 팩은 빌드 시점에 .sch에서 XSLT로 컴파일됩니다. 런타임은 사전 컴파일된 스타일시트만 실행합니다.
캐시 키는 컴파일러 버전 솔트(현재 nextpdf-schxslt-1.0)를 포함합니다. 이를 올리면 퍼지 단계 없이 배포된 캐시를 무효화합니다.
규칙 팩 핀은 enterprise/config/invoice-versions.lock(VersionPinRegistry::DEFAULT_LOCK_PATH)의 잠금 파일에 있습니다. CI는 배포된 아티팩트를 고정된 다이제스트와 대조하여 검증합니다.
등급 간 호출자는 InvoiceContractValidator와 ZugferdContractEmbedder를 사용합니다. 등급 네이티브 Enterprise 호출자는 ZugferdEmbedder와 InvoiceXmlValidator를 직접 사용합니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위 밖입니다.

함께 보기

Invoice 기능 — 이 참조의 기능 대응 문서.
Pro Compliance — Pro 등급 탐지/검증.
Document E-Filing
Enterprise overview