Section navigation

E-INVOICE IT für SIGN IT-Kunden

Sie sehen die Dokumentation für API-Version 2026-06-01.

Dieser Leitfaden richtet sich an Kunden, die bereits über eine funktionierende SIGN IT-Integration verfügen und die italienische E-Rechnungsstellung (E-INVOICE IT) — B2B und B2C — ergänzen möchten. Beide Produkte basieren auf derselben Unified API und teilen sich dieselbe Taxpayer- und Location-Struktur — es sind nur wenige Ergänzungen erforderlich.

Kommen Sie von SIGN IT 2024-10-31 oder 2025-08-12? Aufklappen und zuerst lesen.

Nach Version 2025-08-12 wurden einige Ressourcen umbenannt und neue für die E-Rechnungsstellung hinzugefügt. Die aktualisierten Endpunkte können mit den bereits verwendeten {id} aufgerufen werden.

Bis Version 2025-08-12	Nach Version 2025-08-12	Hinweise
`ASSET` — `/assets`	`ORGANIZATION` — `/organizations`	Nur eine Umbenennung — gleiche ID wie vorher.
`ENTITY` (`COMPANY`/`INDIVIDUAL`) — `/entities`	`TAXPAYER` (`COMPANY`/`INDIVIDUAL`) — `/taxpayers`	Nur eine Umbenennung — gleiche ID wie vorher.
`ENTITY` (`LOCATION`) — `/entities`	`LOCATION` — `/locations`	Diese Ressource ist jetzt in zwei Arten aufgeteilt: `HEAD_OFFICE` location: wird automatisch bei der Erstellung des Taxpayers angelegt — gleiche ID wie Ihr vorheriges `ENTITY` (`COMPANY`/`INDIVIDUAL`) `BRANCH` location: jede zusätzliche Location. Wird über den `createLocation`-Endpunkt erstellt — gleiche ID wie Ihr vorheriges `ENTITY` (`LOCATION`)
`SYSTEM` mit Verweis auf `entity: {id}`	`SYSTEM` mit Verweis auf `location: {id}`	Nur eine Umbenennung — gleiche ID wie vorher.

Bevor Sie fortfahren:

Aktualisieren Sie Ihren X-Api-Version-Header auf die im Banner oben angegebene Version.
Stellen Sie sicher, dass Sie die richtigen Basis-URLs verwenden: test.api.fiskaly.com (TEST) und live.api.fiskaly.com (LIVE).
Fügen Sie fiscalization.credentials.tax_id_number zu Ihren FISCONLINE-Zugangsdaten hinzu, falls noch nicht vorhanden. Dieses Feld war in 2024-10-31 nicht erforderlich, in 2025-08-12 optional, ist aber jetzt erforderlich.
Prüfen Sie die wichtigsten Änderungen an der Record-Payload-Struktur in der API-Dokumentation — dieser FAQ-Artikel kann dabei helfen. Bei Fragen wenden Sie sich gerne an dev-support@fiskaly.com.

Was Ihre SIGN IT-Integration bereits abdeckt

Vor dem Start wird davon ausgegangen, dass Ihre Integration Folgendes umfasst:

Einen Taxpayer, der mit italienischen Fiskalisierungsdaten erstellt wurde (fiscalization.type=IT, tax_id_number, vat_id_number, credentials)
Den in Betrieb genommenen Taxpayer (state=COMMISSIONED, mode=OPERATIVE)
Ein FISCAL_DEVICE System, das auf der Location des Taxpayers in Betrieb genommen wurde
Einen INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION Ablauf für fiskalische Belege

Nichts davon muss geändert werden. Die folgenden Schritte ergänzen E-INVOICE IT zum bestehenden Setup.

Taxpayer-Onboarding-Daten erweitern

Ergänzen Sie die zusätzlichen Unternehmensregistrierungsdaten, die die italienische E-Rechnungsstellung erfordert.

Ein zusätzliches System in Betrieb nehmen

Aktivieren Sie den E-Rechnungsdienst auf Ihrem Taxpayer — dies deckt das Senden und optional das Empfangen ab.

Den Rechnungs-Transaktionsablauf hinzufügen

Beginnen Sie mit dem Ausstellen von Rechnungen und Gutschriften an Unternehmen und Verbraucher.

Schritt 1 — Taxpayer-Onboarding-Daten erweitern

📘Vorerst nur COMPANY-Taxpayer

E-INVOICE IT unterstützt derzeit Taxpayer vom Typ COMPANY. Ein INDIVIDUAL-Taxpayer — ein Freiberufler oder Einzelunternehmer, der unter seinem eigenen Codice fiscale statt einer Unternehmens-USt-IdNr. ausstellt — kann noch nicht erweitert werden; die Unterstützung folgt in Kürze.

Zwei Ergänzungen am Taxpayer sind erforderlich, die SIGN IT allein nicht benötigt:

