Aller au contenu

Allemagne — E-INVOICE DE (Unified API)

En Allemagne, fiskaly prend en charge l’envoi et la réception de factures électroniques B2B. La facturation électronique est réglementée par le Ministère fédéral des Finances (BMF — Bundesministerium der Finanzen). Toutes les factures électroniques doivent être conformes à la norme EN 16931, satisfaite par des formats tels que XRechnung, ZUGFeRD ou Peppol BIS 3.0 Billing. fiskaly n’archive pas les factures électroniques allemandes — voir Archivage.

fiskaly génère des factures électroniques conformes à la norme EN 16931 et les transmet via l’un des deux canaux. Le canal est choisi par facture sur le destinataire (recipients[].invoicing) : par e-mail — au format ZUGFeRD ou XRechnung — ou via le réseau PEPPOL, au format XRechnung.

Les deux directions se configurent différemment :

Cette page couvre les exigences spécifiques à l’Allemagne qui complètent l’Intégration générale étape par étape. Assurez-vous de disposer des informations suivantes sur le contribuable avant de continuer :

  • fiscalization.vat_id_number — Numéro d’identification TVA (Umsatzsteuer-ID), 9 chiffres sans le préfixe DE
  • fiscalization.tax_id_number — Numéro d’identification fiscale personnel (Steuer-ID), 11 chiffres. Obligatoire pour les Taxpayers de type INDIVIDUAL.
  • name — Dénomination légale enregistrée et nom commercial de l’entreprise ou de la personne physique
  • address — Adresse légale enregistrée de l’entreprise ou de la personne physique

Envoi de factures électroniques : exigences relatives au destinataire

Section intitulée « Envoi de factures électroniques : exigences relatives au destinataire »

Pour envoyer une facture électronique, vous indiquez son destinataire et son mode d’acheminement directement sur l’enregistrement de la facture. Lorsque vous créez la facture (TRANSACTION::INVOICE) avec createRecord, ajoutez le destinataire à son tableau recipients.

Comme l’explique l’Intégration générale étape par étape, chaque destinataire doit être de type BUSINESS et son bloc invoicing doit être renseigné. Au-delà des informations standard de toute facture électronique (nom, adresse, identification fiscale du destinataire, lignes de facture, etc.), l’Allemagne ajoute le canal de transmission sur le destinataire :

  • recipients[].type = BUSINESS
  • recipients[].identification.type = VAT — la facture électronique allemande identifie l’acheteur par son numéro de TVA
  • recipients[].address.country = DE — les destinataires doivent se trouver en Allemagne
  • recipients[].invoicing.type = EMAIL ou PEPPOL — le canal de transmission
  • recipients[].invoicing.email — (EMAIL uniquement) l’adresse e-mail du destinataire
  • recipients[].invoicing.format — (EMAIL uniquement, facultatif) le format du document
  • recipients[].invoicing.identifier — (PEPPOL uniquement) le PEPPOL Network Identifier du destinataire, sous la forme <code de schéma>:<valeur> — généralement 9930:<numéro de TVA> pour une entreprise allemande
invoicing.typeÉgalement requisMode de transmission par fiskaly
EMAILinvoicing.emailPar e-mail à cette adresse, au format ZUGFeRD ou XRechnung selon invoicing.format.
PEPPOLinvoicing.identifierVers le point d’accès PEPPOL du destinataire, au format XRechnung — voir la limitation XRechnung.

Vous choisissez le canal par facture et non une fois pour toutes par destinataire — la même entreprise peut recevoir une facture par e-mail et la suivante via PEPPOL.

Chaque entrée de payments est soit un paiement déjà reçu (CASH, CARD, ONLINE, VOUCHER, OTHER), soit le montant restant dû (OUTSTANDING). Les paiements reçus apparaissent sur la facture comme montant déjà payé, et la date de l’entrée OUTSTANDING devient la date d’échéance de la facture. Pour une facture entièrement payée, omettez OUTSTANDING.

Chaque paiement nécessite type et details.amount. Certains types en nécessitent davantage :

typeÉgalement obligatoire
CASH—
CARDnumber (numéro de carte masqué, par exemple ************1234) et kind
ONLINEname, par exemple le prestataire de paiement
VOUCHERnumber et kind
OTHER— (name est facultatif)
OUTSTANDINGconcept (GOOD, SERVICE ou INVOICE) et details.date, la date d’échéance

concept n’est accepté que sur OUTSTANDING. Sur tout autre type de paiement, la requête est rejetée avec 400.

En Allemagne, l’inscription au réseau PEPPOL est facultative : vous choisissez de l’activer System par System.

Renseignez-la sur le System E_INVOICE_SERVICE avec createSystem :

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

Ou ajoutez-la à un System existant avec updateSystem :

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

Ce qui découle de ce choix :

  • registrations omis — le System n’envoie que par e-mail. Aucun Proof of Ownership n’est nécessaire et le System passe directement en mode OPERATIVE.
  • registrations contient PEPPOL — un Proof of Ownership est requis. Lors de la mise en service, le state du System devient COMMISSIONED mais son mode devient DEGRADED, et le System porte une entrée de journal signalant l’absence du Proof of Ownership.

