Invoice — Referência Profunda

Visão geral

O módulo Invoice tem três superfícies independentes: incorporação, validação e execução de regras Schematron. ZugferdEmbedder e PeppolEmbedder anexam o XML de fatura fornecido pelo chamador a um carregador PDF/A-4f ou PDF/A-3b e retornam um resultado estruturado. InvoiceXmlValidator executa uma pré-verificação estrutural EN 16931 com severidade selecionável COMPAT ou STRICT. SchematronValidator executa pacotes de regras Schematron pré-compilados em processo e analisa achados SVRL. O NextPDF não gera o XML da fatura; o chamador fornece e é responsável pelo payload.

Disponibilidade e licenciamento

Esta capacidade é fornecida no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes da capacidade. Compare edições e obtenha uma licença.

Nuance por nível: a detecção e validação de fatura eletrônica é a superfície de nível Pro (módulo Pro Compliance). A incorporação de fatura híbrida, o perfil XRechnung CIUS e o mecanismo Schematron em processo são exclusivos do Enterprise. Não há código de capacidade separado por recurso além do limite do pacote nextpdf/enterprise.

Superfície da API pública

composer require nextpdf/enterprise:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
ZugferdEmbedder::basic()	PdfAManager, FileAttachment, string $xmlData	Incorpora XML CII de perfil BASIC: verificação XmlGuard, validação estrutural, injeção de esquema XMP, anexação	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Caminho rápido; ponto de partida recomendado
ZugferdEmbedder::minimum()	PdfAManager, FileAttachment, string $xmlData	Mesmo pipeline no perfil MINIMUM	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Caminho rápido
ZugferdEmbedder::create()	ZugferdProfile, string $xmlData	Entrada do builder; rejeita XML vazio	self	InvalidArgumentException	Configure via withoutValidation(), withDescription()
ZugferdEmbedder::withAfRelationship() / PeppolEmbedder::withAfRelationship()	AFRelationship|string	Substitui o relacionamento padrão /Alternative; controlado pelo regramento de arquivos associados	self	InvalidArgumentException	Schema, EncryptedPayload, FormData rejeitados para faturas
ZugferdEmbedder::embed()	PdfAManager, FileAttachment	Chamada terminal do builder: XmlGuard, validação opcional, verificação do carregador, XMP, anexação	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	A falha de validação nomeia o primeiro erro
ZugferdProfile (enum)	—	Casos MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG anexa xrechnung.xml; perfis CII anexam factur-x.xml
ZugferdXmpSchema::apply()	XmpMetadata, ZugferdProfile	Registra a descrição RDF do Factur-X e a entrada de esquema de extensão PDF/A	XmpMetadata	Nenhum	Chamado por embed(); também utilizável diretamente
PeppolEmbedder::invoice() / ::creditNote()	PdfAManager, FileAttachment, string $ublXml	Incorpora XML de fatura ou nota de crédito UBL Peppol BIS 3.0	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	Nomes de arquivo padrão invoice.xml / creditnote.xml
PeppolEmbedder::create()	string $ublXml, string $filename = 'invoice.xml'	Entrada do builder; rejeita XML ou nome de arquivo vazio	self	InvalidArgumentException	Configure via withFilename(), withDescription(), withoutSanitization()
PeppolEmbedder::embed()	PdfAManager, FileAttachment	Verificação XmlGuard, verificação do carregador, controle do regramento, anexação	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	Nova verificação do regramento ciente do carregador no momento da incorporação
InvoiceXmlValidator::validate()	string $xmlData, ZugferdProfile, ?InvoiceValidatorMode	Pré-verificação estrutural EN 16931; severidade COMPAT por padrão	InvoiceValidationResult	Não lança; as falhas aparecem como achados de erro	O modo resolve o argumento, depois o ambiente, depois COMPAT
InvoiceXmlValidator::isCrossIndustryInvoice()	string $xmlData	Verificação de elemento raiz e namespace para payloads CII	bool	Não lança; retorna false	Sonda de detecção econômica
InvoiceValidatorMode (enum)	—	COMPAT (padrão) mantém achados de BT-24 em aviso; STRICT os promove a erro	—	—	fromEnvironment() recai para COMPAT em valores não definidos ou não reconhecidos
InvoiceValidationResult / InvoiceValidationFinding	—	Agregados imutáveis: isValid, getErrors(), getWarnings(); nível, código e mensagem por achado	—	—	InvoiceValidationResult::fail() encapsula um único erro
SchematronValidator::validate()	string $xsltPath, string $xmlData	Executa um XSLT Schematron pré-compilado; analisa o SVRL em achados	SchematronResult	InvalidArgumentException para um XSLT ausente ou ilegível; falhas do mecanismo retornam um resultado de erro	Tempo capturado em durationMs
SchematronValidator::runRules()	string $xslPath, string $xmlPayload	Adaptador entre níveis; mapeia achados de erro para objetos RuleViolation do contrato	list<RuleViolation>	Igual a validate()	Achados de nível info são ignorados
SchematronResult / SchematronFinding	—	Veredito, achados, duração; getFailedAssertions(), getSuccessfulReports()	—	—	SchematronResult::error() marca falhas do mecanismo como inválidas
SchematronCacheInterface	—	Contrato de cache com detecção de adulteração: getVerified(), set(), computeKey()	—	—	Falha fechado em incompatibilidade de digest
AtomicRenameSchematronCache	string $cacheDir, bool $atomicRename = true, LoggerInterface	Cache de arquivo verificado por SHA-256 com escritas por renomeação atômica	—	InvalidArgumentException, SchematronCacheException	O diretório deve existir ou poder ser criado, e ser gravável
VersionPinRegistry	array $pins, ?string $sourcePath	Fixações de conjunto de regras travadas por SHA-256: loadFromLockFile(), get(), verifyArtefact(), regenerateLockFile()	—	VersionPinException, InvalidArgumentException, JsonException em JSON de lock malformado	Digests em branco ou malformados falham fechado
InvoiceContractValidator	?SemanticValidator	Adaptador ValidatorInterface entre níveis; pré-verificação estrutural mais regras semânticas profundas do EN 16931	ContractResult	Falha fechado; erros do mecanismo aparecem como achados de erro	Vinculado nos caminhos de framework quando nextpdf/premium está instalado
ZugferdContractEmbedder	FacturXContractEmbedder	Adaptador EmbedderInterface entre níveis; incorporação byte-in / byte-out	string (bytes de PDF)	Propaga falhas do delegado	Delega ao mecanismo de reescrita de bytes do nível Pro
ZugferdEmbeddingException, PeppolEmbeddingException, SchematronCacheException, VersionPinException	—	Taxonomia de falhas do módulo	—	—	Todas estendem 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

