ZUGFeRD Creator: configuração e associação

Passo 1

Servidor e chave

No separador „Preferences“ há três indicações: o endereço do próprio servidor web onde está a componente PHP, uma chave API para a sugestão de IA, que é opcional, e a chave de licença. Por baixo estão dois campos de contentor onde ficam a PDF ZUGFeRD e o ficheiro UBL gerados.

O gráfico à direita na imagem mostra o caminho: da fatura no programa de faturação nasce, através da associação segundo a EN 16931, uma PDF/A-3 com XML incorporado.

Passo 2

A associação

O separador „Zuordnung“ (associação) é a página central. Em cima à direita há um separador por tipo de documento, aqui „Rechnung“ (fatura) e „Gutschrift“ (nota de crédito), além de „+ Belegart“.

À esquerda estão as definições do tipo de documento: nome, código de tipo (380 para a fatura, 381 para a nota de crédito), a ocorrência de tabela do documento, o layout, o campo com o número do documento, o contentor com a fatura impressa, os contentores de destino e as indicações sobre as linhas.

À direita está a associação propriamente dita, dividida em cinco áreas com contador: documento 15/17, vendedor 9/10, comprador 7/7, pagamento 4/5, linhas 8/9. Cada linha é um valor da fatura eletrónica, com o seu número da norma (BT-1, BT-2, BT-5 e assim por diante) e uma breve explicação. Ao lado o campo de entrada: aí está um campo da própria solução, uma fórmula FileMaker ou um valor fixo. A pequena marca a seguir diz o que é:

Os dados obrigatórios estão marcados, bem como os dados que só são obrigatórios para a XRechnung, por exemplo Leitweg-ID, pessoa de contacto, telefone e e-mail do emissor.

A pré-visualização

Totalmente à direita está a coluna „Vorschau“ (pré-visualização). Quem introduzir em baixo um número de documento e premir „Vorschau“ vê por linha o valor real desse documento, antes de a primeira fatura ser criada. Em baixo à esquerda está o resultado, na imagem „Vorschau für RE602127: 48 Werte, 7 leer.“ (48 valores, 7 vazios). Assim vê-se antes do primeiro teste se a associação se sustenta.

Passo 3

A sugestão de IA

Em vez de preencher a associação à mão, prime-se em baixo „KI-Vorschlag“ (sugestão de IA). O software envia os nomes e tipos dos campos ao próprio servidor, que consulta um modelo de linguagem. Volta, por valor, uma sugestão com justificação.

Na imagem vê-se a área „Verkäufer“ (vendedor). À direita está por linha a origem e a confiança, „KI · hoch“ (IA · alta) ou „KI · mittel“ (IA · média), por baixo a justificação em texto claro, por exemplo „NIF-IVA do emissor“ ou „sem campo de código de país no vendedor, empresa alemã“. Se a IA não encontrar nada, aparece a vermelho „KI · niedrig · nichts gefunden“ (IA · baixa · nada encontrado).

O que muda em relação ao estado guardado recebe a marca „GEÄNDERT“ (alterado) ou „NEU“ (novo). O valor antigo fica riscado ao lado, um pequeno botão „zurück“ (repor) restaura-o. Em baixo está o balanço, na imagem „29 von der KI, 14 über den Namen, 5 offen, prüfen und speichern.“ (29 da IA, 14 pelo nome, 5 em aberto, verificar e guardar).

Importante: São transferidos apenas nomes de campos e tabelas, nenhum dado de fatura. A chave API pertence ao cliente, a função é opcional.

Passo 4

Outros tipos de documento

Cada tipo de documento tem o seu próprio separador e a sua própria associação. A nota de crédito tem o código de tipo 381 e nela está preenchido „Bezug auf Rechnung“ (BT-25), a referência à fatura original.

Um novo tipo de documento cria-se com „+ Belegart“: à esquerda introduzir nome e ocorrência de tabela. Ao escrever, o software sugere todas as ocorrências de tabela da solução ligada. A mesma ajuda existe em cada campo de associação para os nomes dos campos.

Passo 5

Guardar e transferir

Com „Export“ pode mostrar-se e copiar toda a associação como JSON, com „Import“ volta a importar-se. Assim se guarda uma configuração pronta ou se transfere para outra instalação.

Passo 6

Testar

Em cima à esquerda estão „Test PDF“ e „Test UBL“ com um campo para o número do documento. Ambos geram o ficheiro exatamente como o programa de faturação o fará mais tarde. O resultado fica nos campos de contentor do passo 1: à esquerda a PDF ZUGFeRD final, que se parece com a fatura habitual e traz o XML no interior, à direita o ficheiro UBL da XRechnung.

Passo 7

Integração na própria solução

Na própria solução basta um botão que chama um script com três indicações: tipo de documento, número do documento e formato. Volta o ficheiro final.

1. Nenhum campo da própria solução tem de ser alterado.
2. Sem campos auxiliares, sem layouts com campos.
3. O que muda, muda na associação, não no programa de faturação.

A outra direção

Ler faturas recebidas

O Creator escreve faturas eletrónicas. As faturas recebidas são lidas pelo ZUGFeRD Reader, que utiliza a mesma componente de servidor e vem logo incluído na ZUGFeRD Suite. Aceita o que circula no mercado: ZUGFeRD e Factur-X como PDF/A-3 com XML incorporado, XRechnung como UBL, fatura e nota de crédito, bem como CII-XML puro. O servidor reconhece por si o que recebe.

O resultado é uma vista legível do documento, com a verificação: dados obrigatórios completos, totais batem certo, no ZUGFeRD adicionalmente o esquema. Para UBL não há esquema no pacote, aí são verificados dados obrigatórios e regras de cálculo. Uma nota de crédito com código de tipo 381 passa da mesma forma, com referência à fatura original. Se o mesmo documento for lido uma segunda vez, o Reader avisa „Schon im Eingang“ (já na caixa de entrada).

O que acontece depois com o documento é decidido pela sua solução. O Reader coloca-o na caixa de entrada, verifica-o e disponibiliza um JSON. Nesse ponto assume um script, no qual o seu sistema de gestão cria a partir dele um documento de entrada, uma aprovação ou uma entrega a outro sistema.

Configura-se como o Creator, com o endereço do próprio servidor e a chave de licença. Dois botões de teste mostram logo após a instalação se a ligação está estabelecida.

Fidelidade à norma

Formatos e verificação

O software foi desenvolvido e testado contra as regras de validação oficiais, o Schematron CEN da EN 16931 e as regras de validação da XRechnung. Em funcionamento, o servidor verifica os dados obrigatórios e calcula os totais.

Armazenamento de dados

Onde ficam os dados

A componente PHP corre no servidor do cliente, na empresa ou no seu alojamento. Sem cloud, sem telemetria, sem ativação pela rede. A chave de licença é verificada no servidor do cliente, sem ligação ao exterior. Os dados das faturas não saem da casa do cliente.

Requisitos

O que precisa

Prazos

A partir de quando se aplica

1. Desde 2025, todas as empresas têm de poder receber faturas eletrónicas.
2. A partir de 1 de janeiro de 2027, as empresas com mais de 800.000 euros de volume de negócios no ano anterior têm de emitir faturas eletrónicas.
3. A partir de 1 de janeiro de 2028 aplica-se a todas.