# DataFirefly Factur-X SW: fatura eletrónica Shopware 6, guia completo
> Apresentação O DfFacturX SW gera faturas eletrónicas conformes à EN 16931 para Shopware 6.5, 6.6 e 6.7. A cada criação de um documento de fatura, a extensão constrói um XML…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dffacturx-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dffacturx-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dffacturx-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dffacturx-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dffacturx-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffacturx-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacturx-shopware/index.md)
- Índice:
## Apresentação
O DfFacturX SW gera faturas eletrónicas conformes à **EN 16931** para Shopware 6.5, 6.6 e 6.7. A cada criação de um documento de fatura, a extensão constrói um XML UN/CEFACT CII e, consoante o perfil escolhido, incorpora-o no PDF da fatura (Factur-X / ZUGFeRD) ou fornece-o como ficheiro autónomo (XRechnung 3.0 para o B2G alemão).
- **Factur-X / ZUGFeRD EN 16931**: perfil recomendado para o B2B; o PDF transferido pelo cliente é a fatura eletrónica híbrida.
- **Factur-X BASIC**: perfil aligeirado, para os destinatários que não exigem o conjunto completo da EN 16931.
- **XRechnung 3.0**: XML autónomo em sintaxe CII para faturar as administrações alemãs, com Leitweg-ID obrigatório.
A faturação eletrónica à administração pública portuguesa exige o CIUS-PT em sintaxe UBL 2.1, submetido através da plataforma FE-AP da eSPap. Esse formato não é produzido por esta versão da extensão.
## Instalação
1. Copie a pasta da extensão para `custom/plugins/DfFacturX` (ou carregue o ZIP a partir da administração, em Extensões e depois As minhas extensões).
2. Execute:
```
bin/console plugin:refresh
bin/console plugin:install --activate DfFacturX
bin/console cache:clear
```
A ativação instala o conjunto de campos personalizados **Fatura eletrónica (DfFacturX)** com o campo `df_facturx_buyer_reference` no cliente e na encomenda. É aí que se introduz o Leitweg-ID (BT-10).
## Configuração
Administração, Extensões, DfFacturX, Configuração. Todas as definições têm âmbito por canal de venda.
### Geral
- **Ativar a geração**: aciona a criação do XML a cada novo documento de fatura.
- **Perfil**: Factur-X EN 16931, Factur-X BASIC ou XRechnung 3.0.
- **Incorporar o XML no PDF**: para os perfis Factur-X; o média do documento é substituído pelo PDF híbrido.
- **Anexar o XML aos emails**: acrescenta `factur-x.xml` (ou `numero-xrechnung.xml`) aos emails de encomenda.
- **Apenas B2B**: só gera se a encomenda tiver uma empresa ou um número de IVA.
### Vendedor
Denominação social, rua, código postal, localidade, país (ISO-2), número de IVA (BT-31), número fiscal (BT-32), email (BT-34), telefone e pessoa de contacto (BG-6). O email e o contacto são exigidos pelo XRechnung.
Campos mínimos do vendedor: nome, rua, código postal, localidade, país, mais o número de IVA _ou_ o número fiscal (regra BR-CO-26). Sem eles, a geração falha com um erro explícito nos registos.
### Pagamento
IBAN e BIC (transferência SEPA, código 58), texto das condições de pagamento (BT-20) e prazo de vencimento em dias (BT-9). Sem IBAN, o meio de pagamento é declarado com o código 1 (não definido).
### Gestão do IVA
Para as taxas a 0 %, o modo **Automático** aplica: **K** entrega intracomunitária (comprador com IVA noutro país da UE), **G** exportação fora da UE, **Z** nos restantes casos. Pode forçar uma categoria fixa (Z, E, K, G) e personalizar o motivo de isenção (BT-120).
### XRechnung
Nome técnico do campo personalizado que contém a referência do comprador (por predefinição `df_facturx_buyer_reference`) e valor de recurso se nenhum campo estiver preenchido.
## Leitweg-ID e referência do comprador (BT-10)
Introduza o Leitweg-ID uma vez na ficha do cliente (separador de campos personalizados): será reutilizado em todas as suas faturas. Para um caso pontual, preencha-o diretamente na encomenda; o valor da encomenda prevalece sobre o do cliente, que prevalece sobre o valor de recurso.
No perfil XRechnung, se não for encontrada qualquer referência do comprador, a extensão **recusa gerar** um XML inválido e regista um erro. Corrija o dado e relance com `df:facturx:generate --force`.
## Funcionamento
1. Na criação do documento de fatura (administração, Flow Builder ou API), a extensão carrega a encomenda na sua versão exata.
2. O XML CII é construído e guardado nos campos personalizados do documento (`df_facturx_xml`, `df_facturx_profile`, `df_facturx_generated_at`).
3. No perfil Factur-X, o XML é incorporado no PDF por atualização incremental: ficheiro `factur-x.xml` anexado, metadados XMP PDF A-3 e esquema de extensão Factur-X. O média do documento é substituído no local.
4. Se a opção estiver ativa, o XML é anexado aos emails de encomenda.
Com o Flow Builder, acrescente a ação de geração de fatura ao seu fluxo de encomenda: a fatura eletrónica segue automaticamente, sem qualquer ação adicional.
Por conceção, um erro de fatura eletrónica nunca bloqueia a criação do documento: o incidente é registado e a fatura PDF clássica continua disponível.
## Modelo contabilístico EN 16931
- **Modelo líquido**: as encomendas com IVA incluído são convertidas através dos impostos calculados do Shopware.
- **Promoções**: convertidas em descontos ao nível do documento (BG-20), uma entrada por taxa de IVA, porque a norma proíbe linhas negativas (BR-27).
- **Portes**: declarados como encargos ao nível do documento (BG-21), uma entrada por taxa.
- **RoundingAmount (BT-114)**: absorve qualquer desvio de arredondamento; o GrandTotal do XML é rigorosamente igual ao total da encomenda Shopware.
- **Pagamento SEPA**: transferência com código 58, IBAN/BIC, vencimento calculado a partir da data da fatura.
## Comando de consola
```
# Regenerar a fatura eletrónica da última fatura de uma encomenda
bin/console df:facturx:generate 10042 --force
# Exportar o XML para um ficheiro (para um validador)
bin/console df:facturx:generate 10042 --output=/tmp/10042.xml
# Forçar um perfil pontualmente (implica a regeneração)
bin/console df:facturx:generate 10042 --profile=xrechnung-30
```
## Checklist de validação antes da produção
1. Crie encomendas de teste que cubram os seus casos reais: canal com IVA incluído e canal sem IVA, promoção, portes, venda intracomunitária com número de IVA, exportação fora da UE.
2. Gere a fatura para cada uma e exporte o XML com `--output`.
3. Valide: [validador KOSIT](https://github.com/itplr-kosit/validator) para XRechnung, [Mustang](https://www.mustangproject.org) para Factur-X / ZUGFeRD.
4. Abra o PDF híbrido no Adobe Acrobat e verifique a presença do anexo `factur-x.xml`.
## Resolução de problemas
- **Nenhum XML gerado**: verifique que a extensão está ativa para o canal de venda, que o tipo de documento é mesmo _fatura_, e que o modo apenas B2B não está a filtrar a encomenda. Consulte os registos (`var/log`).
- **Erro «Missing seller configuration»**: complete o cartão Vendedor (campos mínimos acima).
- **Aviso «PDF embedding skipped»**: a estrutura do PDF não permitiu a incorporação; o XML continua disponível em anexo de email e pela consola. Caso típico: PDF gerado por um motor de terceiros.
- **XRechnung recusado**: referência do comprador em falta; preencha o campo personalizado ou o valor de recurso, e depois `--force`.
- **Regeneração após alteração da configuração**: os documentos já tratados não são reprocessados automaticamente; use `df:facturx:generate --force`.
## Limites conhecidos e roteiro
- Versão 1.0: apenas faturas (código 380). Notas de crédito (381) e faturas retificativas (384) previstas para a 1.1.
- A conformidade estrita PDF/A-3B depende também de propriedades do PDF de origem produzido pelo motor dompdf do Shopware (fontes incorporadas, output intent). Os destinatários e as ferramentas de contabilidade usam o XML incorporado em qualquer caso; para uma exigência estrita PDF/A-3B, use o perfil XRechnung ou o anexo XML.
- Uma única linha de IVA por linha de encomenda (comportamento normal do Shopware).