# 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…

- Página: <https://www.datafirefly.com/pt/documentation/dffacturx/>
- Idioma: pt
- Atualizado em: 2026-09-03
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dffacturx/index.md), [en](https://www.datafirefly.com/en/documentation/dffacturx/index.md), [es](https://www.datafirefly.com/es/documentation/dffacturx/index.md), [de](https://www.datafirefly.com/de/documentation/dffacturx/index.md), [it](https://www.datafirefly.com/it/documentation/dffacturx/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffacturx/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacturx/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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).

**Âmbito para uma loja portuguesa.** O Factur-X é o formato híbrido franco-alemão da norma europeia EN 16931; em Portugal, a faturação eletrónica obrigatória (B2G via eSPap) usa o formato CIUS-PT (UBL 2.1), e a fatura fiscal deve ser emitida por software certificado pela AT, com ATCUD e código QR, e comunicada por SAF-T. O ficheiro gerado por este módulo não substitui essa fatura certificada: use-o para os seus clientes B2B franceses ou europeus que exigem uma fatura EN 16931, ou se a sua empresa estiver sujeita ao IVA em França. As referências a SIREN, SIRET e à reforma francesa mais abaixo dizem respeito a esse contexto.

## 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)

O módulo não usa Composer. As classes são carregadas por um autoloader PSR-4 manual incorporado, o que evita qualquer conflito de dependências com a sua instalação.

## 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.

Enquanto o SIREN não estiver preenchido, aparece uma faixa de aviso na ficha de encomenda. A geração continua possível, mas o ficheiro produzido não passará um controlo de conformidade francês.

### 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.

É possível uma diferença de um cêntimo em relação aos totais apresentados pelo PrestaShop em casos-limite de arredondamento. É esperado: a coerência interna do documento prevalece, e é ela que os validadores controlam.

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.

Instalar este módulo não basta, por si só, para o pôr em conformidade completa com a reforma francesa. Produz o formato esperado, que é a base indispensável, mas a transmissão através de uma plataforma fica por organizar do seu lado. Em Portugal, a conformidade fiscal passa, em qualquer caso, pelo software de faturação certificado pela AT.

## 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.