In Italien unterstützt fiskaly den Versand von B2B- und B2C-E-Rechnungen sowie den Empfang von B2B-E-Rechnungen. Derzeit unterstützen wir die Standardrechnung (Fattura, TD01) und die Gutschrift (Nota di credito, TD04). Der Dokumenttyp wird aus der Unified-API-Operation abgeleitet und nicht direkt gesetzt. Anzahlungsrechnungen (TD02) sowie nachträgliche Rechnungen (TD24, TD25) werden derzeit nicht ausgestellt. Die Unterstützung für die vereinfachte Rechnung (Fattura semplificata, TD07) folgt in Kürze.
Die elektronische Rechnungsstellung ist verpflichtend und wird von der Agenzia delle Entrate (Finanzverwaltung) geregelt. Alle B2B-Rechnungen müssen über das SDI (Sistema di Interscambio — Austauschsystem) im XML-Format FatturaPA (elektronische Rechnung) ausgetauscht werden und sind seit Januar 2019 gesetzlich vorgeschrieben. Rechnungen müssen zudem durch zertifizierte Archivierung (conservazione a norma) langfristig aufbewahrt werden.
Diese Seite beschreibt die italienspezifischen Anforderungen für das Onboarding eines Taxpayers zur elektronischen Rechnungsstellung; sie ergänzen die allgemeine Schritt-für-Schritt-Integration.
fiskaly wickelt beide Richtungen des SDI-Austauschs ab, wobei beide unterschiedlich funktionieren:
Versand — B2B und B2C
fiskaly erzeugt die FatturaPA und übermittelt sie an das SDI, das sie validiert und asynchron an den Empfänger weiterleitet. Eine Netzwerkregistrierung ist nicht erforderlich. Geschäfts- und Verbraucherempfänger erfordern jeweils unterschiedliche Felder.
Empfang — nur B2B
Optional und pro Taxpayer aktivierbar. Erfordert eine einmalige Registrierung, um Rechnungen Ihrer Lieferanten zu empfangen.
Über beide Richtungen hinaus wird jede Rechnung, die Sie senden und empfangen, automatisch für Sie archiviert. Das bedeutet zertifizierte Langzeitaufbewahrung (conservazione a norma) für die gesetzlich vorgeschriebenen 10 Jahre — ohne Einrichtung auf Ihrer Seite.
Wenn Sie bereits eine SIGN IT-Integration haben, fangen Sie nicht bei null an — Sie erweitern Ihren bestehenden Taxpayer um die zusätzlichen Registrierungsdaten und nehmen ein E_INVOICE_SERVICE System in Betrieb. Siehe E-INVOICE IT für SIGN IT-Kunden für alle Schritte.
Voraussetzungen
Abschnitt betitelt „Voraussetzungen“Diese gelten für jeden Taxpayer, den Sie für die elektronische Rechnungsstellung in Italien onboarden — egal, ob Sie senden, empfangen oder beides. Stellen Sie sicher, dass Sie die folgenden Taxpayer-Informationen bereithalten, bevor Sie fortfahren.
E-INVOICE IT unterstützt derzeit Taxpayer vom Typ COMPANY. Das Onboarding eines INDIVIDUAL-Taxpayers — eines Freiberuflers oder Einzelunternehmers, der unter seinem eigenen Codice fiscale statt einer Unternehmens-USt-IdNr. ausstellt — folgt in Kürze.
Italienspezifische Registrierungsdaten — übermittelt unter content.fiscalization.registration:
company_id— Numero Registro Imprese (Handelsregisternummer)office— Provinzkürzel der Camera di Commercio, die die REA-Nummer ausgestellt hat, z. B.MI,RMentry— REA-Nummer (6 oder 7 Ziffern)legal_form— Rechtsform des Unternehmens (z. B.LIMITED_LIABILITY_COMPANY,JOINT_STOCK_COMPANY)capital— eingetragenes Stammkapital in EUR (z. B."10000.00")shareholder_status—SOLE_SHAREHOLDERoderMULTIPLE_SHAREHOLDERSliquidation_status—IN_LIQUIDATIONoderNOT_IN_LIQUIDATIONtax_regime— optional,ORDINARY(Standard) oderFLAT_RATE_SCHEME(Regime Forfettario)
Standard-Taxpayer-Felder — Teil des Taxpayers selbst (gemeinsam mit SIGN IT genutzt, falls verwendet):
content.name— eingetragener rechtlicher Name des Unternehmens oder der Personcontent.address— eingetragene rechtliche Adressecontent.address.region— Provincia (Provinzkürzel, z. B.MI,RM); verpflichtend am Taxpayer und wird bei der Inbetriebnahme validiert
Für die elektronische Rechnungsstellung in Italien sind content.fiscalization.registration und content.address.region (Provincia) erforderliche Felder des Taxpayers. Sie werden bei der Inbetriebnahme des E_INVOICE_SERVICE Systems validiert — fehlen sie, schlägt die Inbetriebnahme fehl. Stellen Sie sicher, dass beide Felder vorab am Taxpayer gesetzt oder aktualisiert werden.
E-Rechnungen senden: Anforderungen an den Empfänger
Abschnitt betitelt „E-Rechnungen senden: Anforderungen an den Empfänger“Um eine E-Rechnung zu senden, geben Sie deren Empfänger und dessen Routing-Daten an — direkt im Rechnungs-Record. Wenn Sie die Rechnung (TRANSACTION::INVOICE) mit createRecord erstellen, fügen Sie den Empfänger dem recipients-Array hinzu. Welche Felder Sie setzen, hängt davon ab, wen Sie in Rechnung stellen:
Geschäftsempfänger (B2B)
Geroutet über den SDI-Empfängercode oder per PEC, wenn kein SDI-Postfach vorhanden ist.
Verbraucherempfänger (B2C)
In Italien ansässige Verbraucher werden über den Codice fiscale identifiziert, Verbraucher im Ausland über eine ausländische Kennung.
Jeder Empfänger trägt invoicing.type = SDI. Was sich zwischen den drei Fällen unterscheidet, sind die Identifikation, der Empfängercode und die Frage, ob eine PEC im Spiel ist:
| Unternehmen | Verbraucher in Italien | Verbraucher im Ausland | |
|---|---|---|---|
type | BUSINESS | CONSUMER | CONSUMER |
identification | VAT — validiert | TAX — Codice fiscale, validiert | beliebiger Typ; nicht validiert |
invoicing.destination_code | der 7-stellige Code des Empfängers, oder "0000000", oder "XXXXXXX" | "0000000" | "XXXXXXX" |
invoicing.pec | erforderlich bei "0000000" | optional | nicht verwendet |
address.region | erforderlich, wenn die Adresse in Italien liegt | erforderlich | nicht erforderlich |
name | Firmenname | gender, forename, surname | gender, forename, surname |
- Den 7-stelligen Code, den der Empfänger Ihnen genannt hat (z. B.
ABC1234) — nur Großbuchstaben und Ziffern. "0000000"— der Empfänger hat kein SDI-Postfach: jeder Verbraucher sowie Unternehmen, die per PEC empfangen."XXXXXXX"— der Empfänger befindet sich im Ausland.
Geschäftsempfänger (B2B)
Abschnitt betitelt „Geschäftsempfänger (B2B)“Jeder Geschäftsempfänger ist vom Typ BUSINESS mit befülltem invoicing-Block, wie in der allgemeinen Schritt-für-Schritt-Integration beschrieben. Über die Standarddaten hinaus, die jede E-Rechnung erfordert (Empfängername, Adresse, Steueridentifikation, Rechnungspositionen usw.), kommen in Italien die oben genannten SDI-Routing-Felder hinzu.
Welche Werte destination_code und pec annehmen, hängt vom Empfänger ab:
| Szenario | destination_code | pec |
|---|---|---|
| Empfänger hat ein registriertes SDI-Postfach | sein 7-stelliger Code (z. B. ABC1234) | optional |
| Empfänger ist nicht beim SDI registriert | "0000000" | erforderlich |
| Empfänger befindet sich außerhalb Italiens | "XXXXXXX" | nicht verwendet |
Eine pec ist eine Posta Elettronica Certificata-Adresse — Italiens zertifizierte E-Mail. Das SDI prüft die Domain, ein gewöhnliches Postfach wird daher abgelehnt.
"0000000" bedeutet Zustellung per PEC; deshalb ist die pec bei einem Geschäftsempfänger in diesem Fall zwingend.
recipients[].address.region (die Provincia des Empfängers) ist im gemeinsamen Unified-API-Schema nicht als Pflichtfeld gekennzeichnet, Italien verlangt sie jedoch, sobald die Adresse in Italien liegt. Sie wird nicht bei der Erstellung des Records geprüft: createRecord ist erfolgreich und die Übermittlung schlägt erst später fehl, wodurch die gesamte Kette auf FAILED geht. Setzen Sie sie daher von vornherein, statt es asynchron zu bemerken.
Verbraucherempfänger (B2C)
Abschnitt betitelt „Verbraucherempfänger (B2C)“Wenn Ihr Kunde eine Privatperson und kein Unternehmen ist, setzen Sie recipients[].type auf CONSUMER. Die Rechnung läuft wie eine B2B-Rechnung als FatturaPA-Dokument (TD01) über das SDI.
Verbraucher haben kein SDI-Postfach, daher funktioniert das Routing anders. Wie Sie den Verbraucher identifizieren, hängt davon ab, ob er in Italien ansässig ist:
- In Italien ansässig — identifiziert über den Codice fiscale, geroutet mit dem Empfängercode
"0000000". - Außerhalb Italiens — es existiert kein Codice fiscale, daher tritt eine ausländische Kennung an dessen Stelle und die Rechnung wird mit
"XXXXXXX"geroutet.
Über die Felder in der Tabelle oben hinaus trägt ein Verbraucherempfänger stets name.gender, name.forename und name.surname sowie die Adresse des Verbrauchers.
In Italien ansässige Verbraucher
Abschnitt betitelt „In Italien ansässige Verbraucher“Senden Sie den Codice fiscale als TAX-Identifikation (16 Zeichen), die Wohnadresse einschließlich region (Provincia) und den Empfängercode "0000000". Eine pec kann ergänzt werden, ist aber nicht erforderlich.
Bei einem in Italien ansässigen Verbraucher ist eine Identifikation zwingend, sie muss vom Typ TAX sein, und der Codice fiscale wird bereits bei der Erstellung des Records geprüft — fehlt er oder ist er formal fehlerhaft, wird die Anfrage dort abgelehnt und es wird keine Rechnung erstellt. Das SDI validiert ihn erneut gegen das Steuerregister, sodass ein formal korrekter, aber unbekannter Code in dieser Phase abgelehnt wird.
Verbraucher außerhalb Italiens
Abschnitt betitelt „Verbraucher außerhalb Italiens“Ein nicht in Italien ansässiger Verbraucher hat keinen Codice fiscale. Senden Sie an dessen Stelle eine ausländische Kennung — in der Regel eine ausländische Steuer- oder USt-IdNr.
| Feld | Wert |
|---|---|
recipients[].identification | erforderlich; VAT, TAX, PASSPORT, DOCUMENT oder OTHER — je nachdem, welche Kennung Ihnen vorliegt |
recipients[].address.country | das Land des Verbrauchers als ISO-3166-1-alpha-2-Code |
recipients[].address.code | "00000" — FatturaPA akzeptiert nur eine 5-stellige Postleitzahl |
recipients[].invoicing.destination_code | "XXXXXXX" |
Die Kennung wird dem SDI als IdCodice übermittelt; weder fiskaly noch das SDI prüfen sie auf Gültigkeit, sobald das Adressland nicht Italien ist. Für eine nicht italienische Adresse ist region nicht erforderlich.
"XXXXXXX" signalisiert dem SDI, dass die Freigabe angefordert wird, eine Zustellung über das Übermittlungssystem jedoch nicht greift — das SDI hat keinen Kanal, um einen Empfänger im Ausland zu erreichen. Senden Sie dem Verbraucher seine Rechnungsausfertigung (PDF o. Ä.) separat außerhalb des SDI zu.
gender wird von der Unified API verlangt, nicht vom SDI — die FatturaPA-Rechnung enthält kein solches Feld. Senden Sie DIVERSE, wenn Sie die Angabe nicht haben.
Bei einem in Italien ansässigen Verbraucher legt das SDI die Originalrechnung in dessen geschützten Bereich im AdE-Portal ab (Fatture e Corrispettivi).
Wenn der Kunde eine Rechnung statt eines Belegs benötigt
Abschnitt betitelt „Wenn der Kunde eine Rechnung statt eines Belegs benötigt“Italien meldet die beiden Dokumente über getrennte Kanäle — den Beleg über die corrispettivi, die Rechnung über das SDI — und nichts verknüpft sie automatisch.
Erfassen Sie den Wunsch, bevor der Verkauf abgeschlossen ist. Teilt Ihnen der Kunde mit, dass er eine Fattura benötigt, stellen Sie eine TRANSACTION::INVOICE anstelle einer TRANSACTION::RECEIPT aus. Das ist der Ablauf, den fiskaly heute durchgängig unterstützt — unabhängig davon, ob der Kunde vor oder während des Verkaufs danach fragt.
Wir arbeiten an einem unterstützten Weg, der einen fiskalisierten Beleg und eine E-Rechnung miteinander verknüpft, sodass ein Umsatz genau eine Rechnung und einen Prüfpfad trägt. Bis dahin erfassen Sie den Rechnungswunsch, bevor die Transaktion abgeschlossen wird.
Umgang mit SDI-Antworten
Abschnitt betitelt „Umgang mit SDI-Antworten“Im Gegensatz zu einem synchronen API-Aufruf erfolgt das SDI-Ergebnis asynchron. Nachdem Sie die Rechnung (TRANSACTION::INVOICE) mit createRecord erstellt haben, fragen Sie den E_INVOICE::TRANSMISSION Record ab, um zu erfahren, ob das SDI sie angenommen hat. Es gibt keinen Webhook.
SDI-Ergebnisse treffen in der Regel innerhalb weniger Minuten ein. Die SDI-Spezifikation lässt jedoch bis zu 48 Stunden zu.
Alle drei Records erreichen ihren Endzustand gemeinsam:
| Record | Endzustand |
|---|---|
E_INVOICE::TRANSMISSION | COMPLETED oder FAILED, mode=FINISHED |
TRANSACTION::INVOICE | COMPLETED oder FAILED, mode=FINISHED |
INTENTION::TRANSACTION | COMPLETED oder FAILED, mode=FINISHED |
Im Fehlerfall ist der SDI-Ablehnungsgrund im Feld logs[].message aller drei Records verfügbar. Weitere Details finden Sie unter How to check the status of an e-invoice auf unserer Support-Seite.
Das Ergebnis lesen
Abschnitt betitelt „Das Ergebnis lesen“state sagt Ihnen, wo eine Rechnung steht, logs[] sagt Ihnen, warum. Lesen Sie beide zusammen und handeln Sie entsprechend:
| Was Sie sehen | Was es bedeutet | Was zu tun ist |
|---|---|---|
4xx von createRecord, kein Record erstellt | Das Payload wurde abgelehnt. Es wurde nichts erstellt und nichts gesendet. | Korrigieren Sie das Payload und versuchen Sie es erneut mit demselben INTENTION::TRANSACTION. |
state=ACCEPTED | Noch in Bearbeitung. | Fragen Sie den Record E_INVOICE::TRANSMISSION ab. Ergebnisse liegen in der Regel innerhalb von Minuten vor. |
state=FAILED | Abgeschlossen, und die Rechnung ist rechtlich nicht gültig. Sie wurde entweder auf dem Weg zum SDI gestoppt oder vom SDI mit NS abgelehnt. | Lesen Sie logs[].message für den Grund, korrigieren Sie die Daten und starten Sie eine neue Kette — siehe Fehler und erneute Übermittlung. |
state=COMPLETED mit einem ERROR-Eintrag in logs[] | Auf dem Weg ist etwas schiefgegangen, ohne die Rechnung zu stoppen. | Lesen Sie logs[].message, bevor Sie die Rechnung als gesendet betrachten. |
state=COMPLETED, keine ERROR-Einträge | Das SDI hat die Rechnung angenommen. | Nichts weiter. |
Jeder Eintrag in logs[] ist entweder ein ERROR oder ein WARNING. Ein WARNING ist informativ und blockiert eine Rechnung niemals — Sie erhalten eines, wenn etwas in Ihrem Payload angepasst wurde oder nicht aufging, zum Beispiel wenn Sie mehrere offene Zahlungen gesendet haben und nur die erste verwendet wurde, oder wenn die Umsatzsteuersummen in Ihrem Payload von den aus den Rechnungspositionen berechneten Summen abweichen.
Es bedeutet nicht, dass der Empfänger sie erhalten hat. Das SDI meldet sowohl die Zustellung (RC) als auch die Nichtzustellung (MC, die dennoch rechtlich gültig ist) als Erfolg, und die API unterscheidet die beiden Fälle nicht.
Wo Validierungsfehler sichtbar werden
Abschnitt betitelt „Wo Validierungsfehler sichtbar werden“Nicht jede Ablehnung sieht auch wie eine Ablehnung aus. Rechnungsdaten werden an drei verschiedenen Stellen geprüft, und jede schlägt in einer anderen Form fehl:
| Wo es fehlschlägt | Beispiel | Was Sie sehen |
|---|---|---|
| Schema-Beschränkungen | identification.number außerhalb von AlphaNumerical28; document.number außerhalb von ^[0-9A-Z_/\-\.]{1,20}$ | 400 von createRecord. Es wird nichts erstellt. |
| Feldvalidierung | Ein codice fiscale mit falschem Format oder falscher Prüfziffer | createRecord gelingt. Der Record schließt mit COMPLETED / FINISHED ab, aber content.used_in fehlt und es wird nichts übermittelt. Der Grund erscheint ausschließlich als Eintrag in content.logs mit der Schwere ERROR. |
| Nachgelagert | Ein fehlendes recipients[].address.region | createRecord gelingt, und die Kette geht später auf FAILED. |
Die mittlere Zeile ist die Falle für Integratoren: Ein Record mit COMPLETED / FINISHED und ohne dahinterliegende Rechnung sieht genauso aus wie ein erfolgreicher, wenn Sie nur state lesen und dort aufhören. Lesen Sie immer content.logs auf ERROR-Einträge und prüfen Sie, dass content.used_in vorhanden ist, bevor Sie eine Rechnung als ausgestellt betrachten.
Fehler und erneute Übermittlung
Abschnitt betitelt „Fehler und erneute Übermittlung“Wenn das SDI NS (Notifica di Scarto) zurückgibt, ist die Rechnung rechtlich nicht existent:
- Lesen Sie
logs[].messagean einem der drei Records, um den SDI-Ablehnungsgrund zu erhalten - Erstellen Sie eine neue
INTENTION::TRANSACTIONund eine neueTRANSACTION::INVOICEmit den korrigierten Daten - Dieselbe
document.numberdarf innerhalb von 5 Tagen nach derNS-Ablehnung erneut verwendet werden - Die fehlgeschlagene Kette bleibt dauerhaft
FAILED— sie wird zu Prüfzwecken aufbewahrt
Jede erneute Übermittlung startet eine neue Transaktionskette — UAPI behandelt sie als völlig neue Übermittlung.
E-Rechnungen empfangen
Abschnitt betitelt „E-Rechnungen empfangen“Ein E_INVOICE_SERVICE System kann E-Rechnungen sowohl senden als auch empfangen. Der Empfang ist optional — ein Taxpayer, der nur sendet, kann diesen Abschnitt überspringen.
Dabei sind zwei getrennte, voneinander unabhängige Dinge beteiligt:
- Empfangsbereitschaft — fiskaly richtet dies automatisch ein, wenn Sie das System in Betrieb nehmen.
- Registrierung des SDI-Empfängercodes (manuell, von Ihnen) — hinterlegen Sie in Ihrem Portal der Agenzia delle Entrate (AdE) den SDI-Empfängercode
JKKZDGRvon fiskaly als SDI-Zieladresse Ihres Unternehmens, damit das SDI Ihre eingehenden Rechnungen an fiskaly weiterleitet.
Die Antwort auf die Inbetriebnahme zeigt compliance.state als TRANSMISSION_ONLY. Anschließend wechselt er automatisch zu TRANSMISSION_RECEPTION, sobald die Registrierung des Taxpayers abgeschlossen ist — was normalerweise geschieht, unabhängig davon, ob Sie die AdE-Registrierung durchgeführt haben oder den Empfang planen.
TRANSMISSION_RECEPTION bedeutet, dass das System empfangen kann, aber nicht, dass eingehende Rechnungen tatsächlich an den Taxpayer zugestellt werden. Diese Zustellung erfordert die AdE-Registrierung: Solange sie nicht vorliegt, empfängt der Taxpayer keine Rechnungen, selbst wenn das System bereit ist. Sie können die AdE-Registrierung jederzeit durchführen — zum Beispiel, um den Empfang für einen Taxpayer zu aktivieren, der zuvor nur für den Versand eingerichtet war.
Rufen Sie jederzeit retrieveSystem auf, um den aktuellen compliance.state zu lesen, der nur die Bereitschaft widerspiegelt — nicht die AdE-Registrierung:
TRANSMISSION_RECEPTION— fiskaly hat das System für den Empfang eingerichtet.TRANSMISSION_ONLY— diese Einrichtung ist nicht abgeschlossen.
Wenn retrieveSystem nach der Inbetriebnahme weiterhin compliance.state = TRANSMISSION_ONLY zurückgibt, wurde die Registrierung des Taxpayers nicht abgeschlossen. Behandeln Sie dies als hängengebliebenen Übergang und wenden Sie sich mit der USt-IdNr. des Taxpayers unter dev-support@fiskaly.com an das fiskaly-Support-Team, damit wir dies untersuchen können.
Für das Routing ist nichts weiter einzurichten: fiskaly ordnet jede eingehende Rechnung automatisch dem richtigen Taxpayer anhand seiner Steuer-ID zu — weshalb jede Steuer-ID zu genau einem registrierten Taxpayer gehören muss. Sie müssen keinen separaten Routing-Code konfigurieren oder speichern.
Wenn eine Rechnung eingeht
Abschnitt betitelt „Wenn eine Rechnung eingeht“Wenn Ihnen über das SDI eine Rechnung zugesendet wird, empfängt fiskaly sie automatisch:
- die eingehende Zustellung wird automatisch auf unserer Seite verarbeitet
- ein Reception Record wird für die Rechnung erstellt
- das signierte XML, das PDF und die Metadaten werden am Record gespeichert
- doppelte Zustellungen werden dedupliziert
In der Praxis ist die erste Rechnung, die Sie auf diesem Weg erreicht, zugleich Ihre Bestätigung, dass der Empfang korrekt eingerichtet ist.
Empfangene Rechnungen abrufen
Abschnitt betitelt „Empfangene Rechnungen abrufen“Jede an Ihren Taxpayer adressierte Rechnung wird automatisch empfangen, validiert und als Record gespeichert — es gibt keinen Webhook, Sie fragen neue Rechnungen daher selbst ab:
- Rufen Sie
listRecordsauf und filtern Sie nachE_INVOICE::RECEPTION. - Rufen Sie für jeden neuen Record
retrieveRecordmitcompliance-artifactauf, um das signierte XML zu erhalten.
listRecords gibt die neuesten Records zurück (limit ist standardmäßig 10, neueste zuerst) — verfolgen Sie daher, welche Sie bereits verarbeitet haben.
Wenn Sie E-INVOICE IT ohne SIGN IT integrieren, wenden Sie sich bitte unter dev-support@fiskaly.com an das fiskaly-Support-Team — wir begleiten Sie bei der Taxpayer-Einrichtung für Ihren konkreten Fall.
Archivierung
Abschnitt betitelt „Archivierung“Das italienische Recht verlangt, dass E-Rechnungen durch zertifizierte digitale Archivierung (conservazione a norma) langfristig aufbewahrt werden: Sie müssen mindestens 10 Jahre aufbewahrt und so gespeichert werden, dass sie unveränderlich, authentisch und leicht abrufbar bleiben, mit digitalen Signaturen und Zeitstempeln (marca temporale). Eine eigene Kopie des XML aufzubewahren reicht nicht aus — fiskaly übernimmt dies für Sie.
Für Italien erfolgt die Archivierung automatisch und immer: Jede Rechnung, die Sie senden, und jede Rechnung, die Sie über das SDI empfangen, wird rechtskonform aufbewahrt, ohne zusätzliche Einrichtung oder API-Aufruf auf Ihrer Seite. Sie stützt sich lediglich auf die italienische Steuer-ID des Taxpayers, die bereits Teil des Onboardings ist. Jede aufbewahrte Rechnung erhält einen Aufbewahrungsnachweis als Beleg der conservazione a norma. Die Aufbewahrung ist ereignisgesteuert und in der Regel innerhalb von Sekunden abgeschlossen; die Ausstellung des Nachweises selbst kann bis zu etwa sechs Minuten dauern, danach hängt fiskaly ihn automatisch an — auf Ihrer Seite ist nichts erforderlich.
Rufen Sie die Artefakte einer E-Rechnung aus ihrem Record mit retrieveRecord ab und wählen Sie das Artefakt über einen Query-Parameter aus:
compliance-artifact— das rechtlich maßgebliche Dokument. Für Italien das SDI-validierte FatturaPA-XML.archive-artifact— der Aufbewahrungsnachweis, der die rechtskonforme Aufbewahrung (conservazione a norma) bestätigt, zurückgegeben als signiertes XML.
Das Antwortformat wählen
Abschnitt betitelt „Das Antwortformat wählen“Beide Artefakte werten den Request-Header Accept aus, der die Form der Antwort bestimmt:
Accept | Was Sie erhalten |
|---|---|
application/xml | Das Artefakt selbst — das FatturaPA-XML bzw. das XML des Aufbewahrungsnachweises. |
application/json | Den Record als JSON, mit dem Artefakt Base64-codiert im üblichen content-Feld. |
Das RecordResponse der Spezifikation deklariert nur application/json, weshalb die XML-Variante in der Referenz nicht auftaucht. Sie wird dennoch unterstützt und wird auch von der Postman-Collection verwendet.
Wann Artefakte verfügbar werden
Abschnitt betitelt „Wann Artefakte verfügbar werden“compliance-artifact und archive-artifact existieren nicht während der gesamten Lebensdauer eines Records. Keines von beiden entsteht bei der Record-Erstellung: Beide werden geschrieben, sobald die Übermittlung abgeschlossen ist — also sobald das SDI geantwortet hat, wofür die SDI-Spezifikation bis zu 48 Stunden zulässt. Beide werden im selben Moment gesetzt, weil der Archivierungsschritt vor dem Statuswechsel des Records läuft.
Daraus ergibt sich eine Regel, die allein auf dem Status beruht und kein Timing erfordert:
| Record-Status | Was er über die Artefakte aussagt |
|---|---|
state: ACCEPTED, mode: PROCESSING | Nicht final. Artefakte können noch fehlen — fehlend bedeutet hier noch nicht, sie kommen noch. |
state: COMPLETED / FAILED / REJECTED, mode: FINISHED | Final. Was vorhanden ist, ist alles, was es geben wird; ein fehlendes Artefakt erscheint nicht mehr. |
Die Anforderung eines noch nicht existierenden Artefakts liefert 200 mit dem unveränderten Record — keinen Fehler und keinerlei Hinweis auf „noch nicht bereit“. Entscheiden Sie anhand von state und mode des Records, ob ein fehlendes Artefakt noch nicht oder nie bedeutet, und nicht anhand der Antwort auf die Artefakt-Anfrage.
Der Aufbewahrungsnachweis gehört zum Record E_INVOICE::TRANSMISSION und nicht zur TRANSACTION::INVOICE. Nehmen Sie content.used_in.id aus dem Rechnungs-Record und rufen Sie dann auf:
GET /records/{transmissionId}?archive-artifactDer Nachweis wird Base64-codiert in content.compliance.archive.data zurückgegeben. Gesendete und empfangene Rechnungen haben jeweils ihren eigenen Nachweis. Solange das Artefakt noch nicht verfügbar ist, fehlt das Feld in der Antwort, anstatt vorhanden und leer zu sein.
file-artifact liefert den signierten Umschlag des Records in der übermittelten Form — einen generischen Wrapper, der für alle Record-Typen verwendet wird, bei der Record-Erstellung festgelegt wird und keinen Bezug zur FatturaPA-Erzeugung hat. Es ist wohlgeformtes XML, aber nicht die FatturaPA, und es darf nicht als Rechnung erfasst werden. Für die FatturaPA verwenden Sie compliance-artifact.
Weder der Aufbewahrungsnachweis noch file-artifact ist eine Darstellung der Rechnung. Für eine menschenlesbare Darstellung laden Sie das Dateipaket der Übermittlung herunter — ein ZIP mit dem FatturaPA-XML, demselben Dokument als PDF und einer Metadaten-JSON — über seinen eigenen Endpunkt:
GET /files/{transmissionId}.zipIn der Test-Umgebung läuft die Archivierung vollständig ab, aber das Ergebnis hat keine rechtliche Gültigkeit — es dient ausschließlich Integrationstests. Nur in der Live-Umgebung verarbeitete Rechnungen werden als rechtskonform aufbewahrt zertifiziert.
Stempelsteuer (imposta di bollo)
Abschnitt betitelt „Stempelsteuer (imposta di bollo)“Das italienische Recht verlangt eine Stempelsteuer (imposta di bollo) von 2,00 € auf Rechnungen, deren umsatzsteuerfreie Positionen zusammen 77,47 € übersteigen. fiskaly wendet sie automatisch an: Sobald die Summe der betreffenden umsatzsteuerfreien Positionen diesen Schwellenwert überschreitet, wird die Stempelsteuer der übermittelten FatturaPA hinzugefügt.
Es gibt kein Feld für die Stempelsteuer — weder in der Anfrage noch in der Antwort: Beim Erstellen der Rechnung ist nichts zu setzen, und am Record wird nichts zurückgegeben. Der angewendete Wert erscheint ausschließlich im Element DatiBollo des FatturaPA-XML, das Sie aus dem übermittelten Dokument lesen können:
GET /records/{transmissionId}?compliance-artifactDas XML wird Base64-codiert übertragen — decodieren Sie es also, bevor Sie nach DatiBollo suchen.
Rechnen Sie mit zwei Warnungen zu abweichenden Summen
Abschnitt betitelt „Rechnen Sie mit zwei Warnungen zu abweichenden Summen“Die 2,00 € werden nach der Berechnung der Rechnungssummen hinzugefügt. Auf jeder Rechnung, die den Schwellenwert überschreitet, liegen die übermittelten Summen daher 2,00 € über den von Ihnen gesendeten. Der Record hält diese Differenz als zwei WARNING-Einträge in content.logs fest, zum Beispiel:
provided '100.00000000', calculated '102.00'Das ist erwartetes Verhalten und zugleich das Signal dafür, dass die Stempelsteuer angewendet wurde. Senden Sie weiterhin Ihre Summen ohne Stempelsteuer: Es gibt keine Payload, die die Stempelsteuer enthält und zugleich die Warnungen vermeidet. Behandeln Sie diese beiden WARNING-Einträge als rein informativ und lassen Sie Ihre Integration daran nicht scheitern.
So funktioniert es heute. Die Behandlung der Stempelsteuer in den Summen wird überarbeitet (META-5229); danach werden diese Warnungen nicht mehr ausgelöst.
Rechnungen gutschreiben, die außerhalb von fiskaly ausgestellt wurden
Abschnitt betitelt „Rechnungen gutschreiben, die außerhalb von fiskaly ausgestellt wurden“In Italien ist der Dokumenttyp die FatturaPA-Typkennung: Eine CORRECTION wird als TD04 (Nota di credito) übermittelt, eine INVOICE als TD01 (Fattura). Da der Typ aus dem Vorgang abgeleitet wird, kann eine Rechnung, die nicht über fiskaly übermittelt wurde, nicht gutgeschrieben werden — eine TD01, die auf die frühere Rechnung verweist, erhöht den geschuldeten Betrag, anstatt ihn auszugleichen. Die allgemeine Regel finden Sie unter Credit Note.
Für Einzelfälle gewährt das SdI allen Händlern Portalzugang, über den eine Gutschrift manuell ausgestellt werden kann. Das skaliert nicht und ist kein Integrationsmuster — behandeln Sie es als Rückfalloption für die Migration und halten Sie das bisherige E-Rechnungssystem verfügbar, bis alles dort Ausgestellte beglichen oder gutgeschrieben ist.