Für SIGN DE-Kunden

SIGN IT Integrationsleitfaden für SIGN DE-Kunden

Dieser Leitfaden erklärt 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 vorbereitet sind, SIGN FR (Frankreich) sowie andere zukünftige Länder mit minimalem Zusatzaufwand zu nutzen.

Im Gegensatz zu SIGN DE erfordert SIGN IT keine separate Management API. Alle notwendigen Endpoints für Authentifizierung, Organisationserstellung, Konfiguration und die Verwaltung von Steuerbelegen sind direkt in 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 gibt, die für beide Umgebungen verwendet wird.
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, erzeugt LIVE-Ressourcen.
Ein Token, der mit einem TEST API Key erstellt wird, erzeugt TEST-Ressourcen — auch wenn die URL gleich bleibt.

In SIGN IT wird die Umgebung über die Basis-URL ausgewählt.
Sie müssen jeden Endpoint mit der richtigen Basis-URL aufrufen (test.api.fiskaly.com oder live.api.fiskaly.com), 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 X-Api-Version-Header enthalten.
Der Wert entspricht dem Veröffentlichungsdatum der Version. Dies gibt Ihnen die volle Kontrolle darüber, wann Sie zu einer neueren 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, wenn nötig, während Sie neue Kunden direkt mit der neuesten Version einbinden.

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, garantiert der X-Idempotency-Key, dass ein API-Aufruf idempotent verarbeitet 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 X-Scope-Identifier-Header ersetzt die Pfadparameter, die zuvor in der Management API verwendet wurden, um Beziehungen zwischen Ressourcen herzustellen.

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

Terminologiezuordnung: SIGN IT vs. SIGN DE

SIGN IT	SIGN DE	Erklärung
`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` oder `Taxpayer::INDIVIDUAL`	In Deutschland Teil der `managed_organization` (DSFINVK DE) oder `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 Standort(e) (z. B. Filialen) des Steuerpflichtigen.
`System::FISCAL_DEVICE`	`client`	Repräsentiert das POS-System / die Kasse, die für die Fiskalisierung verwendet wird.
`Subject::API_KEY`	`API key`	API-Key-Authentifizierungsobjekt, zur Autorisierung des Zugriffs verwendet.
`Record`	`transaction`	Repräsentiert einen auf der Kasse durchgeführten Vorgang. Erfordert immer zwei Aufrufe: ein `Record::INTENTION` und ein `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Markiert den Beginn eines Kaufvorgangs oder eines anderen einzelnen Ereignisses, das auf der Kasse verarbeitet wird.
`Record::TRANSACTION`	`Finish-Transaction`	Markiert den Abschluss eines Kaufvorgangs.

SIGN IT Schritt für Schritt

Erste Organization

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

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

POST: Create Token

Verwenden Sie diesen Token, um die Erstellung der Organisationsstruktur für Italien zu authentifizieren.
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 wird dieser Token nun benötigt, um Organization::UNIT-Ressourcen zu erstellen.

POST: Create Organization (UNIT)

Erstellen Sie eine Organization::UNIT (Organization vom Typ Unit), die Ihren ersten Kunden repräsentiert. Dies entspricht der managed_organization, die über die Management API 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 Steuerpflichtigendaten zur Taxpayer-Ressource, die vom Typ COMPANY oder INDIVIDUAL sein kann, je nachdem, ob der Steuerpflichtige eine juristische oder natürliche Person ist. Diese Details definieren Sie im Schritt Taxpayer (COMPANY / INDIVIDUAL) weiter unten.

POST: Create Subject (API Key)

Jeder Ihrer Kunden benötigt einen eigenen API Key, um Ressourcen im Scope seiner spezifischen Organization::UNIT 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 X-Scope-Identifier-Header.

Im Gegensatz zu SIGN DE werden die Informationen, 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: Create Token (scoped)

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

Mit dem zuvor erstellten API Key für die Organization::UNIT müssen Sie diesen beschränkten Token erstellen.
Er wird für alle Operationen verwendet, die innerhalb dieser spezifischen Organization::UNIT durchgeführt werden müssen.

