Für SIGN DE Kunden

⚠️ Sie sehen die Dokumentation für API-Version 2024-10-31. Die neueste Version ist 2026-05-04. Wesentliche Änderungen umfassen aktualisierte Terminologie (Asset → Organization, Entity → Taxpayer/Location).

SIGN IT Integrationsleitfaden für SIGN DE Kunden

Dieser Leitfaden erklärt die wesentlichen Unterschiede zu SIGN DE und unterstützt Sie dabei, die fiskaly SIGN IT API erfolgreich zu integrieren. Er beschreibt alle erforderlichen Schritte für Sie und Ihre Händler.

Unified API-Ansatz

SIGN IT ist Teil des Unified API-Ansatzes von fiskaly. Das bedeutet, dass Sie durch die Integration von SIGN IT bereits darauf vorbereitet sind, SIGN FR (Frankreich) und SIGN ES (Spanien) sowie andere kommende Länder mit minimalem Zusatzaufwand zu nutzen.

Im Gegensatz zu SIGN DE erfordert SIGN IT keine separate Management API. Alle notwendigen Endpunkte für Authentifizierung, Asset-Erstellung, Konfiguration und Handhabung von Steuer-Records 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.
In SIGN DE bestimmt der API Key selbst, ob TEST- oder LIVE-Ressourcen erstellt werden.
Ein Token, der mit einem LIVE API Key erstellt wird, erstellt LIVE-Ressourcen.
Ein Token, der mit einem TEST API Key erstellt wird, erstellt TEST-Ressourcen — auch wenn die URL dieselbe bleibt.

In SIGN IT wird die Umgebung über die Basis-URL ausgewählt.
Sie müssen jeden Endpunkt mit der richtigen 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

Bei allen Unified API-Lösungen muss jede Anfrage den X-Api-Version-Header enthalten.
Der Wert entspricht dem Veröffentlichungsdatum der Version. Dies gibt Ihnen volle Kontrolle darüber, wann Sie zu einer neueren Version wechseln, 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 laufen zu lassen, wenn nötig, während neue Kunden direkt mit der neuesten Version onboarded werden.

Hauptvorteil: Keine weiteren Breaking Changes in Ihrer laufenden Version.

X-Idempotency-Key

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

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

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

X-Scope-Identifier

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

Er macht Integrationen sauberer und flexibler, da der Header den Gültigkeitsbereich explizit definiert (zum Beispiel, zu welchem Asset::UNIT ein API Key gehört).

Terminologie-Mapping: SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Erläuterung
`Asset::TENANT`	(keine Entsprechung)	Struktur der obersten Ebene im fiskaly HUB. Repräsentiert das gesamte Kundenkonto. Kann nicht in anderen Assets verschachtelt werden.
`Asset::GROUP` (optional)	`organisation` (mit `billing_options`)	Optionale Zwischenschicht zur Organisation mehrerer Steuerpflichtiger in logischen Clustern.
`Asset::UNIT`	`managed_organization`	Repräsentiert einen einzelnen Händler oder Steuerpflichtigen. Jedes `Asset::UNIT` ist über eine `Entity` mit einem Steuerpflichtigen verknüpft.
`Entity::COMPANY` oder `Entity::INDIVIDUAL`	In Deutschland Teil der `managed_organization` (DSFINVK DE) oder `taxpayer` (SUBMIT DE)	Definiert den Steuerpflichtigen für das verknüpfte `Asset::UNIT`, erforderlich zur Erfüllung steuerlicher Pflichten.
`Entity::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 für die Fiskalisierung verwendete POS/Kassensystem.
`Subject::API_KEY`	`API key`	API Key-Authentifizierungsobjekt, das zur Autorisierung des Zugangs verwendet wird.
`Record`	`transaction`	Repräsentiert einen am Kassensystem durchgeführten Vorgang. Erfordert immer zwei Aufrufe: einen `Record::INTENTION` und einen `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Markiert den Beginn eines Kaufprozesses oder eines anderen einzelnen Ereignisses, das am Kassensystem verarbeitet wird.
`Record::TRANSACTION`	`Finish-Transaction`	Markiert den Abschluss eines Kaufprozesses.

SIGN IT Schritt-für-Schritt

Erste Organisation

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