address.region — der italienische Provincia-Code (z. B. MI, RM) ist für die SDI-Übermittlung obligatorisch. Falls er noch nicht am Taxpayer gesetzt ist, fügen Sie ihn über updateTaxpayer hinzu.
fiscalization.registration — ein neuer Block mit Daten aus dem Registro delle Imprese / REA.

Erforderliche Felder: company_id, office, entry, legal_form, capital, shareholder_status, liquidation_status. Das Feld tax_regime verwendet standardmäßig ORDINARY, wenn Sie es nicht angeben.

Das SDI verlangt diesen Block für registrierte Unternehmen — geben Sie ihn beim Onboarding des Taxpayers an.

Beispiel: PATCH /taxpayers/{taxpayer_id}

{
  "content": {
    "address": {
      "region": "MI"
    },
    "fiscalization": {
      "type": "IT",
      "registration": {
        "company_id": "MI12345678901234567",
        "office": "MI",
        "entry": "1234567",
        "legal_form": "LIMITED_LIABILITY_COMPANY",
        "capital": "10000.00",
        "shareholder_status": "MULTIPLE_SHAREHOLDERS",
        "liquidation_status": "NOT_IN_LIQUIDATION"
      }
    }
  }
}

💡address.region bereits vorhanden?

Wenn Ihre SIGN IT-Integration die vollständige Adresse des Taxpayers einschließlich region bereits erfasst, ist hier keine Änderung nötig — fügen Sie lediglich den registration-Block hinzu.

Schritt 2 — Ein zusätzliches System in Betrieb nehmen

Das E_INVOICE_SERVICE System ist das einzige System, das E-Rechnungen erstellt und übermittelt (und eingehende empfängt). Es ersetzt nicht Ihre FISCAL_DEVICE Systeme: Sie erstellen den Rechnungs-Record (TRANSACTION::INVOICE) weiterhin auf einem FISCAL_DEVICE System (einem beliebigen auf demselben Taxpayer), und das E_INVOICE_SERVICE System wandelt diese Daten in die E-Rechnung um.

📘Möchten Sie auch empfangen?

Der Empfang ist optional. Wenn Sie ihn wünschen, hinterlegen Sie in Ihrem Portal der Agenzia delle Entrate (AdE) den SDI-Empfängercode JKKZDGR von fiskaly als SDI-Zieladresse Ihres Unternehmens — jederzeit, vor oder nach der Inbetriebnahme. Ohne ihn empfängt der Taxpayer keine Rechnungen, selbst wenn das System bereit ist. Überspringen Sie ihn, wenn der Taxpayer nur senden wird.

Verwenden Sie createSystem, um ein E_INVOICE_SERVICE System auf der HEAD_OFFICE Location des Taxpayers zu erstellen, und nehmen Sie es anschließend über updateSystem in Betrieb, indem Sie seinen state auf COMMISSIONED setzen.

⚠️Caution

Pro Taxpayer kann nur ein E_INVOICE_SERVICE System in Betrieb genommen werden, auf der HEAD_OFFICE Location (die automatisch mit dem Taxpayer angelegt wird) — die Inbetriebnahme eines zweiten schlägt fehl. Es bleibt getrennt von den FISCAL_DEVICE Systemen für die Belegfiskalisierung, die davon unberührt bleiben, egal wie viele Sie haben.

📘Wenn das System auf TRANSMISSION_ONLY bleibt

Die Antwort auf die Inbetriebnahme zeigt stets TRANSMISSION_ONLY; rufen Sie anschließend retrieveSystem auf, um den tatsächlichen compliance.state des Systems zu lesen. Bleibt er TRANSMISSION_ONLY, anstatt zu TRANSMISSION_RECEPTION zu wechseln, wurde die Registrierung des Taxpayers nicht abgeschlossen — behandeln Sie dies als hängengebliebenen Übergang und wenden Sie sich unter dev-support@fiskaly.com an das fiskaly-Support-Team, mit der USt-IdNr. des Taxpayers, damit wir dies untersuchen können.

Den vollständigen Empfangsablauf finden Sie unter Empfang von E-Rechnungen auf der Italien-Seite.

Schritt 3 — Den Rechnungs-Transaktionsablauf hinzufügen

SIGN IT verwendet TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION.

E-INVOICE IT verwendet andere Transaktionstypen im selben INTENTION::TRANSACTION Container:

Rechnung (B2B oder B2C) → erstellen Sie eine TRANSACTION::INVOICE auf einem FISCAL_DEVICE System (wie in Schritt 2)
Gutschrift → erstellen Sie eine TRANSACTION::CORRECTION mit data.type=INVOICE, die über record.id auf die ursprüngliche Rechnung verweist

Sowohl BUSINESS- als auch CONSUMER-Empfänger werden unterstützt. Bei einem Geschäftsempfänger benötigt der Eintrag im recipients-Array der Rechnung einen invoicing-Block vom Typ SDI sowie die Provincia des Empfängers:

