Germania — E-INVOICE DE (Unified API)

In Germania, fiskaly supporta l’invio e la ricezione di fatture elettroniche B2B. La fatturazione elettronica è regolata dal Ministero Federale delle Finanze (BMF — Bundesministerium der Finanzen). Tutte le fatture elettroniche devono essere conformi alla EN 16931, soddisfatta da formati come XRechnung, ZUGFeRD o Peppol BIS 3.0 Billing, e devono essere archiviate per 8 anni in un formato elettronico conforme (§14b UStG).

fiskaly genera fatture elettroniche conformi alla EN 16931 e le consegna tramite uno di due canali. Il canale si sceglie per ogni fattura sul destinatario (recipients[].invoicing): tramite e-mail — come ZUGFeRD o XRechnung — oppure tramite la rete PEPPOL, come XRechnung.

Le due direzioni si configurano in modo diverso:

📤

Invio — B2B

Due canali di consegna, scelti per singola fattura sul destinatario: via e-mail come ZUGFeRD o XRechnung, oppure tramite la rete PEPPOL come XRechnung. L'e-mail non richiede alcuna registrazione sulla rete.

📥

Ricezione — B2B

Solo tramite PEPPOL, quindi richiede la registrazione PEPPOL facoltativa e un Proof of Ownership verificato. Un Taxpayer che invia solo via e-mail non può ricevere. Le XRechnung in entrata al momento non vengono ricevute.

Questa pagina tratta i requisiti specifici della Germania che integrano la Guida generale di integrazione passo dopo passo. Assicuratevi di avere a disposizione le seguenti informazioni del contribuente prima di procedere:

• vat_id_number — Numero di identificazione IVA (Umsatzsteuer-ID)
• credentials.tax_number — Numero fiscale in formato ELSTER (Steuernummer)
• name — Denominazione legale registrata e nome commerciale dell’azienda o della persona fisica
• address — Indirizzo legale registrato dell’azienda o della persona fisica

📘La partita IVA è necessaria per la messa in servizio

Un System E_INVOICE_SERVICE tedesco non può essere messo in servizio se sul Taxpayer non è presente un vat_id_number valido. La Steuernummer indicata in credentials.tax_number non è sufficiente: le fatture elettroniche tedesche richiedono un’identità fiscale in forma di partita IVA, quindi i due campi non sono interscambiabili in questo contesto. Senza di essa la messa in servizio restituisce 422 Unprocessable Content.

Invio di fatture elettroniche: requisiti del destinatario

Per inviare una fattura elettronica, indicate il destinatario e il modo in cui deve raggiungerlo direttamente sul record della fattura. Quando create la fattura (TRANSACTION::INVOICE) con createRecord, aggiungete il destinatario al suo array recipients.

Come spiega la Guida generale di integrazione passo dopo passo, ogni destinatario deve essere di tipo BUSINESS e avere il blocco invoicing compilato. Oltre ai dati standard di ogni fattura elettronica (nome, indirizzo, identificazione fiscale del destinatario, righe della fattura e così via), per la Germania si aggiunge il canale di consegna sul destinatario:

• recipients[].type = BUSINESS
• recipients[].identification.type = VAT — la fattura elettronica tedesca identifica l’acquirente tramite la partita IVA
• recipients[].invoicing.type = EMAIL o PEPPOL — il canale di consegna
• recipients[].invoicing.email — (solo EMAIL) l’indirizzo e-mail del destinatario
• recipients[].invoicing.format — (solo EMAIL, opzionale) il formato del documento
• recipients[].invoicing.identifier — (solo PEPPOL) il PEPPOL Network Identifier del destinatario

invoicing.type	Richiesto anche	Come fiskaly effettua la consegna
EMAIL	invoicing.email	Via e-mail a quell’indirizzo, come ZUGFeRD o XRechnung secondo invoicing.format.
PEPPOL	invoicing.identifier	All’endpoint PEPPOL del destinatario, come XRechnung — vedi la limitazione XRechnung.

Il canale si sceglie per ogni fattura e non una volta per destinatario — la stessa azienda può ricevere una fattura via e-mail e la successiva tramite PEPPOL.

📘Importante

Senza il blocco invoicing, la fattura elettronica viene creata ma non consegnata al destinatario.

Registrazione PEPPOL

In Germania la registrazione sulla rete PEPPOL è facoltativa: scegliete di attivarla System per System.

Indicatela sul System E_INVOICE_SERVICE con createSystem:

{
  "content": {
    "type": "E_INVOICE_SERVICE",
    "location": { "id": "..." },
    "software": { "...": "..." },
    "registrations": [{ "type": "PEPPOL" }]
  }
}

Oppure aggiungetela a un System esistente con updateSystem:

{
  "content": {
    "registrations": [{ "type": "PEPPOL" }]
  }
}

Cosa comporta questa scelta:

• registrations omesso — il System invia solo via e-mail. Non è necessario alcun Proof of Ownership e il System passa direttamente alla modalità OPERATIVE.
• registrations include PEPPOL — è necessario un Proof of Ownership. Alla messa in servizio lo state del System diventa COMMISSIONED, ma la sua mode diventa DEGRADED, e il System riporta una voce di log che segnala l’assenza del Proof of Ownership.

