Faturas e faturamento eletrônico

Spec Spec: EN 16931-1:2026, BT-24 EN 16931-1:2026 BT-24 Spec Spec: Factur-X 1.08 Factur-X 1.08 Spec Spec: ISO 32000-2:2020, §14.13 ISO 32000-2:2020 §14.13 Evidence ⊕ Mixed evidence Evidence: Mixed evidence

Em resumo

Uma fatura moderna reúne dois documentos em um único arquivo: uma página legível por pessoas e uma carga útil XML legível por máquina, que um sistema tributário analisa. Esta página acompanha o cenário da fatura híbrida da obrigação até a saída: o que ZUGFeRD e Factur-X exigem, como o NextPDF anexa e verifica a carga útil estruturada e em que ponto a conformidade deixa de ser tarefa do motor e passa a ser sua.

Por que isso importa

Várias jurisdições já exigem faturas estruturadas para o faturamento entre empresas ou entre empresa e governo. A armadilha é que uma fatura híbrida pode parecer perfeita na tela e, ainda assim, ser rejeitada. A rejeição ocorre por causa do XML incorporado, não dos pixels. Se a carga útil estruturada não tiver o identificador de especificação, declarar o perfil errado ou for anexada com o relacionamento errado, a plataforma receptora a rejeita. Do seu lado, a falha costuma ser silenciosa e aparece dias depois, com um pagamento retido por trás dela.

Resolver isso uma vez, na camada que produz o arquivo, é muito mais barato do que descobrir o problema uma fatura emitida por vez.

A versão curta

• Uma fatura híbrida em conformidade é um portador PDF/A com uma carga útil XML conforme, incorporada como arquivo associado. Os metadados do portador devem declarar o perfil.
• O campo que mais frequentemente decide a aceitação é o BT-24, o identificador de especificação. A EN 16931, na regra de negócio BR-1, exige que toda fatura o contenha. O valor é uma URN que nomeia o perfil exato — por exemplo, a do perfil EN 16931 (COMFORT): urn:cen.eu:en16931:2017.
• A tarefa do NextPDF é a incorporação e a validação estrutural do XML fornecido pelo chamador. Ele não cria o conteúdo da fatura e não é um validador de autoridade tributária.
• O emissor continua responsável pela correção legal e fiscal. Um resultado de validação limpo é uma entrada para essa decisão, não um certificado.

Como o NextPDF aborda isso

O NextPDF trata a fatura estruturada como um contrato entre camadas, não como um recurso isolado. O motor core define as interfaces — um incorporador, um descritor de perfil, um validador — e a camada Premium fornece as implementações. Essa separação é deliberada. A superfície pública fica congelada no core, de modo que os pontos de chamada e os testes acessam o perfil e o resultado da mesma forma, independentemente da camada por trás deles.

O fluxo tem quatro estágios, e a ordem importa porque cada estágio depende do anterior.

1. Author the invoice XML You (or your ERP) produce a UN/CEFACT CII or Peppol UBL payload. NextPDF never synthesizes invoice content.
2. Produce the PDF/A carrier A PDF/A-3 or PDF/A-4f document is the human-readable face and the conformant container the standard requires.
3. Embed the payload The embedder attaches the XML as an associated file with the correct AFRelationship, and injects the Factur-X XMP profile declaration.
4. Validate, then ship A structural pass checks the root, the required sections, and BT-24 against the declared profile before the file leaves your system.

O cenário da fatura eletrônica híbrida de ponta a ponta: você cria o XML e detém sua correção legal; o NextPDF o transporta e o verifica estruturalmente; a plataforma receptora toma a decisão final de aceitação.

O contrato do incorporador é byte de entrada, byte de saída: entram um portador PDF/A e uma carga útil XML, e saem os bytes do PDF híbrido. Antes de qualquer coisa ser anexada, o XML passa por uma proteção reforçada que rejeita um DOCTYPE, limita o tamanho da entrada e recusa os caracteres de controle proibidos do XML 1.0. Isso elimina por construção ataques de XML External Entity e Billion-Laughs, porque o XML de faturas costuma vir de fora do limite de confiança.

O descritor de perfil responde às quatro perguntas que um sistema a jusante faz: a URN canônica do perfil, o valor de BT-24 a declarar, um nome estável para os logs e um discriminante neutro em relação à camada para que os testes de paridade possam agrupar os resultados. O descritor é honesto sobre lacunas. O perfil ZUGFeRD MINIMUM não contém o identificador de especificação BT-24, e o descritor retorna null para ele em vez de fabricar um. É também por isso que MINIMUM e BASIC WL não são conformes com a EN 16931. O motor codifica a realidade da cardinalidade em vez de ocultá-la.