Pour faire passer le System en mode OPERATIVE, téléversez le Proof of Ownership comme décrit à l’étape 11 du guide d’intégration général. La vérification prend jusqu’à 72 heures ; une fois terminée, le System change d’état automatiquement et l’entrée de journal est supprimée. Le contenu attendu du document est décrit dans la section Proof of Ownership.

Sur le destinataire de votre requête createRecord, définissez :

  • recipients[].invoicing.type = PEPPOL
  • recipients[].invoicing.identifier — le PEPPOL Network Identifier du destinataire

Deux conditions préalables doivent être remplies : votre System E_INVOICE_SERVICE doit être inscrit au réseau PEPPOL (voir Inscription PEPPOL) et vous devez disposer du PEPPOL Network Identifier du destinataire. fiskaly se charge du schéma de l’identifiant.

Les factures transmises ainsi sont générées au format XRechnung. recipients[].invoicing.format n’intervient pas ici : sur ce canal, le format n’est pas sélectionnable.

Lorsque le canal est EMAIL, vous décidez quel format de document fiskaly génère. Définissez-le sur le même destinataire dans votre requête createRecord, via recipients[].invoicing.format :

ValeurFormat
ZUGFERD_V2 (par défaut)ZUGFeRD — un document hybride : un PDF/A-3 lisible par une personne, avec le XML structuré intégré à l’intérieur.
XRECHNUNG_V3XRechnung — une facture XML purement structurée, sans couche PDF.

Le champ est facultatif : si vous l’omettez, fiskaly génère ZUGFERD_V2. Les deux formats sont conformes à la EN 16931.

fiskaly envoie l’e-mail au nom du vendeur, depuis no-reply.e-invoicing@fiskaly.com. L’objet est « Your Invoice » et le texte est en anglais. L’e-mail nomme le vendeur et renvoie le destinataire vers celui-ci pour toute question sur la facture.

L’e-mail est envoyé juste après la création de la facture (le traitement est asynchrone, voir plus bas). Il n’existe pas de déclencheur d’envoi distinct : pour différer l’envoi, différez l’appel à createRecord.

La facture est jointe sous le nom invoice_<id>.xml (XRechnung) ou invoice_<id>.pdf (ZUGFeRD), où <id> est l’ID du Record E_INVOICE::TRANSMISSION.

Toute facture envoyée via PEPPOL est générée en XRechnung, tout comme toute facture par e-mail avec XRECHNUNG_V3. XRechnung exige deux champs que ZUGFeRD n’exige pas :

ChampRègle XRechnungValeur
document.references.buyerBR-DE-15De 1 à 32 caractères : lettres, chiffres, espaces et . - _ /. Obligatoire sur chaque facture, pas seulement pour les acheteurs publics.
seller.phoneBR-DE-6Numéro de téléphone de contact du vendeur au format E.164, par exemple +49301234567.

Chaque facture nécessite deux appels à createRecord, comme décrit à l’étape 12 du guide d’intégration général : une INTENTION, puis une TRANSACTION::INVOICE qui y fait référence. Envoyez chaque appel avec une nouvelle clé d’idempotence. Remplacez les ID et les valeurs par les vôtres.

Intention
{
"content": {
"type": "INTENTION",
"system": {
"id": "<E_INVOICE_SERVICE System ID>"
},
"operation": {
"type": "TRANSACTION"
}
}
}
Facture par e-mail en 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"
}
}
}
}
}
Facture par e-mail en 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"
}
}
}
}
}
Facture via 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’envoi est asynchrone. createRecord répond dès que la TRANSACTION::INVOICE est acceptée, puis la facture et sa transmission sont traitées. Il n’existe pas de webhooks pour cela : interrogez donc le statut avec retrieveRecord. Chaque Record indique sa progression dans mode : PROCESSING tant que le traitement est en cours, FINISHED une fois terminé. state contient alors le résultat.

Une fois la TRANSACTION::INVOICE en FINISHED, COMPLETED ne signifie pas à lui seul que la facture a été envoyée. Vérifiez que ses logs ne contiennent aucune entrée avec "severity": "ERROR" et que used_in est présent.

used_in.id est le Record E_INVOICE::TRANSMISSION. Interrogez-le jusqu’à ce que son mode soit FINISHED. Son state indique le résultat :

  • COMPLETED — la facture a été remise pour distribution.
  • FAILED — la facture n’a pas été distribuée. Le motif figure dans les logs du Record.

Pour l’e-mail, COMPLETED signifie que la facture a été remise à la passerelle e-mail de fiskaly. La distribution dans la boîte de réception du destinataire ne peut pas être confirmée, et les rebonds ultérieurs ne sont pas signalés sur le Record.

Si la passerelle e-mail rejette un e-mail de façon définitive, la transmission se termine immédiatement en FAILED. Les erreurs temporaires font l’objet de nouvelles tentatives en arrière-plan : la transmission peut donc rester en PROCESSING pendant un certain temps. Elle ne se termine en FAILED qu’une fois toutes les tentatives épuisées.

