Factur-X: guia completo (PrestaShop 8 e 9)

Este guia cobre a instalação, a configuração e a utilização do módulo DataFirefly Factur-X (dffacturx) para PrestaShop 8 e 9. O módulo transforma as suas encomendas em faturas eletrónicas híbridas no formato Factur-X: um PDF/A-3b legível e imprimível que contém, incorporados no interior, os dados estruturados da fatura em formato XML CII (norma EN 16931).

Apresentação

Uma fatura Factur-X é um ficheiro único que reúne dois usos. O seu cliente abre um PDF clássico, que pode ler, imprimir e arquivar. O seu software de contabilidade, ou a plataforma que processa a fatura, lê diretamente o XML incorporado sem ter de interpretar a imagem. Deixa de haver dois ficheiros a sincronizar, logo deixa de haver risco de diferença entre o que é apresentado e o que é processado.

O módulo cobre a geração destes ficheiros: produz o XML, renderiza o PDF e incorpora um no outro com os metadados esperados. A transmissão através de uma Plateforme Agréée é uma camada distinta, detalhada na secção sobre o alcance regulamentar.

Pré-requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 no mínimo, 8.1 ou superior recomendado
• TCPDF, fornecido de origem com o PrestaShop: nenhuma instalação adicional
• Extensões PHP: dom (construção do XML), zlib (leitura dos metadados XMP comprimidos), zip (geração em massa)

Instalação

1. No back-office, vá a Módulos → Gestor de módulos → Instalar um módulo.
2. Carregue o ficheiro dffacturx.zip. Pode também copiar a pasta dffacturx diretamente para o diretório modules/ da sua loja.
3. Lance a instalação. O módulo regista os seus hooks e cria um separador Factur-X sob o menu Encomendas.
4. Abra a configuração e preencha a identidade do vendedor antes de gerar a sua primeira fatura.

Configuração

Identidade do vendedor

É a etapa obrigatória. Estas informações alimentam simultaneamente o PDF visível e o XML estruturado. Sem elas, o XML será rejeitado por um validador.

• Denominação social: pré-preenchida com o nome da sua loja, a corrigir se a sua denominação legal for diferente.
• SIREN: 9 algarismos, sem espaços. Indispensável para uma empresa francesa: é transmitido no XML com o identificador de esquema adequado. Uma empresa portuguesa não tem SIREN; a sua identificação passa pelo NIF no campo do IVA intracomunitário.
• SIRET: 14 algarismos, opcional mas recomendado (empresas francesas).
• N.º de IVA intracomunitário: indispensável se for sujeito passivo (ex. PT123456789 ou FR12345678901).
• Forma jurídica e capital social: apresentados nas menções legais no rodapé da fatura.
• Morada, código postal, cidade, país: o país é esperado no formato ISO de duas letras (ex. PT).
• Contacto, telefone, e-mail: retomados no XML nos perfis EN 16931 e superiores.

Perfil Factur-X

O perfil determina o nível de detalhe do XML e o identificador de especificação nele inscrito. O módulo ajusta-o automaticamente segundo a sua escolha.

• EN 16931: recomendado. Corresponde à base completa da norma europeia, aceite em todo o lado.
• BASIC: XML mais leve, conserva o detalhe das linhas.
• EXTENDED: perfil alargado, para os casos que precisam de dados adicionais.
• MINIMUM e BASIC WL: perfis sem detalhe de linhas, reservados a usos específicos.

Opções

• Descarregamento pelo cliente: ativa uma ligação na área de conta. O módulo verifica que a encomenda pertence de facto ao cliente autenticado antes de servir o ficheiro.
• Geração automática: se preencher um identificador de estado de encomenda, é gerada e guardada uma fatura na pasta generated do módulo assim que uma encomenda atinge esse estado. Os eventuais erros são escritos nos registos do PrestaShop sem bloquear a mudança de estado.

Gerar uma fatura

A partir da ficha de encomenda

Abra uma encomenda no back-office: um painel Factur-X aparece no fundo da página principal. Recorda o perfil ativo e propõe dois botões: Descarregar PDF Factur-X para o ficheiro híbrido completo, e Descarregar XML para o XML isolado, útil nas fases de teste e de validação.

Geração em massa

O menu Encomendas → Factur-X mostra a lista das suas encomendas com, em cada linha, um acesso direto ao PDF e ao XML. Para processar um lote, marque as encomendas em causa e escolha a ação em massa Descarregar os Factur-X (ZIP): o módulo reúne todas as faturas num arquivo. Se uma encomenda falhar, é ignorada e o erro é registado; o arquivo continua utilizável.

Do lado do cliente

Se a opção estiver ativada, aparece uma ligação As minhas faturas Factur-X na área de conta. O controlador front verifica que o cliente está autenticado e que a encomenda lhe pertence, caso contrário redireciona para o histórico de encomendas.

O que contém o ficheiro gerado

O PDF produzido é um PDF/A-3b renderizado pelo TCPDF do PrestaShop. O módulo acrescenta-lhe depois, por atualização incremental, os elementos que fazem dele uma fatura Factur-X:

• um objeto de ficheiro incorporado que contém o XML, chamado factur-x.xml;
• uma entrada na tabela dos ficheiros associados do catálogo, com a relação Data;
• uma entrada no dicionário dos ficheiros incorporados nomeados;
• metadados XMP que descrevem o tipo de documento, o nome do ficheiro, a versão e o nível de conformidade, acompanhados do esquema de extensão PDF/A correspondente.

A atualização incremental acrescenta estes objetos ao fim do ficheiro sem modificar um único byte do documento renderizado. Os tipos de letra, os fluxos de conteúdo e o perfil de cor produzidos pelo TCPDF ficam intactos, e o módulo não depende de nenhum detalhe interno do TCPDF, logo de nenhuma versão particular.

