Für SIGN DE-Kunden

⚠️ Sie sehen die Dokumentation für API-Version 2026-02-03. Die neueste Version ist 2026-05-04. Die neue API-Version bringt keine Änderungen an der italienischen Integration. Sie fügt jedoch die SIGN PT-Unterstützung hinzu und ermöglicht es Teams, die eine Expansion nach Portugal planen, dieselbe Integration, die bereits für Italien vorhanden ist, wiederzuverwenden.

SIGN IT-Integrationsleitfaden für SIGN DE-Kunden

Dieser Leitfaden erläutert die wichtigsten Unterschiede zu SIGN DE und unterstützt Sie bei der erfolgreichen Integration der fiskaly SIGN IT API. Er beschreibt alle notwendigen Schritte für Sie und Ihre Händler.

Unified API-Ansatz

SIGN IT ist Teil von fiskalys Unified API-Ansatz. Das bedeutet, dass Sie durch die Integration von SIGN IT bereits für die Nutzung von SIGN FR (Frankreich) sowie anderer zukünftiger Länder mit minimalem Zusatzaufwand vorbereitet sind.

Im Gegensatz zu SIGN DE erfordert SIGN IT keine separate Management API. Alle notwendigen Endpunkte für Authentifizierung, Organisationserstellung, Konfiguration und die Handhabung von Steuerdatensätzen sind direkt in der SIGN IT enthalten — was die Integration schneller und einfacher macht.

Umgebungen: TEST und LIVE

In SIGN IT gibt es zwei separate Basis-URLs für die verschiedenen Umgebungen:

TEST-Umgebung: https://test.api.fiskaly.com
LIVE-Umgebung: https://live.api.fiskaly.com

Dies unterscheidet sich von SIGN DE, wo es nur eine Basis-URL für beide Umgebungen gibt.
Bei SIGN DE bestimmt der API Key selbst, ob TEST- oder LIVE-Ressourcen erstellt werden.
Ein mit einem LIVE API Key erstelltes Token erstellt LIVE-Ressourcen.
Ein mit einem TEST API Key erstelltes Token erstellt TEST-Ressourcen — auch wenn die URL dieselbe bleibt.

Bei SIGN IT wird die Umgebung über die Basis-URL ausgewählt.
Sie müssen jeden Endpunkt mit der korrekten Basis-URL (test.api.fiskaly.com oder live.api.fiskaly.com) aufrufen, je nachdem, ob Sie mit der TEST- oder LIVE-Umgebung interagieren möchten.

Header-Parameter

Im Unified API-Ansatz wurden einige neue HTTP-Header eingeführt, um Ihre Prozesse zu vereinfachen.
Sie bieten Flexibilität, gewährleisten Datenintegrität und machen Integrationen einfacher und zuverlässiger.

X-Api-Version

Für alle Unified API-Lösungen muss jede Anfrage den Header X-Api-Version enthalten.
Der Wert entspricht dem Veröffentlichungsdatum der Version. Damit haben Sie die vollständige Kontrolle darüber, wann Sie auf eine neuere Version wechseln möchten, um neue Funktionen zu nutzen.

Sie können Änderungen zunächst in der TEST-Umgebung testen und erst dann zur neuen Version migrieren, wenn alles überprüft wurde. Dies ermöglicht es Ihnen auch, einige Kunden auf einer älteren Version zu betreiben, falls nötig, während Sie neue Kunden direkt mit der neuesten Version onboarden.

Hauptvorteil: keine Breaking Changes mehr in Ihrer laufenden Version.

X-Idempotency-Key

Da Ressourcen-IDs nicht mehr von Ihnen definiert werden müssen, sondern von der API generiert werden, gewährleistet der X-Idempotency-Key, dass ein API-Aufruf idempotent behandelt wird.

Das bedeutet, dass wiederholte identische Anfragen mit demselben X-Idempotency-Key dasselbe Ergebnis liefern und doppelte Erstellungen verhindern.