Une facture en échec n’a pas été émise. Envoyez-la à nouveau sous la forme d’une nouvelle TRANSACTION::INVOICE (nouvelle INTENTION, nouvelle clé d’idempotence) avec le même numéro de facture, et non comme CORRECTION. Pour corriger une facture qui est parvenue à l’acheteur, émettez une note de crédit.

Pour plus de détails, consultez l’article d’assistance How to detect and handle failed invoices (en anglais).

Ce que vous voyezCause
Log ERROR either party.telephones or party.people[0].telephones is required (BR-DE-6), rien n’est envoyéXRechnung sans seller.phone
Log ERROR sur la TRANSACTION::INVOICE, pas de used_in, rien n’est envoyéXRechnung sans document.references.buyer
400 sur createRecorddocument.references.buyer vide ou autre erreur de schéma
receiver does not support document typeDestinataire PEPPOL non enregistré pour XRechnung — voir Envoi via PEPPOL
422 Unprocessable Content lors de la mise en serviceTaxpayer sans vat_id_number

Appelez retrieveRecord sur la E_INVOICE::TRANSMISSION (used_in.id) avec compliance-artifact pour obtenir la facture électronique générée. La réponse est une enveloppe JSON. Pour XRechnung, content.compliance.artifact vaut :

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

Pour ZUGFeRD, content.compliance.artifact est le PDF/A-3 avec le XML intégré :

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

Le guide Note de crédit explique quand et comment émettre une note de crédit. Cette section ne couvre que ce qui est propre à l’Allemagne.

Une note de crédit est un document complet à part entière et ne reprend aucune donnée de la facture d’origine. Envoyez le même destinataire, canal et format que sur la facture. Pour XRechnung, envoyez aussi à nouveau seller.phone, seller.email et document.references.buyer. Sans eux, rien n’est envoyé et le record reçoit un log ERROR (BR-DE-6, BR-DE-7, BR-DE-15).

Paiements sur les notes de crédit et les factures d’annulation

Section intitulée « Paiements sur les notes de crédit et les factures d’annulation »

Sur une note de crédit, et sur une facture qui annule une note de crédit (facture d’annulation), payments décrit ce qui reste ouvert sur ce document :

  • Partie réglée : type: OTHER avec details.amount et details.currency, sans date.
  • Montant restant à payer : type: OUTSTANDING avec concept, details.amount, details.currency et details.date, la date d’échéance (obligatoire).

La facture électronique présente la partie réglée comme déjà payée et le reste comme payable à la date d’échéance. Les deux types peuvent être combinés, sur les notes de crédit comme sur les factures.

DocumentSituationpayments
Note de créditRemboursement déjà versé au clientOTHER = montant crédité
Note de créditRemboursement encore à verserOUTSTANDING avec date d’échéance
Note de créditRemboursement partielOTHER (partie remboursée) + OUTSTANDING (reste)
Facture d’annulationRemboursement entièrement versé, le client le rembourseOUTSTANDING = montant total
Facture d’annulationRemboursement versé en partie (p. ex. 50,00 sur 119,00)OTHER 69.00 + OUTSTANDING 50.00
Facture d’annulationRien n’a été versé, les documents s’annulentOTHER = montant total
Exemple — facture d’annulation, remboursement versé en partie
"payments": [
{
"type": "OTHER",
"details": {
"amount": "69.00",
"currency": "EUR"
}
},
{
"type": "OUTSTANDING",
"concept": "SERVICE",
"details": {
"amount": "50.00",
"currency": "EUR",
"date": "2026-11-30"
}
}
]

La réception des factures entrantes passe par PEPPOL et dépend donc de la même inscription PEPPOL que la transmission via PEPPOL — Proof of Ownership validé inclus. Un Taxpayer qui envoie uniquement par e-mail ne peut pas recevoir.

Lorsque vous inscrivez un Taxpayer allemand sur PEPPOL, fiskaly l’inscrit par défaut à l’envoi et à la réception. Les factures entrantes adressées au PEPPOL Identifier du System lui sont rattachées, et fiskaly crée pour chacune un Record de type E_INVOICE::RECEPTION.

Appelez retrieveSystem pour lire compliance.state :

  • TRANSMISSION_RECEPTION — le System peut envoyer et recevoir.
  • TRANSMISSION_ONLY — le System ne peut qu’envoyer.

Chaque facture adressée à votre Taxpayer est reçue et stockée automatiquement sous forme de Record — il n’y a pas de webhook, vous interrogez donc l’API pour détecter les nouvelles :

  1. Appelez listRecords et filtrez sur E_INVOICE::RECEPTION.
  2. Pour chaque nouveau Record, appelez retrieveRecord avec compliance-artifact pour obtenir le XML signé.

listRecords renvoie les Records les plus récents (limit vaut 10 par défaut, du plus récent au plus ancien) : suivez donc ceux que vous avez déjà traités.

Vous pouvez récupérer la facture électronique générée d’une facture envoyée et le XML d’une facture reçue.