recipients[].type = BUSINESS
recipients[].invoicing.type = SDI
recipients[].invoicing.destination_code — der 7-stellige SDI-Postfachcode des Empfängers
recipients[].invoicing.pec — (wo erforderlich) die PEC-Adresse des Empfängers
recipients[].address.region — die Provincia des Empfängers (z. B. MI, RM)

Szenario	`destination_code`	`pec`
Empfänger hat ein registriertes SDI-Postfach	sein 7-stelliger Code, nur Großbuchstaben und Ziffern (z. B. `ABC1234`)	optional
Empfänger ist nicht beim SDI registriert	`"0000000"`	erforderlich
Empfänger befindet sich außerhalb Italiens	`"XXXXXXX"`	nicht verwendet

⚠️Geben Sie die region (Provincia) des Empfängers an

Geben Sie die Provincia des Empfängers in recipients[].address.region an. Sie ist im gemeinsamen Unified-API-Schema nicht als Pflichtfeld gekennzeichnet, aber Italien verlangt sie, 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.

Bei einem Verbraucherempfänger (B2C) sind die Felder anders — kein frei wählbarer destination_code und keine USt-IdNr., aber der Codice fiscale ist zwingend:

recipients[].type = CONSUMER
recipients[].identification.type = TAX, mit number als Codice fiscale des Verbrauchers
recipients[].name — gender, forename und surname
recipients[].address — die Wohnadresse des Verbrauchers, einschließlich region (Provincia)
recipients[].invoicing.destination_code = "0000000", pec optional

📘Wenn Ihnen das Geschlecht des Verbrauchers nicht vorliegt

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.

Die vollständigen Anforderungen an den Empfänger finden Sie unter E-Rechnungen senden auf der Italien-Seite.

Wenn der Kunde eine Rechnung statt eines Belegs benötigt

Ihre beiden Abläufe melden an unterschiedliche Stellen — der Beleg an die AdE, die Rechnung an 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 auf dem System E_INVOICE_SERVICE anstelle des Belegs 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.

📘Upgrade vom Beleg zur Rechnung in Entwicklung

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

Asynchrones Ergebnis

Anders als bei Beleg-Abläufen erfolgt das SDI-Ergebnis asynchron. Nach dem Erstellen der TRANSACTION::INVOICE fragen Sie den E_INVOICE::TRANSMISSION Record ab oder warten auf Aktualisierungen.

💡Tip

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.

Gesendete und empfangene E-Rechnungen werden automatisch langfristig aufbewahrt (conservazione a norma, mindestens 10 Jahre), wobei ein Aufbewahrungsnachweis über das archive-artifact des Records verfügbar ist. Es ist keine Einrichtung erforderlich. Einzelheiten finden Sie unter Archivierung auf der Italien-Seite.

📘Note

Das Compliance-Artefakt für die italienische E-Rechnungsstellung ist das FatturaPA-XML, das über den E_INVOICE::TRANSMISSION Record zugänglich ist.

Fehlerstufen

Fehler können in drei verschiedenen Phasen auftreten, jeweils mit unterschiedlichem Verhalten:

Phase	Wann	Verhalten
UAPI-Validierung (synchron)	Ungültiges Payload	`4xx` wird sofort zurückgegeben — es wird kein Record erstellt. Korrigieren Sie das Payload und versuchen Sie es erneut mit demselben `INTENTION::TRANSACTION`.
Vor-SDI-Validierung (asynchron)	Die Rechnung wird abgelehnt, bevor sie das SDI erreicht	Die gesamte Kette erreicht `state=FAILED` — für einen erneuten Versuch ist eine neue Kette erforderlich.
SDI-Ablehnung (asynchron)	SDI gibt `NS` zurück	Die gesamte Kette erreicht `state=FAILED` — für einen erneuten Versuch ist eine neue Kette erforderlich.

Fehler und erneute Übermittlung

Wenn das SDI NS (Notifica di Scarto) zurückgibt, ist die Rechnung rechtlich nicht existent:

Lesen Sie logs[].message an einem der drei Records, um den SDI-Ablehnungsgrund zu erhalten
Erstellen Sie eine neue INTENTION::TRANSACTION und eine neue TRANSACTION::INVOICE mit den korrigierten Daten
Dieselbe document.number darf innerhalb von 5 Tagen nach der NS-Ablehnung erneut verwendet werden
Die fehlgeschlagene Kette bleibt dauerhaft FAILED — sie wird zu Prüfzwecken aufbewahrt

⚠️Kein automatischer erneuter Versuch

Jede erneute Übermittlung startet eine neue Transaktionskette — UAPI behandelt sie als völlig neue Übermittlung.

Was unverändert bleibt

Folgendes bleibt vollständig unberührt:

Der Inbetriebnahme-Ablauf des Taxpayers und die Fisconline-Anmeldedaten
Alle FISCAL_DEVICE Systeme und BRANCH Locations
Ihr bestehender INTENTION::TRANSACTION → TRANSACTION::RECEIPT / TRANSACTION::CORRECTION / TRANSACTION::CANCELLATION Beleg-Ablauf