Der X-Idempotency-Key ist für alle POST- und PATCH-Anfragen erforderlich.

X-Scope-Identifier

Der Header X-Scope-Identifier ersetzt die zuvor in der Management API verwendeten Pfadparameter zur Herstellung von Beziehungen zwischen Ressourcen.

Er macht Integrationen klarer und flexibler, da der Header explizit den Scope definiert (z. B. zu welcher Organization::UNIT ein API Key gehört).

Terminologiezuordnung: SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Erläuterung
`Organization::ACCOUNT`	(kein Äquivalent)	Übergeordnete Struktur im fiskaly HUB. Repräsentiert das gesamte Kundenkonto.
`Organization::GROUP`	`organization` (mit `billing_options`)	Repräsentiert die Hauptorganisation, unter der Steuerpflichtige verschachtelt sind.
`Organization::UNIT`	`managed_organization`	Repräsentiert einen einzelnen Händler oder Steuerpflichtigen. Jede `Organization::UNIT` ist mit einem `Taxpayer` verknüpft.
`Taxpayer::COMPANY` or `Taxpayer::INDIVIDUAL`	In Deutschland Teil der `managed_organization` (DSFINVK DE) oder des `taxpayer` (SUBMIT DE)	Definiert den Steuerpflichtigen für die verknüpfte `Organization::UNIT`, erforderlich zur Erfüllung steuerlicher Pflichten.
`Location`	Vergleichbar: `establishment` (SUBMIT DE)	Repräsentiert physische Standorte (z. B. Geschäfte), die vom Steuerpflichtigen betrieben werden.
`System::FISCAL_DEVICE`	`client`	Repräsentiert das POS / die Registrierkasse, die für die Fiskalisierung verwendet wird.
`Subject::API_KEY`	`API key`	API Key-Authentifizierungsobjekt, das zur Autorisierung des Zugriffs verwendet wird.
`Record`	`transaction`	Repräsentiert einen an der Registrierkasse durchgeführten Vorgang. Erfordert immer zwei Aufrufe: eine `Record::INTENTION` und eine `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Markiert den Beginn eines Kaufprozesses oder eines anderen Ereignisses, das an der Registrierkasse verarbeitet wird.
`Record::TRANSACTION`	`Finish-Transaction`	Markiert den Abschluss eines Kaufprozesses.

SIGN IT Schritt für Schritt

Erste Organisation

Zunächst müssen Sie im fiskaly HUB eine separate Organisation speziell für Italien und einen dedizierten API Key für die italienische Integration erstellen.

Ab diesem Punkt werden alle Integrationsschritte direkt über die SIGN IT abgewickelt. Im Gegensatz zu SIGN DE müssen Sie die Management nicht mehr verwenden, um Organisationsstrukturen zu erstellen oder zu verwalten. Alle erforderlichen Funktionen sind Teil der SIGN IT selbst.

POST: Token erstellen

Verwenden Sie dieses Token, um die Erstellung der Organisationsstruktur für Italien zu authentifizieren.
Es funktioniert genauso wie das Token in SIGN DE (Management API), das mit dem API Key der (Haupt-)Organisation erstellt wurde und dann zur Erstellung von managed_organizations verwendet wurde.
In SIGN IT ist dieses Token nun erforderlich, um Organization::UNIT-Ressourcen zu erstellen.

POST: Organisation (UNIT) erstellen

Erstellen Sie eine Organization::UNIT (Organisation vom Typ Unit), die Ihren ersten Kunden repräsentiert. Dies entspricht der managed_organization, die über die Management für SIGN DE erstellt wurde.

In diesem Schritt ist nur der Name der Organization::UNIT erforderlich.
Im Gegensatz zu SIGN DE gehören die Steuerpflichtigeninformationen zur Taxpayer-Ressource, die je nach dem, ob der Steuerpflichtige eine juristische oder natürliche Person ist, vom Typ COMPANY oder INDIVIDUAL sein kann. Diese Details definieren Sie im Schritt Taxpayer (COMPANY / INDIVIDUAL) weiter unten.

POST: Subject (API Key) erstellen

Jeder Ihrer Kunden benötigt einen eigenen API Key, um Ressourcen innerhalb seines spezifischen Organization::UNIT-Scopes zu erstellen.
Daher muss ein Subject::API_KEY (Subject vom Typ API Key) erstellt werden.

Verknüpfen Sie Ihren API Key mit der Organization::UNIT über den Header X-Scope-Identifier.

Im Gegensatz zu SIGN DE werden die Informationen darüber, zu welcher Unit der API Key gehört, nicht mehr über den Pfadparameter, sondern über den Header-Parameter X-Scope-Identifier bereitgestellt.
Dieser Header muss die ID der Organization::UNIT enthalten, zu der der API Key gehört.

POST: Token erstellen (mit Scope)

Dieses Token ist auf die Organization::UNIT beschränkt. Verwenden Sie es für alle steuerpflichtigenspezifischen Operationen.

Mit dem zuvor für die Organization::UNIT erstellten API Key müssen Sie dieses auf den Scope beschränkte Token erstellen.
Es wird für alle Operationen verwendet, die innerhalb dieser spezifischen Organization::UNIT durchgeführt werden müssen.

POST: Steuerpflichtigen erstellen (COMPANY / INDIVIDUAL)

Definiert die Steuerpflichtigenrepräsentation für die entsprechende Organization::UNIT.

Ein Taxpayer vom Typ COMPANY oder INDIVIDUAL repräsentiert entweder eine juristische Person (Unternehmen) oder eine natürliche Person (Einzelunternehmer).
Jeder Steuerpflichtige muss erstellt werden, bevor steuerliche Operationen durchgeführt werden können.

Da SIGN IT dem Unified API-Ansatz folgt, ist die Taxpayer-Struktur standardisiert aufgebaut und in zwei Hauptteile unterteilt:

Allgemeine Informationen (länderübergreifend gemeinsam):
Dies umfasst gemeinsame Attribute wie den Namen und die Adresse des Steuerpflichtigen.
Fiskalisierungsinformationen (länderspezifischer Abschnitt):
Dieser enthält steuerliche Attribute, die durch nationale Vorschriften erforderlich sind, wie die Steueridentifikationsnummer und Steuerzugangsdaten.
In Italien umfasst dies steuerliche Attribute wie die Steuernummer (Codice Fiscale) und die Umsatzsteuer-Identifikationsnummer (Partita IVA), die durch nationale Vorschriften erforderlich sind.

PATCH: Steuerpflichtigen aktualisieren

Aktualisieren Sie den Status von ACQUIRED auf COMMISSIONED, um den Steuerpflichtigen zu aktivieren.

Im Gegensatz zu SIGN DE verfügen Steuerpflichtige in SIGN IT über ein Status-Attribut.
Wenn ein Steuerpflichtiger erstellt wird, ist sein anfänglicher Status ACQUIRED.
Bevor er verwendet werden kann, muss der Steuerpflichtige auf den Status COMMISSIONED aktualisiert werden.

Dieser Schritt ist unumkehrbar. Ab diesem Punkt wird die Ressource gemäß dem geltenden Abrechnungsmodell abgerechnet.

Wenn ein Steuerpflichtiger nicht mehr in Verwendung ist, kann er auf den Status DECOMMISSIONED aktualisiert werden.
Auch dieser Schritt ist unumkehrbar und sollte nur durchgeführt werden, wenn feststeht, dass der Kunde diesen Steuerpflichtigen nicht mehr nutzen wird.

Neben Status verfügt jeder Steuerpflichtige in SIGN IT über ein Modus-Attribut, das seinen Betriebsstatus definiert.

Wenn der Steuerpflichtige den Status ACQUIRED oder DECOMMISSIONED hat, ist sein Modus immer INACTIVE.
In diesem Modus kann die Ressource nicht verwendet werden.
Wenn der Steuerpflichtige auf den Status COMMISSIONED aktualisiert wird, validiert der SIGN IT-Service automatisch alle erforderlichen Konfigurationen.
Bei Erfolg wechselt der Modus zu OPERATIVE.
Bei einem Problem mit dem Steuerpflichtigen oder einer seiner abhängigen Ressourcen ändert sich der Modus automatisch zu DEGRADED (noch nicht implementiert), bis das Problem behoben ist.
Sobald das Problem behoben wurde, setzt der SIGN IT-Service den Modus wieder auf OPERATIVE.
Der Modus SUSPENDED kann manuell für Steuerpflichtige im Status COMMISSIONED über den Endpunkt updateTaxpayer gesetzt werden.
Dies ist nützlich, um steuerliche Operationen vorübergehend zu pausieren, beispielsweise beim Aktualisieren von Zugangsdaten oder während Wartungsarbeiten. Wenn der SIGN IT-Service den Steuerpflichtigen aufgrund eines Problems, das Benutzeraktion erfordert, auf den Modus DEGRADED (noch nicht implementiert) setzt, sollte der Modus zunächst auf SUSPENDED geändert werden, während die notwendigen Maßnahmen ergriffen werden, und dann nach Behebung des Problems wieder auf OPERATIVE aktualisiert werden.

Zusammenfassung:

INACTIVE: Standardmodus für ACQUIRED und DECOMMISSIONED
OPERATIVE: Normaler Produktivmodus
DEGRADED (noch nicht implementiert): Automatisch vom SIGN IT-Service aufgrund eines Problems gesetzt
SUSPENDED: Manueller Wartungsmodus

POST: Standort erstellen

Definiert den physischen Geschäftsstandort. Startet ebenfalls im Status ACQUIRED.

Für jeden Standort eines Steuerpflichtigen sollte ein separater Location-Eintrag erstellt werden.
In der SIGN IT-Lösung erfordert dies keine separate Organization::UNIT.
Alle Standorte eines Steuerpflichtigen werden innerhalb derselben Organization::UNIT repräsentiert und sind mit dem entsprechenden Taxpayer::COMPANY oder Taxpayer::INDIVIDUAL verknüpft.
Jeder Steuerpflichtige sollte mindestens einen zugehörigen Location-Eintrag haben.

PATCH: Standort aktualisieren

Aktualisieren Sie den Status der Location auf COMMISSIONED.

Wie bei Taxpayer::COMPANY oder Taxpayer::INDIVIDUAL muss auch die Location auf den Status COMMISSIONED aktualisiert werden, bevor sie verwendet werden kann.
Erst nach diesem Schritt wird der Standort aktiv und kann genutzt werden.

POST: System erstellen

Ein System vom Typ FISCAL_DEVICE repräsentiert ein POS oder eine Registrierkasse.
Es entspricht dem Client in SIGN DE.
Jedes System ist mit einem Location-Eintrag verknüpft.

Im Gegensatz zu SIGN DE müssen bei der Erstellung eines FISCAL_DEVICE zusätzliche Informationen über das elektronische Aufzeichnungssystem selbst angegeben werden.
Die meisten dieser Details werden typischerweise vom POS-Anbieter definiert.
In Deutschland werden diese Informationen üblicherweise später als Teil des DSFinV-K DE- oder Submit DE-Prozesses hinzugefügt — in SIGN IT erfolgt dies jedoch in einem einzigen Schritt bei der Systemerstellung.

PATCH: System aktualisieren

Aktualisieren Sie das System vom Status ACQUIRED auf COMMISSIONED, um es zu aktivieren.

Die System-Ressource folgt derselben Status- und Moduslogik wie ein Taxpayer.
Sobald es auf COMMISSIONED gesetzt ist, wird das System aktiv und die Abrechnung gilt automatisch (wenn es in der LIVE-Umgebung verwendet wird).
Wenn es nicht mehr in Verwendung ist, kann es auf DECOMMISSIONED gesetzt werden, was — wie in SIGN IT generell — unumkehrbar ist.

Das mode-Attribut spiegelt den Betriebszustand des Systems wider (z. B. OPERATIVE, SUSPENDED oder DEGRADED). DEGRADED ist noch nicht implementiert. Diese Modi verhalten sich genauso wie für Taxpayer beschrieben, sodass Sie den Betrieb vorübergehend aussetzen oder automatisch eine beeinträchtigte Leistung aufgrund von Konfigurationsproblemen anzeigen können.

Einrichtung abgeschlossen

Mit dem erfolgreich in Betrieb genommenen System ist die anfängliche Einrichtungsphase abgeschlossen.
Alle organisatorischen und steuerlichen Strukturen — von Organization::UNIT über Taxpayer bis hin zu System — sind nun aktiv und produktionsbereit.

Von diesem Punkt an beschreiben die folgenden Schritte die täglichen steuerlichen Vorgänge am POS.
Dazu gehören die Erstellung und Verarbeitung von Steuerdatensätzen, die Verkäufe, Rückgaben und andere Ereignisse darstellen — äquivalent zu Transaktionen in SIGN DE, jedoch mit erweiterten steuerlichen Daten gemäß den Anforderungen in Italien.

Tägliche Vorgänge am POS

Sobald die Einrichtung abgeschlossen ist und alle Ressourcen in Betrieb genommen wurden, wird der Fiskalisierungsprozess in SIGN IT mit den täglichen Vorgängen fortgesetzt.
Diese Vorgänge repräsentieren die täglichen Geschäftsaktivitäten am POS — wie das Ausstellen von Belegen, die Verarbeitung von Rückgaben oder die Handhabung von Stornierungen.

Obwohl das Gesamtkonzept dem von SIGN DE ähnelt, führt SIGN IT ein einheitliches und datenreicheres Datensatzmodell ein.
Jede Transaktion wird als ein oder mehrere Datensätze dargestellt, die digital signiert, protokolliert und archiviert werden, um eine vollständige steuerliche Konformität zu gewährleisten.

Die folgenden Abschnitte beschreiben, wie diese Datensätze in der italienischen Steuerumgebung erstellt, verarbeitet und verwaltet werden.

POST: Datensatz erstellen

In SIGN IT wird jede steuerliche Transaktion als ein oder mehrere Datensätze dargestellt.
Dieses Modell ersetzt den zweistufigen Transaktions-Update-Prozess aus SIGN DE (ACTIVE → FINISHED) durch zwei unabhängige Ressourcen: einen Datensatz vom Typ INTENTION und einen weiteren Datensatz vom Typ TRANSACTION.

Teil A) INTENTION

In SIGN DE beginnt eine Transaktion mit einem Start-Transaction-Ereignis, das den Beginn eines steuerlichen Prozesses markiert und später auf einen abgeschlossenen Status aktualisiert wird.
In SIGN IT wird diese Logik durch eine dedizierte Ressource ersetzt: einen Datensatz vom Typ INTENTION.

Ein Datensatz vom Typ INTENTION markiert den Beginn eines steuerlichen Vorgangs.
In Italien ist die unterstützte Intention-Operation TRANSACTION.

Er enthält kontextbezogene Informationen, die die Absicht des Vorgangs definieren, darunter:

Das System (System::FISCAL_DEVICE), das den Vorgang durchführt.
Den Vorgangstyp, der der TRANSACTION entspricht.

Teil B) TRANSACTION

In SIGN DE wird eine Transaktion durch ein Finish-Transaction-Update der Transaktionsressource abgeschlossen, das den steuerlichen Prozess beendet.
In SIGN IT wird dieser Schritt durch eine separate Ressource dargestellt: einen Datensatz vom Typ TRANSACTION.

Ein Datensatz vom Typ TRANSACTION schließt den steuerlichen Vorgang ab und referenziert den zuvor erstellten Datensatz vom Typ INTENTION.
Er enthält alle steuerlichen und transaktionalen Daten, die für den Vorgang erforderlich sind.
Im Vergleich zu SIGN DE sind der Datenumfang und die Struktur umfangreicher und orientieren sich stärker an den Informationen, die in einer Transaktion innerhalb eines Kassenabschlusses in DSFinV-K DE enthalten sind.

Er umfasst:

Dokumentinformationen wie Belegnummer, Datum sowie Gesamtbrutto- und -nettobeträge.
Details zu jeder Verkaufszeile (Waren oder Dienstleistungen), einschließlich Beschreibung, Menge, Mehrwertsteuersatz und Betrag.
Verweise auf frühere Belege bei der Erstellung von CORRECTION- oder CANCELLATION-Datensätzen.

Dieser Datensatztyp liefert die vollständige steuerliche Darstellung der Transaktion gemäß den Anforderungen der italienischen Vorschriften.

Datensatz-Status und -Modi

Jeder Datensatz in SIGN IT (ob INTENTION, TRANSACTION oder andere Typen) folgt seinem eigenen Status und Modus, der seinen Lebenszyklus im Fiskalisierungsprozess widerspiegelt.

Status

Accepted (Akzeptiert) – Der Datensatz wurde empfangen, validiert und ist bereit zur Verarbeitung.
Rejected (Abgelehnt) – Der Datensatz wurde empfangen, hat aber unsere internen Validierungsprüfungen nicht bestanden. Details sind in den Protokollmeldungen verfügbar.
Completed (Abgeschlossen) – Der Datensatz wurde erfolgreich verarbeitet.
Failed (Fehlgeschlagen) – Der Datensatz konnte aufgrund eines externen Übertragungsfehlers nicht verarbeitet werden. Details sind in den Protokollmeldungen verfügbar.

Modi

Processing (In Verarbeitung) – Der Datensatz wird derzeit verarbeitet.
Finished (Abgeschlossen) – Der Datensatz wurde verarbeitet, erfolgreich oder nicht.

Übergänge

Übergang	Beschreibung
POST → Accepted	Der Datensatz wird erstellt und geht vorübergehend in den Status `Accepted` über, wenn die Validierung erfolgreich ist, und schreitet sofort zum nächsten Schritt fort.
POST → Rejected	Der Datensatz schlägt bei der internen Validierung fehl und wechselt automatisch zu `Rejected`, wobei Fehlerprotokolle bereitgestellt werden.
Accepted → Completed	Wird automatisch gesetzt, wenn die Verarbeitung erfolgreich abgeschlossen wurde.
Accepted → Failed	Wird gesetzt, wenn die Verarbeitung aufgrund einer externen Komponente fehlschlägt.
Processing → Finished	Zeigt an, dass die Verarbeitung abgeschlossen wurde, unabhängig vom Erfolg oder Misserfolg.

Dieses ereignisbasierte Design ermöglicht es, jeden steuerlichen Vorgang unabhängig zu verfolgen — ohne dieselbe Ressource zu aktualisieren — und gewährleistet einen transparenten, unveränderlichen Prüfpfad für jede Transaktion.

Zusammenfassung

Im täglichen Betrieb ersetzt SIGN IT den einfachen „Start → Finish”-Transaktionsfluss von SIGN DE durch ein Multi-Ressourcen, ereignisgesteuertes Datensatzmodell.
Jeder Vorgang — ob Verkauf (RECEIPT), Rückgabe (CORRECTION) oder Stornierung (CANCELLATION) — wird einzeln signiert, protokolliert und archiviert, was eine vollständige Rückverfolgbarkeit und Konformität mit dem italienischen Steuerrecht gewährleistet.

Was this page helpful?