Von diesem Punkt an 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 diesen Token zur Authentifizierung für die Erstellung der Organisationsstruktur für Italien.
Er funktioniert genauso wie der Token in SIGN DE (Management API), der mit dem API Key der (Haupt-)Organisation erstellt und dann zur Erstellung von managed_organizations verwendet wurde.
In SIGN IT ist dieser Token jetzt zur Erstellung von Asset::UNIT-Ressourcen erforderlich.

POST: Asset (UNIT) erstellen

Erstellen Sie ein Asset::UNIT (Asset vom Typ Unit), das Ihren ersten Kunden repräsentiert. Dies entspricht der über die Management für SIGN DE erstellten managed_organization.

In diesem Schritt ist nur der Name des Asset::UNIT erforderlich.
Im Gegensatz zu SIGN DE gehören die Steuerpflichtigen-Informationen zur Entity-Ressource, die je nach Art des Steuerpflichtigen (juristische oder natürliche Person) vom Typ COMPANY oder INDIVIDUAL sein kann. Diese Details legen Sie im Schritt Entity (COMPANY / INDIVIDUAL) unten fest.

POST: Subject (API Key) erstellen

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

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

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

POST: Token erstellen (bereichsbezogen)

Dieser Token ist auf das Asset::UNIT beschränkt. Verwenden Sie ihn für alle steuerpflichtigen-spezifischen Vorgänge.

Mit dem zuvor erstellten API Key für das Asset::UNIT müssen Sie diesen bereichsbezogenen Token erstellen.
Er wird für alle Vorgänge verwendet, die innerhalb dieses spezifischen Asset::UNIT durchgeführt werden müssen.

POST: Entity erstellen (COMPANY / INDIVIDUAL)

Definiert die Steuerpflichtigen-Repräsentation für das entsprechende Asset::UNIT.

Eine Entity vom Typ COMPANY oder INDIVIDUAL repräsentiert den Steuerpflichtigen — entweder eine juristische Person (Unternehmen) oder eine natürliche Person (Einzelunternehmer).
Jeder Steuerpflichtige muss als Entity erstellt werden, bevor steuerliche Vorgänge durchgeführt werden können.

Da SIGN IT dem Unified API-Ansatz folgt, ist die Entity-Struktur auf standardisierte Weise gestaltet und in zwei Hauptteile unterteilt:

Allgemeine Informationen (länderübergreifend geteilt):
Dazu gehören gemeinsame Attribute wie Name und Adresse des Steuerpflichtigen.
Fiskalisierungsinformationen (länderspezifischer Abschnitt):
Dieser enthält steuerliche Attribute, die von nationalen Vorschriften gefordert werden, wie die Steueridentifikationsnummer und die steuerlichen Anmeldeinformationen.
In Italien umfasst dies steuerliche Attribute wie die Steuernummer (Codice Fiscale) und die Umsatzsteuer-Identifikationsnummer (Partita IVA), die von nationalen Vorschriften gefordert werden.

PATCH: Entity aktualisieren

Aktualisieren Sie den Zustand von ACQUIRED auf COMMISSIONED, um die Entity zu aktivieren.

Im Gegensatz zu SIGN DE haben Entities in SIGN IT ein state-Attribut.
Wenn eine Entity erstellt wird, ist ihr Anfangszustand ACQUIRED.
Bevor sie verwendet werden kann, muss die Entity auf den Zustand COMMISSIONED aktualisiert werden.

Dieser Schritt ist irreversibel. Von diesem Punkt an wird die Ressource gemäß dem anwendbaren Abrechnungsmodell abrechenbar.

Wenn eine Entity nicht mehr verwendet wird, kann sie auf den Zustand DECOMMISSIONED aktualisiert werden.
Dieser Schritt ist ebenfalls irreversibel und sollte nur durchgeführt werden, wenn sicher ist, dass der Kunde diese Entity nicht mehr verwenden wird.

Zusätzlich zu Zuständen hat jede Entity in SIGN IT ein mode-Attribut, das ihren Betriebsstatus definiert.