POST: Create Taxpayer (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 und in zwei Hauptteile unterteilt:

Allgemeine Informationen (länderübergreifend geteilt):
Enthält gemeinsame Attribute wie Name und Adresse des Steuerpflichtigen.
Fiskalisierungsinformationen (länderspezifischer Abschnitt):
Enthält steuerliche Attribute, die durch nationale Vorschriften erforderlich sind, wie die Steuerpflichtigenkennzahl und steuerliche Zugangsdaten.
In Italien umfasst dies steuerliche Attribute wie die Steuernummer (Codice Fiscale) und die Mehrwertsteuernummer (Partita IVA), die durch nationale Vorschriften erforderlich sind.

PATCH: Update Taxpayer

Aktualisieren Sie den Zustand von ACQUIRED zu COMMISSIONED, um den Taxpayer zu aktivieren.

Im Gegensatz zu SIGN DE haben Taxpayer in SIGN IT ein state-Attribut.
Wenn ein Taxpayer erstellt wird, ist sein anfänglicher Zustand ACQUIRED.
Bevor er verwendet werden kann, muss der Taxpayer auf den Zustand COMMISSIONED aktualisiert werden.

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

Wenn ein Taxpayer nicht mehr genutzt wird, kann er auf den Zustand DECOMMISSIONED aktualisiert werden.
Dieser Schritt ist ebenfalls irreversibel und sollte nur durchgeführt werden, wenn sicher ist, dass der Kunde diesen Taxpayer nicht mehr verwenden wird.

Zusätzlich zu Zuständen hat jeder Taxpayer in SIGN IT ein mode-Attribut, das seinen Betriebsstatus definiert.

Wenn der Taxpayer sich im Zustand ACQUIRED oder DECOMMISSIONED befindet, ist sein Modus immer INACTIVE.
In diesem Modus kann die Ressource nicht verwendet werden.
Wenn der Taxpayer auf den Zustand COMMISSIONED aktualisiert wird, validiert der SIGN IT-Dienst automatisch alle erforderlichen Konfigurationen.
Bei Erfolg wechselt der Modus zu OPERATIVE.
Wenn der Taxpayer auf dauerhafte Fisconline-Zugangsdatenfehler stößt, wechselt der Modus automatisch zu DEGRADED. Die Wiederherstellung aus diesem Zustand erfordert, dass der Benutzer zunächst den Modus auf SUSPENDED setzt, die Fisconline-Zugangsdaten korrigiert und den Modus auf OPERATIVE zurücksetzt.
Der Modus SUSPENDED kann für Taxpayer im Zustand COMMISSIONED manuell über den updateTaxpayer-Endpoint gesetzt werden.
Dies ist nützlich, um steuerliche Operationen vorübergehend zu pausieren, zum Beispiel beim Aktualisieren von Zugangsdaten oder bei Wartungsarbeiten.

Zusammenfassung:

INACTIVE: Standardmodus für ACQUIRED und DECOMMISSIONED
OPERATIVE: Normaler Produktivmodus
DEGRADED: Automatisch vom SIGN IT-Dienst aufgrund dauerhafter Fisconline-Zugangsdatenfehler gesetzt.
SUSPENDED: Manueller Wartungsmodus

POST: Create Location

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

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

PATCH: Update Location

Aktualisieren Sie den Zustand der Location auf COMMISSIONED.

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

POST: Create System

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

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

PATCH: Update System

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

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

Das mode-Attribut spiegelt den Betriebszustand des Systems wider (zum Beispiel OPERATIVE, SUSPENDED oder DEGRADED). Diese Modi verhalten sich genauso wie für Taxpayer beschrieben.

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 bereit für den Produktionseinsatz.

Von diesem Punkt an beschreiben die folgenden Schritte die täglichen Steuervorgänge an der Kasse.
Dazu gehört die Erstellung und Verarbeitung von Steuerbelegen, die Verkäufe, Rückgaben und andere Ereignisse repräsentieren — äquivalent zu Transaktionen in SIGN DE, jedoch mit erweiterten Steuerdaten, wie es in Italien erforderlich ist.

Täglicher Betrieb an der Kasse

Sobald die Einrichtung abgeschlossen ist und alle Ressourcen in Betrieb genommen wurden, setzt sich der Fiskalisierungsprozess in SIGN IT mit dem täglichen Betrieb fort.
Diese Vorgänge repräsentieren die täglichen Geschäftsaktivitäten an der Kasse — wie die Ausstellung von Belegen, die Bearbeitung von Rückgaben oder die Handhabung von Stornierungen.

Während das Gesamtkonzept ähnlich wie bei SIGN DE ist, führt SIGN IT ein einheitliches und datumreicheres 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 zu gewährleisten.

POST: Create Record

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: ein Record vom Typ INTENTION und ein Record vom Typ TRANSACTION.

Teil A) INTENTION

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

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

Er enthält kontextuelle Informationen, die die Absicht des Vorgangs definieren, einschließlich:

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

Teil B) TRANSACTION

In SIGN DE wird eine Transaktion durch ein Finish-Transaction-Update der Transaktionsressource abgeschlossen.
In SIGN IT wird dieser Schritt durch eine separate Ressource dargestellt: ein Record vom Typ TRANSACTION.

Ein Record vom Typ TRANSACTION schließt den Steuervorgang ab und verweist auf den zuvor erstellten Record 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 breiter und orientieren sich stärker an den Informationen, die in einer Transaktion innerhalb eines Kassenabschlusses (DSFinV-K DE) enthalten sind.

Es enthält:

Dokumentinformationen wie Dokumentnummer, Datum sowie Brutto- und Nettogesamtbeträge.
Details für jede Verkaufszeile (Waren oder Dienstleistungen), einschließlich Beschreibung, Menge, Mehrwertsteuersatz und Betrag.
Verweise auf frühere Belege beim Erstellen von CORRECTION- oder CANCELLATION-Records.

Dieser Record-Typ liefert die vollständige steuerliche Darstellung der Transaktion gemäß den Anforderungen der italienischen Regulierung.

Record-Zustände und -Modi

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

Zustände

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

Modi

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

Übergänge

Übergang	Beschreibung
POST → Accepted	Der Record wird erstellt und geht vorübergehend in den `Accepted`-Zustand über, wenn die Validierung erfolgreich ist, und fährt sofort mit dem nächsten Schritt fort.
POST → Rejected	Der Record schlägt die interne Validierung fehl und wechselt automatisch zu `Rejected`, wobei Fehlerprotokolle bereitgestellt werden.
Accepted → Completed	Automatisch gesetzt, wenn die Verarbeitung erfolgreich abgeschlossen wird.
Accepted → Failed	Gesetzt, wenn die Verarbeitung aufgrund einer externen Komponente fehlschlägt.
Processing → Finished	Gibt an, dass die Verarbeitung abgeschlossen wurde, unabhängig vom Erfolg oder Misserfolg.

Dieses ereignisbasierte Design ermöglicht es, jeden Steuervorgang unabhängig zu verfolgen — ohne die gleiche Ressource zu aktualisieren — und stellt so einen transparenten, unveränderlichen Prüfpfad für jede Transaktion sicher.

Zusammenfassung

Im täglichen Betrieb ersetzt SIGN IT den einfachen „Start → Abschluss”-Transaktionsablauf von SIGN DE durch ein multi-ressourcenbasiertes, 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?