Contrato de comportamento

Incorporação. ZugferdEmbedder anexa um payload XML UN/CEFACT CII ZUGFeRD 2.4 / Factur-X 1.08 fornecido pelo chamador a um carregador PDF/A. Ele suporta dois carregadores: PDF/A-4f (ISO 19005-4:2020), o carregador moderno preferido, e PDF/A-3b (ISO 19005-3:2012) para compatibilidade retroativa. embed() sempre executa primeiro uma verificação de segurança XmlGuard, depois a validação estrutural, a menos que withoutValidation() tenha sido definido, depois verifica se o carregador suporta arquivos incorporados, injeta a declaração de esquema de extensão XMP por meio de ZugferdXmpSchema e anexa o XML como um arquivo associado. O relacionamento de anexo tem como padrão a recomendação /Alternative do regramento; as substituições passam pelo mesmo regramento, que impõe o conjunto de relacionamentos da ISO 32000-2:2020 §14.13 e o subconjunto de fatura do EN 16931. PeppolEmbedder realiza o equivalente para XML de fatura ou nota de crédito UBL 2.1 Peppol BIS Billing 3.0 fornecido pelo chamador. Nenhum dos incorporadores gera o XML da fatura.

Validação. InvoiceXmlValidator verifica o XML CII em relação às expectativas estruturais do EN 16931: elemento raiz, seções obrigatórias, cardinalidade do cabeçalho, itens de linha onde o perfil os exige e o identificador de especificação BT-24 exigido pela regra de negócio BR-1. InvoiceValidatorMode seleciona a severidade. COMPAT (padrão) informa um BT-24 ausente ou incompatível como um aviso, de modo que um portão booleano de validade não regrida. STRICT torna ambos um erro grave e também afirma a consistência do perfil em relação ao ZugferdProfile declarado, espelhando a semântica dos validadores externos KoSIT / Mustang. O modo resolve na ordem: argumento explícito, depois a substituição de ambiente INVOICE_VALIDATOR_MODE, depois COMPAT. Os resultados são objetos estruturados InvoiceValidationResult / InvoiceValidationFinding; o validador retorna achados em vez de lançar.

Schematron. SchematronValidator executa conjuntos de regras Schematron pré-compilados — as regras .sch CEN EN 16931 compiladas para XSLT em tempo de build — usando o processador XSLT do PHP em processo. Ele analisa o relatório SVRL em objetos SchematronFinding / SchematronResult: asserções com falha tornam-se achados de erro, relatórios bem-sucedidos tornam-se achados de info. Um cache opcional (SchematronCacheInterface, com a implementação de arquivo por renomeação atômica) serve bytes de folha de estilo verificados, indexados por digest de conteúdo mais versão do compilador. VersionPinRegistry fixa cada pacote de regras externo a uma versão travada por SHA-256 e falha fechado em desvio ou digests malformados.

