Salta ai contenuti

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. fiskaly non archivia le fatture elettroniche tedesche: vedere Archiviazione.

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:

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:

  • fiscalization.vat_id_number — Numero di identificazione IVA (Umsatzsteuer-ID), 9 cifre senza il prefisso DE
  • fiscalization.tax_id_number — Numero di identificazione fiscale personale (Steuer-ID), 11 cifre. Obbligatorio per i Taxpayer di tipo INDIVIDUAL.
  • name — Denominazione legale registrata e nome commerciale dell’azienda o della persona fisica
  • address — Indirizzo legale registrato dell’azienda o della persona fisica

Invio di fatture elettroniche: requisiti del destinatario

Sezione intitolata “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[].address.country = DE — i destinatari devono trovarsi in Germania
  • 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, nella forma <codice schema>:<valore> — tipicamente 9930:<numero di partita IVA> per un’azienda tedesca
invoicing.typeRichiesto ancheCome fiskaly effettua la consegna
EMAILinvoicing.emailVia e-mail a quell’indirizzo, come ZUGFeRD o XRechnung secondo invoicing.format.
PEPPOLinvoicing.identifierAll’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.

Ogni voce di payments è un pagamento già ricevuto (CASH, CARD, ONLINE, VOUCHER, OTHER) oppure l’importo ancora da pagare (OUTSTANDING). I pagamenti ricevuti compaiono in fattura come importo già pagato, e la data della voce OUTSTANDING diventa la data di scadenza della fattura. Per una fattura interamente pagata, omettete OUTSTANDING.

Ogni pagamento richiede type e details.amount. Alcuni tipi richiedono altro:

typeObbligatorio inoltre
CASH—
CARDnumber (numero di carta mascherato, ad esempio ************1234) e kind
ONLINEname, ad esempio il prestatore di servizi di pagamento
VOUCHERnumber e kind
OTHER— (name è facoltativo)
OUTSTANDINGconcept (GOOD, SERVICE o INVOICE) e details.date, la data di scadenza

concept è accettato solo su OUTSTANDING. Su qualsiasi altro tipo di pagamento, la richiesta viene rifiutata con 400.

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.

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.

Invio via e-mail: scelta del formato del documento

Sezione intitolata “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:

ValoreFormato
ZUGFERD_V2 (predefinito)ZUGFeRD — un documento ibrido: un PDF/A-3 leggibile dall’utente con l’XML strutturato incorporato al suo interno.
XRECHNUNG_V3XRechnung — 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.

fiskaly invia l’e-mail per conto del venditore, dall’indirizzo no-reply.e-invoicing@fiskaly.com. L’oggetto è «Your Invoice» e il testo è in inglese. L’e-mail indica il venditore e rimanda il destinatario al venditore per qualsiasi domanda sulla fattura.

L’e-mail viene inviata subito dopo la creazione della fattura (l’elaborazione è asincrona, vedi sotto). Non esiste un trigger di invio separato: per ritardare la consegna, ritardate la chiamata a createRecord.

La fattura è allegata come invoice_<id>.xml (XRechnung) o invoice_<id>.pdf (ZUGFeRD), dove <id> è l’ID del Record E_INVOICE::TRANSMISSION.

Ogni fattura inviata tramite PEPPOL viene generata come XRechnung, così come ogni fattura via e-mail con XRECHNUNG_V3. XRechnung richiede due campi che ZUGFeRD non richiede:

CampoRegola XRechnungValore
document.references.buyerBR-DE-15Da 1 a 32 caratteri: lettere, cifre, spazi e . - _ /. Obbligatorio su ogni fattura, non solo per gli acquirenti della pubblica amministrazione.
seller.phoneBR-DE-6Numero di telefono di contatto del venditore in formato E.164, ad esempio +49301234567.

Ogni fattura richiede due chiamate a createRecord, come descritto al passo 12 della guida di integrazione generale: una INTENTION e poi una TRANSACTION::INVOICE che vi fa riferimento. Inviate ogni chiamata con una nuova chiave di idempotenza. Sostituite gli ID e i valori con i vostri.

