ZUGFeRD / Factur-X 적합성: 내장 EN 16931 인보이스 프로파일

한눈에 보기

범위 선언. NextPDF는 내장 XML 프로파일을 생성합니다. 세무상 및 법적 유효성은 라이브러리가 아닌 수신 기관이 결정합니다.

ZUGFeRD / Factur-X는 하이브리드 인보이스입니다. 사람이 읽을 수 있는 PDF(PDF/A-3 보존 기반)에 EN 16931 시맨틱 데이터 모델을 따르는 기계 판독 가능한 Cross-Industry-Invoice(CII) XML이 내장됩니다. NextPDF Core는 임베더 계약(NextPDF\Contracts\EInvoice)을 제공하며, 구체적인 Factur-X 1.08 엔진은 Premium nextpdf/pro 패키지에서 제공됩니다. 라이브러리는 내장 XML과 PDF/A-3 첨부 구조를 생성하고, EN 16931 / Schematron 검증기 또는 수신 세무 당국이 세무상 유효성을 결정합니다.

설치

composer require nextpdf/core:^3   # EInvoice contracts only
composer require nextpdf/pro       # Factur-X 1.08 embedder engine

Core는 EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface, ValidationResult를 NextPDF\Contracts\EInvoice에서 제공합니다. 인터페이스 docblock은 이를 명시적으로 설명합니다. Pro 계층(Factur-X 1.08 바이트 재작성 엔진)과 Enterprise 계층(PDF/A 관리 빌더)이 이 계약을 구현합니다. Core 단독으로는 인보이스를 내장하지 않습니다. Core는 각 계층이 충족하는 byte-in/byte-out 계약을 정의합니다.

개념 개요

NextPDF\Contracts\EInvoice\ProfileType은 EN 16931 적합성 판별자이며, 값은 MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG입니다. isEn16931Conformant()은 이 규칙을 EN 16931-1에서 직접 인코딩합니다. MINIMUM과 BASIC_WL은 EN 16931에 적합하지 않습니다(BT-24 사양 식별자 카디널리티와 품목 요구 사항을 충족하지 못합니다). BASIC, EN16931, EXTENDED, XRECHNUNG은 EN 16931에 적합합니다.

임베더(EmbedderInterface)는 다음을 수행하도록 계약되어 있습니다:

제공된 CII XML을 XmlGuard를 통해 파싱합니다(XXE-safe).
선언된 프로파일에 맞는 Factur-X XMP 확장 스키마를 주입합니다.
올바른 AFRelationship(Data / Alternative)으로 XML을 내장 파일로 첨부하여, PDF/A-3 보존 기반(§6.7.5 내장 파일 요구 사항 — F/UF 키)이 이를 담도록 합니다.

NextPDF는 이 구조를 생성하지만, 그 자체로 인보이스가 세무상 유효하다고 주장하지는 않습니다. 그 판단은 EN 16931 §7 비즈니스 규칙과 모든 국가별 CIUS에 비추어 수신 기관이 내립니다.

API 표면

심볼	효과
`Contracts\EInvoice\EmbedderInterface`	Byte-in/byte-out 계약이며, Pro/Enterprise가 구현합니다.
`Contracts\EInvoice\ProfileType` (enum)	EN 16931 프로파일 판별자입니다.
`ProfileType::isEn16931Conformant(): bool`	MINIMUM/BASIC_WL에 대해서는 False, BASIC/EN16931/EXTENDED/XRECHNUNG에 대해서는 true입니다.
`Contracts\EInvoice\ValidatorInterface`	규칙 위반 사항을 담은 `ValidationResult`를 반환하는 검증 계약입니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ProfileType;

// Core: choose and check the profile before delegating embedding to Pro.
$profile = ProfileType::EN16931;

if (!$profile->isEn16931Conformant()) {
    fwrite(STDERR, "Profile {$profile->value} is not EN 16931 conformant.\n");
    exit(1);
}

// The concrete embedder is provided by nextpdf/pro:
//   $embedder = /* the Factur-X embedder from nextpdf/pro; see the Premium docs */;
//   $pdfWithInvoice = $embedder->embed($basePdfBytes, $ciiXml, $options);
echo "Profile {$profile->value} selected (embedding requires nextpdf/pro).\n";

코드 샘플 — 프로덕션