O XML é um CrossIndustryInvoice UN/CEFACT. Contém o contexto do documento com o identificador de especificação do perfil, o cabeçalho da fatura, as linhas se for o caso, o acordo comercial (vendedor e comprador), a entrega e o pagamento com a repartição do IVA, os descontos, os encargos e o resumo monetário.

Modelação contabilística

Os validadores Factur-X não comparam os seus totais com os do PrestaShop: verificam que o documento é coerente consigo mesmo. O módulo recalcula portanto o conjunto dos montantes a partir das linhas e da repartição do IVA, para satisfazer as regras de equilíbrio da norma.

• Linhas: o preço unitário líquido é deduzido do total da linha dividido pela quantidade. A unidade usada é o código de unidade genérico.
• Portes: modelados como encargo ao nível do documento, com a sua própria taxa de IVA.
• Descontos: modelados como allowance ao nível do documento, repartidos proporcionalmente pelas diferentes bases de IVA.
• Repartição do IVA: uma ocorrência por taxa encontrada, com base, montante e categoria.
• Categoria de IVA: categoria standard se a taxa for superior a zero, categoria zero caso contrário.
• Adiantamento: o montante pré-pago é zero e o líquido a pagar é igual ao total com IVA: a fatura é emitida, a totalidade continua devida no sentido do documento.

Os casos de IVA particulares (isenção, autoliquidação, entrega intracomunitária) não são derivados automaticamente. Se a sua atividade os implicar, mande validar algumas faturas representativas e adapte a categoria usada.

Validar antes da passagem a produção

Esta etapa não é opcional. Gere algumas faturas representativas da sua atividade (uma encomenda simples, uma encomenda com desconto, uma encomenda com várias taxas de IVA) e controle-as com:

• o validador da FNFE-MPE, referência francesa para o Factur-X;
• Mustangproject, validador open source para a conformidade EN 16931;
• veraPDF, para a conformidade do contentor PDF/A-3.

O botão de descarregamento do XML isolado foi feito para esta fase: evita-lhe extrair manualmente o anexo do PDF a cada ensaio.

Alcance regulamentar

A reforma francesa da faturação eletrónica segue um calendário em dois tempos. A 1 de setembro de 2026, todas as empresas sujeitas ao IVA em França devem poder receber faturas eletrónicas, e as grandes e médias empresas devem emiti-las. A 1 de setembro de 2027, a obrigação de emissão estende-se às PME, microempresas e empresários em nome individual. A maioria dos comerciantes PrestaShop franceses deve portanto receber desde 2026 e emitir a partir de 2027.

Devem distinguir-se três papéis:

• Gerar ficheiros Factur-X conformes: é o que este módulo faz. Não é exigida nenhuma certificação nem registo.
• Transmitir as faturas através de uma Plateforme Agréée (antiga PDP). O comerciante escolhe a sua plataforma e entrega-lhe os ficheiros.
• Ser uma Plateforme Agréée: atividade sujeita a registo pelo Estado francês, fora do perímetro do módulo.

Resolução de problemas

O validador rejeita o XML

Verifique primeiro a identidade do vendedor, em particular o SIREN e o número de IVA: são as causas de rejeição mais frequentes. Controle depois a morada de faturação do cliente: um país ou um código postal em falta pode também fazer falhar a validação.

Mensagem a indicar que o TCPDF está indisponível

O módulo usa a classe TCPDF fornecida pelo PrestaShop e, na sua falta, tenta carregá-la a partir do diretório das ferramentas. Se o erro persistir, é porque a biblioteca foi retirada da sua instalação: restaure-a a partir de um arquivo PrestaShop da mesma versão.

A ação em massa ZIP está indisponível

A extensão PHP zip não está ativada no servidor. O descarregamento unitário a partir de cada ficha de encomenda continua disponível sem ela.

A geração automática não produz nada

Verifique que o identificador de estado de encomenda está preenchido na configuração, e depois que a pasta generated do módulo tem permissão de escrita. Os erros de geração são registados nos registos do PrestaShop com o prefixo Factur-X.

O PDF abre mas o anexo não aparece

Nem todos os leitores mostram o painel dos anexos por defeito. Abra o painel dedicado do seu leitor de PDF, ou use o descarregamento do XML isolado para controlar o seu conteúdo.

Arquitetura

O módulo segue uma organização clássica, com um autoloader PSR-4 manual cuja raiz de namespace DataFirefly/FacturX aponta para a pasta src.

• src/Builder: definição dos perfis e construção do XML CII.
• src/Pdf: renderização do PDF/A-3b e incorporação do XML.
• src/Service: extração dos dados de encomenda e orquestração.
• src/Install: instalação, separador de administração e hooks.
• controllers/admin e controllers/front: controladores de descarregamento do back-office e do front-office.

A arquitetura assenta em ModuleAdminController e Smarty, idênticos entre PrestaShop 8 e 9, sem ramo de código separado nem dependência Symfony específica.

Changelog

1.0.0 (4 de junho de 2026)

• Geração de faturas híbridas Factur-X: PDF/A-3b com XML CII incorporado.
• Perfis BASIC, EN 16931 e EXTENDED selecionáveis.
• Construção do XML CII conforme UN/CEFACT com repartição do IVA por taxa.
• Incorporação autónoma do XML por atualização incremental do PDF.
• Metadados XMP Factur-X e esquema de extensão PDF/A injetados.
• Identidade do vendedor inteiramente parametrizável.
• Descarregamento PDF e XML na ficha de encomenda, geração em massa em ZIP.
• Ligação de descarregamento na área de cliente, ativável.
• Geração automática opcional na passagem a um estado de encomenda.
• Compatível com PrestaShop 8.0 a 9.0 sem ramo de código separado.