Conformidade com ZUGFeRD / Factur-X: profile de fatura EN 16931 embutido

Visão geral

Declaração de limites. O NextPDF produz o profile XML embutido; a validade fiscal e jurídica é determinada pela autoridade receptora, não pela biblioteca.

ZUGFeRD / Factur-X é uma fatura híbrida: um PDF legível por humanos (um substrato de arquivamento PDF/A-3) com um XML Cross-Industry-Invoice (CII) embutido e legível por máquina, que segue o modelo de dados semântico EN 16931. O NextPDF Core fornece o contrato do embedder (NextPDF\Contracts\EInvoice); o motor concreto Factur-X 1.08 vem no pacote Premium nextpdf/pro. A biblioteca produz o XML embutido e a estrutura de anexo PDF/A-3. Um validador EN 16931 / Schematron ou a autoridade fiscal receptora decide a validade fiscal.

Instalação

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

O Core fornece EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface e ValidationResult em NextPDF\Contracts\EInvoice. O docblock da interface é explícito: o tier Pro (motor de reescrita de bytes Factur-X 1.08) e o tier Enterprise (builder gerenciado de PDF/A) implementam esse contrato. O Core sozinho não embute uma fatura. Ele define o contrato byte-in/byte-out seguido por esses tiers.

Visão conceitual

NextPDF\Contracts\EInvoice\ProfileType é o discriminador de conformidade EN 16931: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Seu isEn16931Conformant() codifica diretamente a regra da EN 16931-1. MINIMUM e BASIC_WL não estão em conformidade com a EN 16931 (eles falham na cardinalidade do identificador de especificação BT-24 e no requisito de item de linha). BASIC, EN16931, EXTENDED, XRECHNUNG estão em conformidade com a EN 16931.

O embedder (EmbedderInterface) tem por contrato:

analisar o XML CII fornecido por meio do XmlGuard (seguro contra XXE);
injetar o schema de extensão XMP do Factur-X para o profile declarado;
anexar o XML como um arquivo embutido com o AFRelationship correto (Data / Alternative), de modo que o substrato de arquivamento PDF/A-3 (§6.7.5 requisitos de arquivo embutido — chaves F/UF) o carregue.

O NextPDF emite essa estrutura. Ele não afirma que a fatura é fiscalmente válida. A autoridade receptora faz essa determinação com base nas regras de negócio da EN 16931 §7 e em qualquer CIUS nacional aplicável.

Superfície da API

Símbolo	Efeito
`Contracts\EInvoice\EmbedderInterface`	Contrato byte-in/byte-out; Pro/Enterprise o implementam.
`Contracts\EInvoice\ProfileType` (enum)	Discriminador de profile EN 16931.
`ProfileType::isEn16931Conformant(): bool`	False para MINIMUM/BASIC_WL; true para BASIC/EN16931/EXTENDED/XRECHNUNG.
`Contracts\EInvoice\ValidatorInterface`	Contrato de validação que retorna um `ValidationResult` com violações de regra.

Exemplo de código — Início rápido

<?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";

Exemplo de código — Produção

O pipeline de produção (tier Pro) embute o XML CII em uma base PDF/A-3. Em seguida, ele executa um validador EN 16931 Schematron, ou envia o arquivo à autoridade receptora, e trata esse relatório como o gate. O NextPDF emite o XML embutido e o anexo PDF/A-3; o validador ou a autoridade decide a validade fiscal. O Core sozinho não consegue executar esse pipeline. O nextpdf/pro é necessário para o motor do embedder.

Casos extremos e pegadinhas

O Core tem apenas contratos. Sem o nextpdf/pro, não há embedder concreto. O código chamador deve depender da interface e degradar de forma clara quando a implementação Pro estiver ausente.
MINIMUM / BASIC_WL não são EN 16931. isEn16931Conformant() retorna false para esses; não anuncie a fatura como EN 16931 ao usá-los.
Substrato PDF/A-3. O XML embutido é transportado em um contêiner de arquivamento PDF/A-3; as chaves de arquivo embutido F/UF (PDF/A §6.7.5) devem estar presentes.
O XML é analisado de forma segura contra XXE. O contrato exige a análise via XmlGuard; um embedder personalizado não deve introduzir um sink de XXE.
A validade não é o veredito da biblioteca. Produzir um arquivo Factur-X estruturalmente correto não significa que a autoridade fiscal o aceitará.

Desempenho

A inserção reescreve o PDF para adicionar o anexo XML e o schema de extensão XMP. Orçamento: tempo de parede ≤ 1500 ms e pico ≤ 128 MB para uma fatura típica.

Notas de segurança

O XML embutido é analisado de forma segura contra XXE via XmlGuard. O XML da fatura contém informações comerciais de identificação pessoal (PII), incluindo as partes e os valores. Ele é embutido, não criptografado. A confidencialidade da fatura é responsabilidade do integrador.

Residência de dados e mitigações de PII

O XML da fatura carrega PII das partes e informações financeiras. A inserção ocorre no processo; nenhum dado deixa o processo durante a inserção. A transmissão a uma autoridade receptora está fora do escopo e é responsabilidade do integrador quanto à residência de dados.

Telemetria segura e limpeza de logs

Nunca registre em log o XML CII nem os bytes do PDF embutido — eles contêm PII da fatura. Registre em log apenas o nome do profile e um veredito estrutural.

Modelo de ameaças

Um arquivo Factur-X não inclui controle de acesso. O XML embutido pode ser lido por qualquer pessoa que tenha o arquivo. O híbrido garante a legibilidade por máquina da fatura, não a sua confidencialidade nem a sua aceitação fiscal.

Comportamento em modo FIPS

A inserção não realiza criptografia. Uma fatura Factur-X assinada é uma preocupação separada da receita de assinatura e herda a postura FIPS dessa receita. Esta página não faz nenhuma afirmação sobre assinatura.

Conformidade

Afirmação	Especificação	Cláusula
Uma fatura EN 16931 carrega os termos de negócio do modelo de dados semântico.	EN 16931-1	§6.4
A conformidade com EN 16931 é regida pela cardinalidade das regras de negócio que uma fatura conformante deve satisfazer.	EN 16931-1	§7
O profile Factur-X EN 16931 exige conformidade com as regras de negócio do CII-XML.	Factur-X 1.08	profile EN 16931
O profile Factur-X EN 16931 exige o conteúdo obrigatório da fatura.	Factur-X 1.08	profile EN 16931
Factur-X é um híbrido: XML legível por máquina embutido junto com o PDF legível por humanos.	Factur-X 1.08	Basic
O XML embutido viaja em um substrato de arquivamento PDF/A (chaves de arquivo embutido F/UF).	ISO 19005-4	§6.7.5

As citações são ponteiros de clause-id + reference_id para o corpus de verificação. Nenhum texto normativo é reproduzido; as cláusulas são resumidas nas palavras do NextPDF.