Este módulo produz e verifica dados estruturados de fatura. Ele não afirma que qualquer documento seja uma fatura legalmente conforme, que esteja aprovado pela autoridade tributária ou que sua aceitação por qualquer autoridade seja garantida. O validador verifica apenas o modelo semântico EN 16931 e o contêiner ZUGFeRD / Factur-X / UBL; ele exclui extensões nacionais (por exemplo, o SDI italiano, o Chorus Pro francês, o transporte XRechnung alemão). Como afirma a EN 16931-1, o emissor da fatura é responsável por cumprir as regras da legislação aplicável; este não é um validador de autoridade tributária. Dar suporte a um padrão não é estar em conformidade com ele.

Casos extremos e modos de falha

• XML vazio falha rapidamente: os builders lançam InvalidArgumentException; InvoiceXmlValidator::validate() retorna um resultado com falha.
• XmlGuard rejeita declarações DOCTYPE, expansão de entidades, payloads superdimensionados e caracteres de controle. Os incorporadores expõem isso como ZugferdEmbeddingException ou PeppolEmbeddingException com a causa preservada.
• withoutValidation() e withoutSanitization() nunca ignoram a verificação de segurança XmlGuard. Apenas as verificações estruturais de termos de negócio podem ser puladas.
• Um carregador sem suporte a arquivos incorporados (qualquer coisa além de PDF/A-4f ou PDF/A-3b) lança InvalidArgumentException nomeando as versões aceitas.
• Um valor AFRelationship não permitido é rejeitado no limite do builder; uma nova verificação do regramento ciente do carregador é executada novamente dentro de embed().
• COMPAT mantém um BT-24 ausente em severidade de aviso; STRICT torna valores BT-24 ausentes e com perfil incompatível erros graves.
• SchematronValidator lança apenas para um caminho XSLT ausente ou ilegível. Falhas de transformação ou de análise de SVRL retornam SchematronResult::error() com isValid false.
• Uma entrada de cache cujos bytes armazenados falham na verificação de digest é removida e a folha de estilo é relida do disco; bytes envenenados nunca são retornados.
• O processador XSLT é executado com o carregamento de recursos de arquivo e de rede bloqueado e nunca registra funções PHP; document(), xsl:include, xsl:import e result-document não podem carregar recursos.
• VersionPinRegistry rejeita digests SHA-256 em branco ou malformados na ingestão e na regeneração; verifyArtefact() retorna false em vez de aprovar uma fixação não verificável.
• Este módulo não realiza nenhuma assinatura criptográfica; o comportamento em modo FIPS está fora do escopo aqui (consulte o módulo Signature).

Conformidade

Comportamento	Referência	Status
Modelo semântico central da fatura	EN 16931-1:2026 §4	Construído em relação a; o emissor permanece responsável
Identificador de especificação (BT-24)	EN 16931-1:2026 BR-1	Aviso em COMPAT, erro em STRICT
Vinculação de sintaxe UN/CEFACT CII	CEN/TS 16931-3-3:2020	Incorporação suportada
Vinculação de sintaxe UBL 2.1	CEN/TS 16931-3-2:2020	Incorporação suportada
Arquivo associado PDF/A-3	ISO 19005-3:2012 §6.7.8	Carregador suportado
Arquivo incorporado PDF/A-4f	ISO 19005-4:2020 Annex A	Carregador suportado
Valores de relacionamento de arquivo associado	ISO 32000-2:2020 §14.13	Controlado por regramento
Análise de relatório Schematron / SVRL	ISO/IEC 19757-3	Construído em relação a (fundamentado no produto; padrão não está no corpus de citações)

Construído em relação a, não certificação nem aprovação de autoridade tributária. O NextPDF não possui certificação para nenhum desses padrões. O NextPDF produz faturas estruturadas em conformidade com o modelo de dados EN 16931 e informa achados de regras; ele não produz faturas legalmente conformes, não fornece saída aprovada por autoridade tributária e não garante aceitação. Consulte seus assessores tributários e jurídicos.

Notas de desenvolvimento

• O mecanismo Schematron requer a extensão PHP ext-xsl; provisioná-la e habilitá-la é responsabilidade do operador.
• O processamento é em processo e local. Nenhuma chamada de rede de saída ocorre durante a incorporação ou a validação. O transporte nacional de fatura eletrônica, as plataformas de clearance e os sistemas de arquivamento são externos a este módulo.
• Os pacotes de regras são compilados de .sch para XSLT em tempo de build; o runtime executa apenas folhas de estilo pré-compiladas.
• As chaves de cache incorporam o salt da versão do compilador (atualmente nextpdf-schxslt-1.0); incrementá-lo invalida os caches implantados sem uma etapa de expurgo.
• As fixações de pacotes de regras ficam no arquivo de lock em enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); a CI verifica os artefatos implantados em relação aos digests fixados.
• Os chamadores entre níveis usam InvoiceContractValidator e ZugferdContractEmbedder; os chamadores nativos do nível Enterprise usam ZugferdEmbedder e InvoiceXmlValidator diretamente.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.

Veja também

• Capacidade Invoice — contraparte de capacidade desta referência.
• Pro Compliance — detecção/validação no nível Pro.
• Document E-Filing
• Visão geral do Enterprise