프로덕션 파이프라인(Pro 계층)은 CII XML을 PDF/A-3 베이스에 내장합니다. 그런 다음 EN 16931 Schematron 검증기를 실행합니다(또는 수신 기관에 제출합니다). 이 보고서를 게이트로 사용합니다. NextPDF는 내장 XML과 PDF/A-3 첨부를 생성하며, validator/authority가 세무상 유효성을 결정합니다. Core 단독으로는 이 파이프라인을 실행할 수 없습니다. 임베더 엔진에는 nextpdf/pro가 필요합니다.

엣지 케이스 & 주의 사항

Core에는 계약만 있습니다. nextpdf/pro 없이는 구체적인 임베더가 존재하지 않습니다. 호출 코드는 인터페이스에 의존해야 하며, Pro 구현이 없을 때 명확하게 기능을 축소해야 합니다.
MINIMUM / BASIC_WL은 EN 16931이 아닙니다. isEn16931Conformant()은 이들에 대해 false를 반환합니다. 이를 사용할 때는 EN 16931 인보이스라고 표방하지 마십시오.
PDF/A-3 기반. 내장 XML은 PDF/A-3 보존 컨테이너에 실립니다. 내장 파일의 F/UF 키(PDF/A §6.7.5)가 반드시 있어야 합니다.
XML은 XXE-safe하게 파싱됩니다. 이 계약은 XmlGuard 파싱을 요구합니다. 사용자 정의 임베더는 XXE 싱크를 도입해서는 안 됩니다.
유효성은 라이브러리의 판정이 아닙니다. 구조적으로 올바른 Factur-X 파일을 생성하는 것이 세무 당국이 이를 수락한다는 진술은 아닙니다.

성능

내장 과정은 XML 첨부와 XMP 확장 스키마를 추가하기 위해 PDF를 재작성합니다. 일반적인 인보이스의 경우 벽시계 시간 ≤ 1500 ms, 최대 메모리 ≤ 128 MB로 예산을 둡니다.

보안 참고 사항

내장 XML은 XmlGuard를 통해 XXE-safe하게 파싱됩니다. 인보이스 XML에는 본질적으로 상업적 PII(당사자, 금액)가 포함됩니다. 이 데이터는 암호화되는 것이 아니라 내장됩니다. 인보이스의 기밀성은 통합 담당자의 책임입니다.

데이터 레지던시 & PII 완화

인보이스 XML은 당사자 및 금융 PII를 담고 있습니다. 내장은 프로세스 내에서 수행됩니다. 내장 중에는 어떤 데이터도 프로세스를 벗어나지 않습니다. 수신 기관으로의 전송은 범위를 벗어나며, 통합 담당자가 데이터 레지던시를 책임집니다.

안전한 텔레메트리 & 로그 스크러빙

CII XML이나 내장 PDF 바이트는 절대 로그에 기록하지 마십시오. 둘 다 인보이스 PII를 포함합니다. 프로파일 이름과 구조적 판정만 로그에 기록하십시오.

위협 모델

Factur-X 파일에는 접근 제어가 적용되지 않습니다. 내장 XML은 해당 파일을 가진 누구나 읽을 수 있습니다. 하이브리드 형식은 인보이스의 기계 판독성을 보장하지만, 기밀성이나 세무상 수락은 보장하지 않습니다.

FIPS 모드 동작

내장은 어떠한 암호화도 수행하지 않습니다. 서명된 Factur-X 인보이스는 별도 서명 레시피의 영역이며, 해당 레시피의 FIPS 태세를 상속합니다. 이 페이지는 서명에 관한 어떠한 주장도 하지 않습니다.

적합성

주장	사양	조항
EN 16931 인보이스는 시맨틱 데이터 모델 비즈니스 용어를 포함합니다.	EN 16931-1	§6.4
EN 16931 준수는 적합한 인보이스가 충족해야 하는 비즈니스 규칙 카디널리티에 의해 규율됩니다.	EN 16931-1	§7
Factur-X EN 16931 프로파일은 CII-XML 비즈니스 규칙 적합성을 요구합니다.	Factur-X 1.08	EN 16931 프로파일
Factur-X EN 16931 프로파일은 필수 인보이스 내용을 의무화합니다.	Factur-X 1.08	EN 16931 프로파일
Factur-X는 하이브리드입니다: 기계 판독 가능한 XML이 사람이 읽을 수 있는 PDF와 함께 내장됩니다.	Factur-X 1.08	Basic 프로파일
내장 XML은 PDF/A 보존 기반(내장 파일 F/UF 키)에 실립니다.	ISO 19005-4	§6.7.5

인용은 검증 코퍼스를 가리키는 clause-id + reference_id 포인터입니다. 표준 본문은 재현하지 않으며, 조항은 NextPDF의 표현으로 요약됩니다.