Per portare il System alla modalità OPERATIVE, caricate il Proof of Ownership come descritto al passo 11 della guida generale di integrazione. La verifica richiede fino a 72 ore; al termine il System cambia stato automaticamente e la voce di log viene rimossa. Il contenuto richiesto del documento è descritto nella sezione Proof of Ownership.

📘Aggiungere PEPPOL in seguito

Potete aggiungere PEPPOL a un System già messo in servizio. In questo modo la verifica del Proof of Ownership viene eseguita di nuovo, quindi un System che non ha mai fornito il documento torna alla modalità DEGRADED fino a quando non lo fa.

Invio tramite PEPPOL

Sul destinatario della vostra richiesta createRecord, impostate:

• recipients[].invoicing.type = PEPPOL
• recipients[].invoicing.identifier — il PEPPOL Network Identifier del destinatario

Sono necessarie due condizioni: il vostro System E_INVOICE_SERVICE deve essere registrato sulla rete PEPPOL (vedi Registrazione PEPPOL) e dovete disporre del PEPPOL Network Identifier del destinatario. Allo schema dell’identificativo pensa fiskaly.

Le fatture inviate in questo modo vengono generate come XRechnung. recipients[].invoicing.format non ha alcun ruolo qui: su questo canale il formato non è selezionabile.

⚠️La maggior parte dei destinatari PEPPOL non può ricevere XRechnung

PEPPOL registra ogni partecipante per gli specifici tipi di documento che è in grado di ricevere e, sulla rete, XRechnung è un tipo di documento a sé. L’invio a un destinatario non registrato per XRechnung fallisce con receiver does not support document type.

A determinarlo non è la conformità: XRechnung segue le regole Peppol BIS 3.0, ma questo non la rende recapitabile a un partecipante registrato solo per Peppol BIS Billing 3.0. Al momento fiskaly non genera Peppol BIS Billing 3.0 per la Germania: recipients[].invoicing.format offre ZUGFERD_V2 e XRECHNUNG_V3 e riguarda soltanto il canale e-mail.

Finché non sapete che un destinatario è registrato per XRechnung, inviate a quel destinatario via e-mail.

📘Il B2G non è ancora supportato

L’invio agli enti pubblici tedeschi (B2G) non è ancora supportato, pertanto l’indirizzamento tramite Leitweg-ID non è disponibile.

Invio via e-mail: scelta del formato del documento

Quando il canale è EMAIL, decidete quale formato del documento fiskaly genera. Impostatelo sullo stesso destinatario nella vostra richiesta createRecord, tramite recipients[].invoicing.format:

Valore	Formato
ZUGFERD_V2 (predefinito)	ZUGFeRD — un documento ibrido: un PDF/A-3 leggibile dall’utente con l’XML strutturato incorporato al suo interno.
XRECHNUNG_V3	XRechnung — una fattura XML puramente strutturata, senza livello PDF.

Il campo è opzionale: se lo omettete, fiskaly genera ZUGFERD_V2. Entrambi i formati sono conformi alla EN 16931.

Ricezione di fatture elettroniche

La ricezione delle fatture in entrata avviene tramite PEPPOL e dipende quindi dalla stessa registrazione PEPPOL richiesta per l’invio tramite PEPPOL — Proof of Ownership verificato incluso. Un Taxpayer che invia solo via e-mail non può ricevere.

Quando registrate un Taxpayer tedesco su PEPPOL, fiskaly lo registra per impostazione predefinita sia per l’invio sia per la ricezione. Le fatture in entrata indirizzate al PEPPOL Identifier del System vengono associate a quel System e fiskaly crea per ognuna un Record di tipo E_INVOICE::RECEPTION.

⚠️Le XRechnung in entrata non raggiungono il vostro Taxpayer

La registrazione per la ricezione copre Peppol BIS Billing 3.0, non XRechnung. Una fattura indirizzata al vostro Taxpayer come XRechnung viene respinta dalla rete prima di arrivare a fiskaly, quindi non viene creato alcun Record di tipo E_INVOICE::RECEPTION. È la stessa limitazione sui tipi di documento registrati descritta in Invio tramite PEPPOL.

Chiamate retrieveSystem per leggere compliance.state:

• TRANSMISSION_RECEPTION — il System può inviare e ricevere.
• TRANSMISSION_ONLY — il System può solo inviare.

⚠️Se compliance.state resta su TRANSMISSION_ONLY

Invio e ricezione è il comportamento predefinito, ma fiskaly ricade su una registrazione di solo invio se la registrazione PEPPOL segnala un conflitto — in genere perché il PEPPOL Participant Identifier del vostro Taxpayer è già registrato presso un altro fornitore. Il System resta utilizzabile per l’invio. Se contavate di ricevere, contattate il team di supporto fiskaly all’indirizzo dev-support@fiskaly.com indicando la partita IVA del Taxpayer.

Recupero delle fatture ricevute

Ogni fattura indirizzata al vostro Taxpayer viene ricevuta e archiviata automaticamente come Record — non esiste alcun webhook, quindi interrogate l’API per individuare quelle nuove:

1. Chiamate listRecords e filtrate per E_INVOICE::RECEPTION.
2. Per ogni nuovo Record chiamate retrieveRecord con compliance-artifact per ottenere l’XML firmato.

listRecords restituisce i Record più recenti (limit vale 10 per impostazione predefinita, dal più recente): tenete quindi traccia di quelli già elaborati.