Wenn die Entity den Zustand ACQUIRED oder DECOMMISSIONED hat, ist ihr Modus immer INACTIVE.
In diesem Modus kann die Ressource nicht verwendet werden.
Wenn die Entity auf den Zustand COMMISSIONED aktualisiert wird, validiert der SIGN IT-Dienst automatisch alle erforderlichen Konfigurationen.
Bei Erfolg wechselt der Modus zu OPERATIVE.
Wenn es ein Problem mit der Entity oder einer ihrer abhängigen Ressourcen gibt, ändert sich der Modus automatisch zu DEGRADED (noch nicht implementiert), bis das Problem behoben ist.
Sobald das Problem behoben ist, wird der SIGN IT-Dienst den Modus auf OPERATIVE zurücksetzen.
Der Modus SUSPENDED kann manuell für Entities im Zustand COMMISSIONED über den updateEntity-Endpunkt gesetzt werden.
Dies ist nützlich, um steuerliche Vorgänge vorübergehend zu unterbrechen, zum Beispiel beim Aktualisieren von Anmeldeinformationen oder bei Wartungsarbeiten. Wenn der SIGN IT-Dienst die Entity aufgrund eines Problems, das Benutzeraktionen erfordert, in den Modus DEGRADED (noch nicht implementiert) versetzt, sollte der Modus zuerst auf SUSPENDED geändert werden, während die erforderlichen Aktionen durchgeführt werden, und dann auf OPERATIVE zurückgesetzt werden, sobald das Problem behoben wurde.

Zusammenfassung:

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

POST: Entity erstellen (LOCATION)

Definiert den physischen Geschäftsstandort. Beginnt ebenfalls im Zustand ACQUIRED.

Für jeden Standort eines Steuerpflichtigen sollte eine separate Entity vom Typ LOCATION erstellt werden.
In der SIGN IT-Lösung erfordert dies kein separates Asset::UNIT.
Alle Standorte eines Steuerpflichtigen werden innerhalb desselben Asset::UNIT repräsentiert und mit der entsprechenden Entity::COMPANY oder Entity::INDIVIDUAL verknüpft.
Jeder Steuerpflichtige (Entity::COMPANY oder Entity::INDIVIDUAL) sollte mindestens eine zugehörige Entity::LOCATION haben.

PATCH: Entity aktualisieren (LOCATION)

Aktualisieren Sie den Zustand der Entity::LOCATION auf COMMISSIONED.

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

POST: System erstellen

Ein System vom Typ FISCAL_DEVICE repräsentiert ein POS oder Kassensystem.
Es entspricht dem client in SIGN DE.
Jedes System ist mit einer Entity::LOCATION verknüpft.

Im Gegensatz zu SIGN DE müssen beim Erstellen eines FISCAL_DEVICE zusätzliche Informationen über das elektronische Aufzeichnungssystem selbst bereitgestellt werden.
Die meisten dieser Details werden in der Regel vom POS-Anbieter definiert.
In Deutschland werden diese Informationen üblicherweise später im Rahmen 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 Zustand ACQUIRED auf COMMISSIONED, um es zu aktivieren.

Die System-Ressource folgt derselben Zustands- und Moduslogik wie eine Entity.
Sobald sie auf COMMISSIONED gesetzt wird, wird das System aktiv und die Abrechnung erfolgt automatisch (bei Verwendung in der LIVE-Umgebung).
Wenn es nicht mehr in Betrieb ist, kann es auf DECOMMISSIONED gesetzt werden, was — wie in SIGN IT allgemein — irreversibel ist.

Das mode-Attribut spiegelt den Betriebszustand des Systems wider (zum Beispiel OPERATIVE, SUSPENDED oder DEGRADED). DEGRADED ist noch nicht implementiert. Diese Modi verhalten sich genauso wie für Entity beschrieben und ermöglichen es Ihnen, Vorgänge vorübergehend zu unterbrechen oder automatisch eine beeinträchtigte Leistung aufgrund von Konfigurationsproblemen anzuzeigen.

Einrichtung abgeschlossen

Mit dem erfolgreich in Betrieb genommenen System ist die anfängliche Einrichtungsphase abgeschlossen.
Alle organisatorischen und steuerlichen Strukturen — vom Asset::UNIT über Entity bis hin zu System — sind jetzt aktiv und produktionsbereit.

