Pro edição

Compliance — Referência Profunda

Visão geral

O módulo Compliance reúne três superfícies independentes sob NextPDF\Pro\Compliance:

Relatório de language-tag — uma fachada de política estrita de /Lang PDF/UA-2 mais um reporter de eventos de conformidade estruturado, no formato PSR-3.
Tratamento de fatura eletrônica — validação Factur-X 1.08 / ZUGFeRD 2.4 contra o modelo semântico EN 16931, e emissão híbrida de PDF/A-3.
Proveniência — incorpore e extraia manifest stores C2PA fornecidos pelo chamador através de um parser JUMBF endurecido contra adversários; a síntese de claims permanece restrita a preview.

O módulo relata o que verifica. Ele não certifica documentos e não realiza assinatura criptográfica.

Disponibilidade e licenciamento

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

Não existe nenhum sinalizador de licença por recurso. Esta é uma capacidade da edição Pro. O construtor experimental de claims C2PA exige adicionalmente um opt-in explícito de ambiente (consulte Casos extremos e modos de falha).

Superfície pública da API

composer require nextpdf/pro:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`LangComplianceReporter::warn()` / `::error()`	`string $tag, string $reason, ?string $clauseReference = null`	Emite um registro JSON estruturado por evento de language-tag através do logger PSR-3	`void`	`JsonException` se o registro falhar na codificação JSON	`warn` = rejeição em modo lax; `error` = rejeição em modo strict
`LangComplianceReporter::reportException()`	`InvalidBcp47TagException $exception, string $severity = 'error'`	Extrai a tag e o motivo da exceção; delega para `warn()` ou `error()`	`void`	Como acima	Caminho de conveniência
`LangComplianceReporter::buildRecord()`	`string $severity, string $tag, string $reason, ?string $clauseReference = null`	Constrói o array de registro sem registrar em log	`array`	Não lança	Para sinks personalizados, como resumos JSON por arquivo
`ConformancePolicy::default()`	`?LoggerInterface $logger = null`	Política strict UA-2: tags `/Lang` malformadas ou não registradas são rejeitadas	`self`	Não lança	O padrão da v5.0 é strict
`ConformancePolicy::fromCore()`	`CoreConformancePolicy $core, ?LoggerInterface $logger = null`	Envolve uma política Core existente como está; nenhum eixo alterado	`self`	Não lança	Prefira `default()` para a postura strict
`ConformancePolicy::withStrictUa2()`	`bool $enabled`	Retorna uma cópia com o eixo strict definido; desabilitar emite um `notice` PSR-3	`self`	Não lança	Opt-out deprecated; alvo de remoção `6.0.0`
`ConformancePolicy::isStrictUa2()` / `::mode()`	—	Lê a política Core subjacente	`bool` / `ConformanceMode`	Não lança	—
`EInvoiceValidator::validate()`	`string $pdfPath`	Pipeline completo: verificação do wrapper PDF/A-3, extração de anexo, detecção de perfil, regras EN 16931, Schematron	`EInvoiceValidationResult`	Subclasse de `EInvoiceException` em falha de I/O, estrutura de PDF malformada ou crash de ferramenta	Interface SPI congelada; um PDF bem formado que não é fatura eletrônica retorna um resultado, nunca lança
`EInvoiceXmlValidator::validate()`	`string $xmlPayload, ValidatorContext $context`	Pré-verificação estrutural mais o corpus de regras semânticas profundas da EN 16931 sobre um payload CII	contrato `ValidationResult`	Não lança para entrada inválida; a rejeição aparece como um resultado falho com achados	Validador concreto entre camadas; entrada filtrada através de `XmlGuard`
`EInvoiceValidationResult::isValid()`	—	Verdadeiro apenas quando wrapper, especificação de anexo, perfil e sintaxe se sustentam e não existe violação FATAL	`bool`	Não lança	Uma lista de violações vazia, por si só, não é validade
`EInvoiceValidationResult::notAnEInvoice()`	—	Resultado determinístico com tudo null e tudo false	`self`	Não lança	Fábrica para o caso “não é uma fatura híbrida”
`EInvoiceProfile`	enum baseado em string	Casos `MINIMUM`, `BASIC_WL`, `BASIC`, `EN16931`, `EXTENDED`, respaldados por URNs BT-24	—	—	`isEn16931Conformant()` é false para `MINIMUM` e `BASIC_WL`
`EInvoiceSyntax`	enum baseado em string	Casos `UN_CEFACT_CII`, `UBL_INVOICE`, `UBL_CREDIT_NOTE`	—	—	Apenas CII é `isFacturXEligible()`; UBL é somente-validador
`BusinessRuleViolation`	`string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null`	DTO de violação imutável	—	—	Famílias de rule-id `BR-`, `BR-CO-`, `BR-CL-`, `BR-DEC-`, `BR-FXEXT-`
`BusinessRuleSeverity`	enum baseado em string	`FATAL` invalida a fatura; `WARNING` sinaliza uma preocupação de qualidade	—	—	Espelha os níveis de Schematron da EN 16931
`FacturXEmbedder::embed()`	veja o bloco de assinatura	Anexa stream de arquivo incorporado, filespec e XMP a uma fonte PDF/A; reescreve o xref	`void`	`EInvoiceException` em XML malformado, fonte ilegível, catálogo ausente, fonte com object-stream ou xref-stream, ou falha de escrita da saída	O arquivo de origem é mantido intacto
`FacturXEmbedderOptions::default()`	—	`/AFRelationship /Alternative`, nome de arquivo `factur-x.xml`, tipo `INVOICE`, versão `1.0`	`self`	Não lança	Os padrões satisfazem o mandato alemão e permanecem aceitos na França
`FacturXEmbedderOptions::withRelationship()` / `::withFilename()`	`string`	Retorna uma cópia com a substituição aplicada	`self`	`InvalidArgumentException` fora dos conjuntos de aceitação	Relacionamentos: `Source`, `Data`, `Alternative`; nomes de arquivo incluem `zugferd-invoice.xml` e `xrechnung.xml`
`FacturXEmbedderOptions::withDocumentType()`	`string $documentType`	Retorna uma cópia com a substituição do tipo de documento XMP	`self`	Não lança	Os valores não são enumerados defensivamente
`FacturXContractEmbedder::embed()`	`string $pdfBytes, string $xmlPayload, EmbedderOptions $options`	Adaptador byte-a-byte sobre `FacturXEmbedder` via arquivos temporários de vida curta	`string`	`EInvoiceException`; o perfil `XRECHNUNG` é rejeitado como exclusivo do Enterprise	Implementação de `EmbedderInterface` entre camadas
`C2paManifestEmbedder::embed()`	`string $pdfBytes, ManifestStore $store`	Incorpora a serialização em bytes do store no local do perfil	`string`	`C2paException` em qualquer falha de incorporação	Interface SPI congelada; somente bytes, sem I/O
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	Analisa um store incorporado através do parser JUMBF endurecido	`ManifestStore\|null`	Subclasse de `C2paException` quando um store está presente mas viola um limite de endurecimento	Null sinaliza ausência; a ausência nunca lança
`ManifestStore::fromBoxes()` / `::empty()`	`list<JumbfBox>` / —	Constrói o objeto de valor imutável do store	`self`	Não lança	A ordem das boxes é determinante para a igualdade de ida e volta
`ManifestStore::toBytes()` / `::isEmpty()` / `::size()`	—	Serializa as boxes raiz; um store vazio serializa para uma string vazia	`string` / `bool` / `int`	Não lança	—
`JumbfBoxParser::parse()`	`string $bytes`	Analisa boxes JUMBF de nível raiz sob limites rígidos	`list<JumbfBox>`	`MalformedJumbfException`, `JumbfBombException`, `JumbfCycleDetectedException`, `JumbfDepthExceededException`	Limites: profundidade 8, 64 MiB por box, 128 MiB no total, `MAX_CHILDREN_PER_SUPERBOX` 4096
`JumbfBox::superbox()` / `::leaf()`	`string $tbox, …`	Constrói uma box validada; `toBytes()` faz ida e volta através do parser	`self`	`MalformedJumbfException` quando a TBox não tem exatamente 4 bytes	—
`C2paCapabilityStatus::current()` / `::summary()`	—	Relata a maturidade da capacidade C2PA, atualmente `preview-draft`	`self` / `string`	Não lança	Marcador de preview verificável por máquina
`Feature::PREVIEW_C2PA_DRAFT->isEnabled()`	—	Lê o ambiente do processo a cada chamada; apenas o literal `'1'` habilita	`bool`	Não lança	Variável de ambiente `NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT`
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes, string $producer`	Constrói um manifest store fixado em draft com uma asserção de claim de vínculo de hash SHA-256	`ManifestStore`	O construtor lança `LogicException` quando o sinalizador de preview está desligado	Preview; formato de fio fixado em um snapshot de draft; nenhuma assinatura de claim emitida

Assinaturas de ponto de entrada, na íntegra:

public static function default(?LoggerInterface $logger = null): self
public function withStrictUa2(bool $enabled): self
public function isStrictUa2(): bool

public function validate(string $pdfPath): EInvoiceValidationResult

public function embed(
    string $sourcePdfPath,
    string $xml,
    EInvoiceProfile $profile,
    string $outputPdfPath,
    ?FacturXEmbedderOptions $options = null,
): void

public function embed(string $pdfBytes, ManifestStore $store): string
public function extract(string $pdfBytes): ?ManifestStore

Contrato de comportamento

Relatório de language-tag. LangComplianceReporter emite um registro JSON estruturado por evento de language-tag do PDF/UA-2. Cada registro carrega o discriminador de evento fixo, uma severidade (warn para uma rejeição em modo lax, error para uma rejeição em modo strict), a tag infratora na íntegra, um motivo legível por máquina, os componentes da tag analisados (ou null quando a tag falha na gramática de forma do RFC 5646), uma referência à cláusula ISO 14289-2 §8.4.4 e um carimbo de tempo em UTC com microssegundos. O JSON viaja como o corpo da mensagem PSR-3; os sinks a jusante analisam o campo de mensagem diretamente. ConformancePolicy é a fachada do Premium sobre a política de conformidade do Core. Seu padrão aplica o tratamento estrito de idioma UA-2 e rejeita uma tag malformada ou não registrada que chegue a /Lang. O auxiliar de opt-out withStrictUa2(false) reverte para o comportamento lax legado e registra um notice PSR-3 quando o valor efetivo de fato muda. O NextPDF marca esse auxiliar como deprecated desde a v5.0 com alvo de remoção 6.0.0. Para migrar: audite o corpus em busca de valores /Lang malformados com composer pdfua2:audit-lang-tags <pdf-or-dir>, corrija-os e, em seguida, remova a chamada de opt-out.

Tratamento de fatura eletrônica. EInvoiceValidator é o contrato SPI congelado para validação de PDF híbrido: verificação do wrapper PDF/A-3, extração de anexo /AF, detecção de perfil a partir do identificador de especificação BT-24, o motor de regras de negócio EN 16931 e uma passagem de Schematron. Um PDF não Factur-X bem formado retorna EInvoiceValidationResult::notAnEInvoice() em vez de lançar; apenas falhas de I/O, estrutura de PDF malformada ou crashes de ferramenta levantam uma subclasse de EInvoiceException. EInvoiceXmlValidator é o validador de XML concreto entre camadas: ele filtra a entrada através do XmlGuard do Core, executa a pré-verificação estrutural e o corpus profundo de regras semânticas da EN 16931, e falha de forma fechada — erros do motor aparecem como achados de erro, nunca como passagens silenciosas. FacturXEmbedder transforma uma fonte PDF/A em um PDF/A-3 híbrido: ele anexa um stream de arquivo incorporado, um filespec com um /AFRelationship configurável e um pacote de extensão XMP Factur-X, e então reescreve a tabela clássica de referência cruzada. Tanto o array /AF do catálogo quanto a árvore de nomes /Names /EmbeddedFiles referenciam o anexo, de modo que leitores ZUGFeRD legados o resolvem.

Proveniência. C2paManifestEmbedder incorpora um manifest store C2PA fornecido pelo chamador em uma string de bytes de PDF, ou extrai um. ManifestStore é o objeto de valor imutável que cruza o limite. A junção é somente-bytes e neutra em relação a fornecedores: ela não sintetiza claims, não ingere referências de URI nem resolve vínculos de hash, e não realiza nenhum I/O de rede ou de sistema de arquivos. extract() retorna null em uma extração sem correspondência e é barata em PDFs sem um store. Toda extração não-null já passou pelos limites de endurecimento do JumbfBoxParser.

Este módulo relata o que verifica. Ele não certifica um documento, não o torna juridicamente vinculante nem garante que qualquer saída satisfaça uma regulamentação. O validador de fatura eletrônica não é um validador de autoridade tributária e exclui extensões nacionais (por exemplo, o SDI italiano, o Chorus Pro francês, o XRechnung alemão). Como a EN 16931-1 declara, o emissor da fatura permanece responsável por atender às regras da legislação aplicável. Dar suporte a um padrão não significa estar em conformidade com ele. Consulte sua equipe de conformidade quanto à suficiência regulatória.

Casos extremos e modos de falha

Um PDF não Factur-X bem formado retorna um resultado de “não é uma fatura eletrônica”; ele não lança.
Uma lista de violações de regra de negócio vazia não significa, por si só, que o documento é válido; verificações de wrapper e de anexo também se aplicam.
FacturXEmbedder falha de forma fechada em fontes que usam object streams comprimidos (/Type /ObjStm) ou cross-reference streams (/Type /XRef, /XRefStm híbrido). Salve novamente essas fontes com uma tabela clássica de referência cruzada primeiro.
Os payloads XML são filtrados através do XmlGuard do Core: declarações DOCTYPE ou de entidade, entrada de tamanho excessivo e UTF-8 inválido são rejeitados com uma EInvoiceException no caminho de incorporação, ou um resultado falho no caminho do validador.
FacturXContractEmbedder rejeita o perfil XRECHNUNG de forma explícita em vez de rebaixá-lo silenciosamente; a emissão de XRechnung é uma capacidade do Enterprise.
C2paManifestEmbedder::extract() distingue ausência (null) de malformação (subclasse de C2paException que nomeia o invariante violado: estrutura malformada, bomba de tamanho ou contagem, ciclo de offset, profundidade de aninhamento).
A construção de ExperimentalC2paEmbedder lança uma LogicException a menos que o sinalizador de ambiente de preview seja igual a '1'. Seu formato de fio está fixado em um snapshot de draft do C2PA e pode mudar sem aviso; ele não emite nenhuma assinatura de claim. Esta capacidade permanece em preview até que o perfil PDF do C2PA seja congelado.
O opt-out lax do strict UA-2 é deprecated; migre para o padrão strict (consulte Contrato de comportamento).
Este módulo não realiza assinatura criptográfica. A assinatura de claims C2PA e a custódia de chaves estão fora do escopo; consulte o módulo Security para o comportamento de assinatura em modo FIPS.

Conformidade

Comportamento	Referência	Status
Declaração de idioma natural (`/Lang`)	ISO 14289-2:2024 §8.4.4	Verificado / relatado
Modelo semântico central de fatura	EN 16931-1:2026	Verificado (o emissor permanece responsável)
Arquivos associados / streams de arquivo incorporado	ISO 32000-2:2020 §14.13.2	Emitido (`/AF`, `/EF`, `/Params`)
Relacionamento de anexo e regras de contêiner	Factur-X 1.08 §3.1, §6.2	Emitido / verificado (padrão `/AFRelationship /Alternative`)
Manifest store / JUMBF do C2PA	C2PA 2.1 §11.1	Incorporação / extração suportadas; síntese de claims em preview

Isto registra as especificações contra as quais o módulo é construído e o que ele verifica ou emite. Não é uma declaração de certificação ou de suficiência regulatória. O NextPDF não detém nenhuma certificação para esses padrões.

Notas de desenvolvimento

O formato de registro do reporter é um contrato estável; regras de alerta a jusante podem se fixar no discriminador de evento fixo.
Desabilitar o strict UA-2 emite um notice de deprecação visível na telemetria apenas quando o valor efetivo muda; reafirmar o valor atual é silencioso.
O embedder Factur-X preserva os bytes de origem na íntegra e anexa novos objetos; ele busca preservar a conformidade PDF/A-3 mas não revalida. Passe a saída por um validador PDF/A externo para uma atestação rigorosa.
A junção C2PA congela cinco invariantes: nenhum import de terceiros, contrato somente-bytes, sem I/O, extração null-em-ausência e nenhuma síntese de claims na camada estável.
Os limites de JumbfBoxParser são constantes públicas; dimensione as entradas que você aceita com base neles em vez de re-derivar limites.

Limite de publicação

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