Intention
{
"content": {
"type": "INTENTION",
"system": {
"id": "<E_INVOICE_SERVICE System ID>"
},
"operation": {
"type": "TRANSACTION"
}
}
}
Fattura via e-mail come ZUGFeRD
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "EMAIL",
"email": "invoices@beispiel-gmbh.de",
"format": "ZUGFERD_V2"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}
Fattura via e-mail come XRechnung
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00",
"references": {
"buyer": "PO-4711"
}
},
"seller": {
"name": "Max Mustermann",
"phone": "+49301234567",
"email": "billing@example-seller.de"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "EMAIL",
"email": "invoices@beispiel-gmbh.de",
"format": "XRECHNUNG_V3"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}
Fattura tramite PEPPOL (XRechnung)
{
"content": {
"type": "TRANSACTION",
"record": {
"id": "<INTENTION Record ID>"
},
"operation": {
"type": "INVOICE",
"document": {
"number": "RE-2026-0001",
"issued_at": "2026-10-05T10:00:00+02:00",
"references": {
"buyer": "PO-4711"
}
},
"seller": {
"name": "Max Mustermann",
"phone": "+49301234567",
"email": "billing@example-seller.de"
},
"entries": [
{
"type": "SALE",
"data": {
"type": "ITEM",
"text": "Consulting service",
"unit": {
"quantity": "2",
"price": {
"exclusive": "100.00",
"inclusive": "119.00"
}
},
"value": {
"base": "200.00"
},
"vat": {
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
},
"details": {
"concept": "SERVICE"
}
}
],
"recipients": [
{
"type": "BUSINESS",
"name": "Beispiel GmbH",
"address": {
"line": {
"type": "STREET_NUMBER",
"street": "Alexanderplatz",
"number": "1"
},
"code": "10178",
"city": "Berlin",
"country": "DE"
},
"identification": {
"type": "VAT",
"number": "369204173"
},
"invoicing": {
"type": "PEPPOL",
"identifier": "9930:DE369204173"
}
}
],
"payments": [
{
"type": "OUTSTANDING",
"details": {
"amount": "238.00",
"currency": "EUR",
"date": "2026-11-04"
},
"concept": "SERVICE"
}
],
"breakdown": [
{
"type": "VAT_RATE",
"code": "STANDARD",
"percentage": "19.00",
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
],
"totals": {
"vat": {
"amount": "38.00",
"exclusive": "200.00",
"inclusive": "238.00"
}
}
}
}
}

L’invio è asincrono. createRecord risponde non appena la TRANSACTION::INVOICE viene accettata; la fattura e la sua trasmissione vengono elaborate in seguito. Non esistono webhook per questo, quindi interrogate lo stato con retrieveRecord. Ogni Record indica il suo avanzamento in mode: PROCESSING finché l’elaborazione è in corso, FINISHED quando è terminata. state contiene quindi l’esito.

Quando la TRANSACTION::INVOICE è FINISHED, COMPLETED da solo non significa che la fattura sia stata inviata. Verificate che i suoi logs non contengano voci con "severity": "ERROR" e che used_in sia presente.

used_in.id è il Record E_INVOICE::TRANSMISSION. Interrogatelo finché il suo mode non è FINISHED. Il suo state indica l’esito:

  • COMPLETED — la fattura è stata consegnata per il recapito.
  • FAILED — la fattura non è stata recapitata. Il motivo è riportato nei logs del Record.

Per l’e-mail, COMPLETED significa che la fattura è stata consegnata al gateway e-mail di fiskaly. Il recapito nella casella del destinatario non può essere confermato e gli eventuali rimbalzi successivi non vengono riportati sul Record.

Se il gateway e-mail rifiuta un’e-mail in modo definitivo, la trasmissione termina subito in FAILED. Gli errori temporanei vengono ritentati in background, quindi la trasmissione può restare in PROCESSING per un certo tempo. Termina in FAILED solo quando tutti i tentativi sono esauriti.

Una fattura non riuscita non è stata emessa. Inviatela di nuovo come nuova TRANSACTION::INVOICE (nuova INTENTION, nuova chiave di idempotenza) con lo stesso numero di fattura, non come CORRECTION. Per correggere una fattura che ha raggiunto l’acquirente, emettete una nota di credito.

Per maggiori dettagli, consultate l’articolo di supporto How to detect and handle failed invoices (in inglese).

Cosa vedeteCausa
Log ERROR either party.telephones or party.people[0].telephones is required (BR-DE-6), nulla viene inviatoXRechnung senza seller.phone
Log ERROR sulla TRANSACTION::INVOICE, nessun used_in, nulla viene inviatoXRechnung senza document.references.buyer
400 su createRecorddocument.references.buyer vuoto o un altro errore di schema
receiver does not support document typeDestinatario PEPPOL non registrato per XRechnung: vedere Invio tramite PEPPOL
422 Unprocessable Content durante la messa in servizioTaxpayer senza vat_id_number

Chiamate retrieveRecord sulla E_INVOICE::TRANSMISSION (used_in.id) con compliance-artifact per ottenere la fattura elettronica generata. La risposta è un envelope JSON. Per XRechnung, content.compliance.artifact è:

{ "type": "application/xml", "data": "<base64>" }

Per ZUGFeRD, content.compliance.artifact è il PDF/A-3 con l’XML incorporato:

{ "type": "application/pdf", "data": "<base64>" }

La guida Nota di credito spiega quando e come emettere una nota di credito. Questa sezione tratta solo ciò che vale specificamente per la Germania.

Una nota di credito è un documento completo a sé stante e non riprende alcun dato dalla fattura originale. Invia lo stesso destinatario, canale e formato della fattura. Per XRechnung, invia di nuovo anche seller.phone, seller.email e document.references.buyer. Senza questi campi non viene inviato nulla e il record riceve un log ERROR (BR-DE-6, BR-DE-7, BR-DE-15).

Pagamenti sulle note di credito e sulle fatture che le annullano

Sezione intitolata “Pagamenti sulle note di credito e sulle fatture che le annullano”

Su una nota di credito, e su una fattura che annulla una nota di credito, payments descrive ciò che resta aperto su quel documento:

  • Parte saldata: type: OTHER con details.amount e details.currency, senza data.
  • Importo ancora da pagare: type: OUTSTANDING con concept, details.amount, details.currency e details.date, la data di scadenza (obbligatoria).

La fattura elettronica mostra la parte saldata come già pagata e il resto come da pagare entro la data di scadenza. I due tipi possono essere combinati sia sulle note di credito sia sulle fatture.

DocumentoSituazionepayments
Nota di creditoRimborso già pagato al clienteOTHER = importo accreditato
Nota di creditoRimborso ancora da pagareOUTSTANDING con data di scadenza
Nota di creditoRimborso parzialeOTHER (parte rimborsata) + OUTSTANDING (resto)
Fattura che annulla la nota di creditoRimborso pagato per intero, il cliente lo restituisceOUTSTANDING = importo totale
Fattura che annulla la nota di creditoRimborso pagato in parte (ad es. 50,00 su 119,00)OTHER 69.00 + OUTSTANDING 50.00
Fattura che annulla la nota di creditoNessun rimborso pagato, i documenti si compensanoOTHER = importo totale
Esempio: fattura che annulla una nota di credito, rimborso pagato in parte
"payments": [
{
"type": "OTHER",
"details": {
"amount": "69.00",
"currency": "EUR"
}
},
{
"type": "OUTSTANDING",
"concept": "SERVICE",
"details": {
"amount": "50.00",
"currency": "EUR",
"date": "2026-11-30"
}
}
]

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.

Chiamate retrieveSystem per leggere compliance.state:

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

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.

Potete recuperare la fattura elettronica generata di una fattura inviata e l’XML di una fattura ricevuta.