Von diesem Punkt an beschreiben die folgenden Schritte die täglichen Steuer-Vorgänge am POS.
Dazu gehören das Erstellen und Verarbeiten von Steuer-Records, die Verkäufe, Rückgaben und andere Ereignisse repräsentieren — äquivalent zu Transaktionen in SIGN DE, aber mit erweiterten Steuerdaten, wie sie in Italien erforderlich sind.

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 täglichen Vorgängen fortgesetzt.
Diese Vorgänge repräsentieren die täglichen Geschäftsaktivitäten am POS — wie die Ausstellung von Belegen, die Verarbeitung von Rückgaben oder die Bearbeitung von Stornierungen.

Während das Gesamtkonzept dem von SIGN DE ähnelt, führt SIGN IT ein einheitliches und datenreicheres Record-Modell ein.
Jede Transaktion wird als ein oder mehrere Records dargestellt, die digital signiert, protokolliert und archiviert werden, um die vollständige Steuerkonformität sicherzustellen.

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

POST: Record erstellen

In SIGN IT wird jede steuerliche Transaktion als ein oder mehrere Records dargestellt.
Dieses Modell ersetzt den zweistufigen Transaktionsaktualisierungsprozess von SIGN DE (ACTIVE → FINISHED) durch zwei unabhängige Ressourcen: einen Record vom Typ INTENTION und einen weiteren Record 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 Zustand aktualisiert wird.
In SIGN IT wird diese Logik durch eine dedizierte Ressource ersetzt: einen Record vom Typ INTENTION.

Ein Record vom Typ INTENTION markiert den Beginn eines steuerlichen Vorgangs.
In Italien ist der unterstützte Intentions-Vorgang TRANSACTION.

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

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

Teil B) TRANSACTION

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

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

Er umfasst:

Dokumentinformationen wie Dokumentnummer, Datum sowie Gesamtbrutto- und Nettobeträge.
Details für jede Verkaufszeile (Waren oder Dienstleistungen), einschließlich Beschreibung, Menge, Mehrwertsteuersatz und Betrag.
Verweise auf vorherige Belege bei der Erstellung von CORRECTION- oder CANCELLATION-Records.

Dieser Record-Typ stellt die vollständige steuerliche Repräsentation der Transaktion gemäß den italienischen Vorschriften bereit.

Aufzeichnungszustände und -modi

Jeder Record in SIGN IT (ob INTENTION, TRANSACTION oder andere Typen) folgt seinem eigenen Zustand und Modus, der seinen Lebenszyklus innerhalb des Fiskalisierungsprozesses widerspiegelt.

Zustände

Accepted – Der Record wurde empfangen, validiert und ist zur Verarbeitung bereit.
Rejected – Der Record wurde empfangen, hat aber unsere internen Validierungsprüfungen nicht bestanden. Details sind in den Log-Meldungen verfügbar.
Completed – Der Record wurde erfolgreich verarbeitet.
Failed – Der Record konnte aufgrund eines externen Übertragungsfehlers nicht verarbeitet werden. Details sind in den Log-Meldungen verfügbar.

Modi

Processing – Der Record wird derzeit verarbeitet.
Finished – Der Record wurde verarbeitet, erfolgreich oder nicht erfolgreich.

Übergänge

Übergang	Beschreibung
POST → Accepted	Der Record wird erstellt und tritt vorübergehend in den Zustand `Accepted` ein, wenn die Validierung erfolgreich ist, und geht sofort zum nächsten Schritt über.
POST → Rejected	Der Record schlägt die interne Validierung fehl und wechselt automatisch zu `Rejected`, wobei Fehler-Logs bereitgestellt werden.
Accepted → Completed	Wird automatisch gesetzt, wenn die Verarbeitung erfolgreich abgeschlossen wird.
Accepted → Failed	Wird gesetzt, wenn die Verarbeitung aufgrund einer externen Komponente fehlschlägt.
Processing → Finished	Zeigt an, dass die Verarbeitung abgeschlossen ist, unabhängig von Erfolg oder Misserfolg.

Dieses ereignisbasierte Design ermöglicht die unabhängige Verfolgung jedes steuerlichen Vorgangs — ohne Aktualisierung derselben Ressource — und gewährleistet einen transparenten, unveränderlichen Prüfpfad für jede Transaktion.

Zusammenfassung

Im täglichen Betrieb ersetzt SIGN IT den einfachen „Start → Abschluss”-Transaktionsfluss von SIGN DE durch ein mehrstufiges, ereignisgesteuertes Record-Modell.
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?