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

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

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.

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.

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.

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 para XRechnung, Mustang 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).