Human-factors note: Human-factors note

O validador tem dois modos, e o padrão é o conservador. No modo padrão, um BT-24 ausente é reportado como aviso para que um pipeline existente que decide com base em um booleano não sofra uma regressão silenciosa. O modo estrito promove a mesma constatação a erro grave, alinhando-se à semântica dos validadores externos. O modo é uma escolha deliberada que você faz a cada chamada. O motor não escolhe a sua postura de risco por você; ele informa qual postura está ativa em vez de deixar que você a deduza.

O que as evidências dizem

O comportamento acima está ancorado em três lugares, cada um com um tipo diferente de evidência.

A norma define a obrigação. Spec Spec: EN 16931-1:2026, BR-1 EN 16931-1:2026 BR-1 torna o identificador de especificação obrigatório em toda fatura. O apêndice técnico do Factur-X fixa os valores de URN por perfil, incluindo o valor do perfil EN 16931, o urn:cen.eu:en16931:2017. O próprio portador é uma questão de PDF: Spec Spec: ISO 32000-2:2020, §9 ISO 32000-2:2020 §9 observa que a renderização mais previsível e confiável acontece quando todas as fontes estão incorporadas — algo diretamente relevante, porque uma fatura que precisa ser legível daqui a dez anos não pode depender do ambiente de fontes do leitor.

O código mantém o contrato. Evidence { } Code-backed Evidence: Code-backed As interfaces core EmbedderInterface, ProfileInterface e ValidatorInterface são interfaces reais e neutras em relação à camada. ProfileType::isEn16931Conformant() codifica a exclusão de MINIMUM / BASIC WL no sistema de tipos. ValidationResult é um DTO imutável em que isValid é a conjunção de “nenhuma constatação de erro” e “nenhuma violação fatal de regra”.

O comportamento está documentado no nível de capacidade da camada Premium: Evidence § Standard-backed Evidence: Standard-backed o incorporador anexa o XML CII fornecido pelo chamador em ZUGFeRD 2.4 / Factur-X 1.08 ou o XML UBL Peppol a um portador PDF/A-4f ou PDF/A-3b com o relacionamento de arquivo associado correto. O validador verifica o modelo semântico da EN 16931 e o identificador BT-24. O estágio Schematron executa os conjuntos de regras do CEN compilados para XSLT. Nada disso gera ou corrige o conteúdo da fatura.

Exemplo prático

O formato abaixo ilustra o ponto de integração; não é uma integração para copiar e colar. A construção do portador e o incorporador vêm da camada Premium, e o XML é seu.

<?php

declare(strict_types=1);

use NextPDF\Contracts\EInvoice\ProfileType;
use NextPDF\Contracts\EInvoice\ValidatorContext;
use NextPDF\Contracts\EInvoice\ValidatorInterface;
use NextPDF\Contracts\EInvoice\EmbedderInterface;
use NextPDF\Contracts\EInvoice\EmbedderOptions;
use Psr\Log\LoggerInterface;

/**
 * Validate first, embed second, never ship an invalid payload.
 *
 * @param non-empty-string $carrierPdf  PDF/A-3 or PDF/A-4f carrier bytes
 * @param non-empty-string $ciiXml      Caller-authored UN/CEFACT CII XML
 *
 * @return non-empty-string Hybrid invoice bytes, ready to deliver
 */
function buildHybridInvoice(
    ValidatorInterface $validator,
    EmbedderInterface $embedder,
    LoggerInterface $logger,
    string $carrierPdf,
    string $ciiXml,
): string {
    // STRICT mode: a missing BT-24 is a hard error, not a warning.
    $context = new ValidatorContext(
        profile: ProfileType::EN16931,
        strictMode: true,
    );

    $result = $validator->validate($ciiXml, $context);

    if (!$result->isValid) {
        foreach ($result->getErrors() as $finding) {
            $logger->error('invoice.structural_finding', [
                'message' => $finding->message,
            ]);
        }

        // A failed structural check is your signal to stop, not to ship.
        throw new \RuntimeException('Invoice XML failed structural validation.');
    }

    $options = new EmbedderOptions(profile: ProfileType::EN16931);

    return $embedder->embed($carrierPdf, $ciiXml, $options);
}

A ordem é o ponto central. A validação é barata em comparação com uma fatura rejeitada e um pagamento atrasado; por isso, ela é executada antes que a carga útil chegue a ser anexada.

Equívoco comum

O equívoco mais caro é “o NextPDF torna as minhas faturas em conformidade.” Ele não torna. Esta página afirma isso claramente. O motor incorpora e verifica estruturalmente o XML que você cria. Um resultado estrutural aprovado significa que a carga útil tem o formato que a EN 16931 espera e declara o perfil que você solicitou. Isso não significa que a fatura é legalmente suficiente, foi aprovada pela autoridade tributária ou tem aceitação garantida por qualquer plataforma de clearance. Extensões nacionais e transportes de clearance estão fora de escopo no nível do motor. Como a própria EN 16931-1 coloca, o modelo central carrega as informações necessárias para dar suporte à conformidade. O emissor é responsável por cumprir a legislação pertinente.

Uma segunda armadilha, mais discreta: oferecer suporte a uma norma não é o mesmo que estar em conformidade com ela. A conformidade é uma propriedade do arquivo final somado a um validador, não uma propriedade da biblioteca que o produziu.

Limites e fronteiras

• O NextPDF não cria nem corrige o conteúdo da fatura. O chamador fornece um XML válido e continua sendo o emissor da fatura. Uma lista de constatações vazia não torna conforme uma carga útil não conforme.
• A incorporação estruturada e a validação Schematron são capacidades da camada Premium. O core define os contratos; as implementações exigem o pacote comercial. Consulte a fronteira abaixo.
• O validador verifica apenas o modelo semântico da EN 16931 e o contêiner ZUGFeRD / Factur-X / UBL. Ele não é um validador de autoridade tributária. O transporte por SDI, Chorus Pro e XRechnung está fora de escopo no nível de transporte.
• Os perfis MINIMUM e BASIC WL não são conformes com a EN 16931 e não contêm o identificador de especificação BT-24 — por design, para refletir a cardinalidade da norma, não uma limitação do motor.
• O motor Schematron precisa de ext-xsl. Os conjuntos de regras são compilados em tempo de build. O runtime executa apenas o XSLT pré-compilado, com o carregamento de recursos de rede e de sistema de arquivos desativado.
• Esta página descreve o comportamento em nível de capacidade. Ela não afirma aceitação por nenhuma autoridade ou plataforma específica.

Structured e-invoice embedding and validation — edition availability

Edition	Availability
Core	○ O core define os contratos entre camadas (EmbedderInterface, ProfileInterface, ValidatorInterface), mas não fornece nenhuma implementação de fatura estruturada. Um portador PDF simples sem carga útil estruturada é o único resultado do Core.
Pro	○ A incorporação CII Factur-X 1.08 em um portador PDF/A e os descritores do perfil EN 16931 estão disponíveis.
Enterprise	○ Adiciona a incorporação UBL Peppol BIS 3.0, o CIUS B2G XRechnung, a validação XML COMPAT/STRICT e o motor de regras Schematron em processo.

Documentos relacionados

• Arquivamento e PDF/A — por que o portador da fatura é um arquivo PDF/A e o que ele garante para a legibilidade de longo prazo.
• O guia de decisão de integração — qual pacote do ecossistema se encaixa em um pipeline de faturamento (geração enfileirada, ponte de framework ou Connect).
• Operação do NextPDF em produção — como observar constatações e falhas de validação quando as faturas fluem em volume.

Glossário

• Fatura híbrida — um único arquivo PDF que funciona ao mesmo tempo como uma página legível por humanos e uma carga útil XML de fatura incorporada e legível por máquina.
• ZUGFeRD / Factur-X — os nomes alemão e francês para a mesma abordagem de fatura híbrida: uma carga útil XML Cross Industry Invoice (CII) UN/CEFACT incorporada em um portador PDF/A.
• EN 16931 — a norma europeia que define o modelo de dados semântico dos elementos centrais de uma fatura eletrônica.
• BT-24 (Identificador de especificação) — o termo de negócio da EN 16931 cujo valor é uma URN que nomeia o perfil exato com o qual a fatura está em conformidade. Exigido pela regra de negócio BR-1.
• Perfil — também chamado de nível de conformidade (MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG). Determina quais termos de negócio uma fatura deve conter.
• Arquivo associado — um arquivo anexado dentro de um PDF com um relacionamento declarado (AFRelationship) que descreve como ele se relaciona com o documento visível; o mecanismo que carrega o XML da fatura.
• Schematron — uma linguagem de regras usada para expressar as regras de negócio da EN 16931. O NextPDF executa os conjuntos de regras do CEN compilados para XSLT.