Für SIGN DE-Kunden

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

SIGN FR Integrierungsleitfaden für SIGN DE-Kunden

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

Einheitlicher API-Ansatz

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

Im Gegensatz zu SIGN DE erfordert SIGN FR keine separate Management API. Alle notwendigen Endpunkte für Authentifizierung, Asset-Erstellung, Konfiguration und Fiskal-Datensatz-Handhabung sind direkt in der SIGN FR API enthalten — was die Integrierung schneller und einfacher macht.

Umgebungen: TEST und LIVE

In SIGN FR 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-Schlüssel selbst, ob TEST- oder LIVE-Ressourcen erstellt werden.
Ein Token, das mit einem LIVE-API-Schlüssel erstellt wird, erzeugt LIVE-Ressourcen.
Ein Token, das mit einem TEST-API-Schlüssel erstellt wird, erzeugt TEST-Ressourcen — auch wenn die URL dieselbe bleibt.

In SIGN FR wird die Umgebung über die Basis-URL ausgewählt.
Sie müssen jeden Endpunkt mit der korrekten 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 einheitlichen API-Ansatz wurden einige neue HTTP-Header eingeführt, um Ihre Prozesse zu vereinfachen.
Sie bieten Flexibilität, gewährleisten Datenintegrität und machen Integrierungen 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 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 zu belassen, während neue Kunden direkt mit der neuesten Version eingebunden 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 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 Pfad-Parameter, die zuvor in der Management API verwendet wurden, um Beziehungen zwischen Ressourcen herzustellen.

Er macht Integrierungen sauberer und flexibler, da der Header explizit den Geltungsbereich definiert (zum Beispiel, zu welchem Asset::Unit ein API-Schlüssel gehört).

Terminologie-Mapping: SIGN FR vs. SIGN DE

SIGN FR	SIGN DE	Erläuterung
`Asset::Tenant`	(kein Äquivalent)	Struktur der obersten Ebene im fiskaly HUB. Repräsentiert das gesamte Kundenkonto. Kann nicht innerhalb anderer Assets verschachtelt werden.
`Asset::Group` (optional)	`organization` (mit `billing_options`)	Optionale Zwischenschicht zur Organisation mehrerer Steuerpflichtiger in logische Cluster.
`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. Läden) des Steuerpflichtigen.
`System::FISCAL_DEVICE`	`client`	Repräsentiert das für die Fiskalisierung verwendete Kassensystem / die Registrierkasse.
`Subject::API_KEY`	`API key`	API-Schlüssel-Authentifizierungsobjekt, zur Autorisierung des Zugangs verwendet.
`Record`	`transaction`	Repräsentiert einen Vorgang an der Registrierkasse. Bei besonderen Ereignissen kann er nur aus einer `Record::INTENTION` bestehen. Bei Transaktionen erfordert er immer zwei Aufrufe: eine `Record::INTENTION` und eine `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Markiert den Beginn eines Kaufvorgangs oder eines einzelnen anderen Ereignisses, das an der Registrierkasse verarbeitet wird.
`Record::TRANSACTION`	`Finish-Transaction`	Markiert den Abschluss (Ende) eines Kaufvorgangs.

SIGN FR Schritt für Schritt

Erste Organisation

Zunächst müssen Sie eine separate Organisation speziell für Frankreich im fiskaly HUB und einen dedizierten API-Schlüssel für die französische Integrierung erstellen.

Von diesem Punkt an werden alle Integrierungsschritte direkt über die SIGN FR API abgewickelt. Im Gegensatz zu SIGN DE müssen Sie die Management API nicht mehr für die Erstellung oder Verwaltung von Organisationsstrukturen verwenden. Die gesamte erforderliche Funktionalität ist Teil der SIGN FR API selbst.

POST: Token erstellen

Verwenden Sie dieses Token, um die Erstellung der Organisationsstruktur für Frankreich zu authentifizieren.
Es funktioniert genauso wie das Token in SIGN DE (Management API), das mit dem API-Schlüssel der (Haupt-)Organisation erstellt und dann zur Erstellung von managed_organizations verwendet wurde.
In SIGN FR ist dieses Token jetzt erforderlich, um Asset::Unit-Ressourcen zu erstellen.

POST: Asset (UNIT) erstellen

Erstellen Sie ein Asset::UNIT (Asset vom Typ Unit), das 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 des Asset::Unit erforderlich.
Im Gegensatz zu SIGN DE gehören die Steuerpflichtigen-Informationen zur Entity-Ressource, die vom Typ COMPANY oder INDIVIDUAL sein kann, je nachdem, ob der Steuerpflichtige eine juristische oder natürliche Person ist. Diese Details werden im Schritt Entity (COMPANY / INDIVIDUAL) unten definiert.

POST: Subject (API-Schlüssel) erstellen

Jeder Ihrer Kunden benötigt einen eigenen API-Schlüssel, um Ressourcen innerhalb seines spezifischen Asset::Unit-Bereichs zu erstellen.
Aus diesem Grund muss ein Subject::API_KEY (Subject vom Typ API-Schlüssel) erstellt werden.

Verknüpfen Sie Ihren API-Schlüssel 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-Schlüssel gehört, nicht mehr über den Pfad-Parameter, sondern über den Header-Parameter X-Scope-Identifier bereitgestellt.
Dieser Header muss die ID des Asset::UNIT enthalten, zu dem der API-Schlüssel gehört.

POST: Token erstellen (bereichsbezogen)

Dieses Token ist auf das Asset::Unit beschränkt. Verwenden Sie es für alle steuerpflichtigenspezifischen Vorgänge.

Mit dem zuvor erstellten API-Schlüssel für das Asset::Unit müssen Sie dieses bereichsbezogene Token erstellen.
Es wird für alle Vorgänge verwendet, die innerhalb dieses spezifischen Asset::Unit abgewickelt 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 FR dem einheitlichen API-Ansatz folgt, ist die Entity-Struktur standardisiert und in zwei Hauptteile untergliedert:

Allgemeine Informationen (länderübergreifend geteilt):
Dies umfasst gemeinsame Attribute wie Name und Adresse des Steuerpflichtigen.
Fiskalisierungsinformationen (länderspezifischer Abschnitt):
Dieser enthält steuerliche Attribute, die durch nationale Vorschriften erforderlich sind, wie die Steuerpflichtigennummer und steuerliche Anmeldedaten.
In Frankreich umfasst dies steuerliche Attribute wie die SIREN-Nummer und das Steuerjahrdatum, die durch nationale Vorschriften vorgeschrieben sind.

PATCH: Entity aktualisieren

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

Im Gegensatz zu SIGN DE haben Entities in SIGN FR ein Status-Attribut.
Wenn eine Entity erstellt wird, ist ihr anfänglicher Status ACQUIRED.
Bevor sie verwendet werden kann, muss die Entity auf den Status COMMISSIONED aktualisiert werden.

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

Wenn eine Entity nicht mehr genutzt wird, kann sie auf den Status DECOMMISSIONED aktualisiert werden.
Auch dieser Schritt ist unwiderruflich und sollte nur durchgeführt werden, wenn sicher ist, dass der Kunde diese Entity nicht mehr verwenden wird.

Zusätzlich zu den Status haben Entities in SIGN FR ein Modus-Attribut, das ihren Betriebsstatus definiert.

Wenn die Entity den Status ACQUIRED oder DECOMMISSIONED hat, ist ihr Modus immer INACTIVE.
In diesem Modus kann die Ressource nicht verwendet werden.
Wenn die Entity auf den Status COMMISSIONED aktualisiert wird, validiert der SIGN FR-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, bis das Problem behoben ist.
Sobald das Problem behoben wurde, gibt der SIGN FR-Dienst den Modus wieder auf OPERATIVE zurück.
Der Modus SUSPENDED kann manuell für Entities im Status COMMISSIONED über den Aktualisierungsendpunkt gesetzt werden.
Dies ist nützlich, um Fiskalvorgänge vorübergehend zu unterbrechen, zum Beispiel beim Aktualisieren von Anmeldedaten oder bei Wartungsarbeiten.
Wenn der SIGN FR-Dienst die Entity aufgrund eines Problems, das Benutzeraktionen erfordert, auf den Modus DEGRADED setzt, sollte der Modus zunächst auf SUSPENDED geändert werden, während die notwendigen Maßnahmen durchgeführt werden,
und dann wieder auf OPERATIVE aktualisiert werden, sobald das Problem behoben wurde.

Zusammenfassung:

INACTIVE: Standardmodus für ACQUIRED und DECOMMISSIONED
OPERATIVE: Normaler Produktivmodus
DEGRADED: Automatisch durch den SIGN FR-Dienst aufgrund eines Problems gesetzt
SUSPENDED: Manueller Wartungsmodus

POST: Entity erstellen (LOCATION)

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

Für jeden Standort eines Steuerpflichtigen sollte eine separate Entity vom Typ LOCATION erstellt werden.
In der SIGN FR-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

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

Wie bei Entity::COMPANY oder Entity::INDIVIDUAL muss auch die Entity::LOCATION auf den Status 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 Kassensystem oder eine Registrierkasse.
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 Aufbewahrungssystem selbst angegeben werden.
Die meisten dieser Details werden in der Regel vom Kassensystemanbieter definiert.
In Deutschland werden diese Informationen üblicherweise später im Rahmen des DSFinV-K DE- oder Submit DE-Prozesses hinzugefügt — in SIGN FR hingegen geschieht dies in einem einzigen Schritt während 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 eine Entity.
Sobald auf COMMISSIONED gesetzt, wird das System aktiv und die Abrechnung erfolgt automatisch (wenn in der LIVE-Umgebung verwendet).
Wenn es nicht mehr in Gebrauch ist, kann es auf DECOMMISSIONED gesetzt werden, was — wie in SIGN FR generell — unwiderruflich ist.

Das mode-Attribut spiegelt den Betriebszustand des Systems wider (zum Beispiel OPERATIVE, SUSPENDED oder DEGRADED).
Diese Modi verhalten sich genauso wie für Entity beschrieben, sodass Sie Vorgänge vorübergehend unterbrechen oder automatisch auf beeinträchtigte Leistung aufgrund von Konfigurationsproblemen hinweisen können.

Einrichtung abgeschlossen

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

Von diesem Punkt an beschreiben die folgenden Schritte die täglichen Fiskalvorgänge am Kassensystem.
Dies umfasst die Erstellung und Verarbeitung von Fiskaldatensätzen, die Verkäufe, Retouren und andere Ereignisse repräsentieren — äquivalent zu Transaktionen in SIGN DE, jedoch mit erweiterten Fiskaldaten, wie sie in Frankreich erforderlich sind.

Tägliche Vorgänge am Kassensystem

Sobald die Einrichtung abgeschlossen und alle Ressourcen in Betrieb genommen sind, setzt sich der Fiskalisierungsprozess in SIGN FR mit täglichen Vorgängen fort.
Diese Vorgänge repräsentieren die täglichen Geschäftsaktivitäten am Kassensystem — wie die Ausstellung von Quittungen, die Verarbeitung von Retouren oder die Bearbeitung von Stornierungen.

Obwohl das Gesamtkonzept ähnlich wie bei SIGN DE ist, führt SIGN FR ein einheitliches und datenreicheres Record-Modell ein.
Jede Transaktion wird als ein oder mehrere Records dargestellt, die digital signiert, journalisiert und archiviert werden, um vollständige Fiskalkonformität zu gewährleisten.

Die folgenden Abschnitte beschreiben, wie diese Records in der französischen Fiskalumgebung erstellt, verarbeitet und verwaltet werden.

POST: Record erstellen

In SIGN FR wird jede Fiskaltransaktion 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 Fiskalprozesses markiert und später auf einen abgeschlossenen Status aktualisiert wird.
In SIGN FR wird diese Logik durch eine dedizierte Ressource ersetzt: einen Record vom Typ INTENTION.

Ein Record vom Typ INTENTION markiert den Beginn einer Fiskaloperation oder führt direkt Operationen durch, die nur einen einzigen Schritt erfordern, wie EVENT, EXPORT oder DUPLICATE.
In Frankreich werden die Intentions-Operationen TRANSACTION, EVENT, EXPORT und DUPLICATE unterstützt.

Er enthält kontextuelle Informationen, die den Zweck der Operation definieren, einschließlich:

Das System (System::FISCAL_DEVICE), das die Operation durchführt.
Der Operationstyp, entsprechend einer der oben aufgeführten unterstützten Intentions-Operationen.

Teil B) TRANSACTION

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

Ein Record vom Typ TRANSACTION schließt die Fiskaloperation ab und referenziert den zuvor erstellten Record vom Typ INTENTION.
Er enthält alle steuerlichen und Transaktionsdaten, die für die Operation erforderlich sind.
Im Vergleich zu SIGN DE sind der Datenumfang und die Struktur breiter und sind enger an die Informationen angelehnt, die in einer Transaktion innerhalb eines Kassenabschlusses in DSFinV-K DE enthalten sind.

Er umfasst:

Dokumentinformationen wie Dokumentennummer, Datum und Bruttogesamtbeträge und Nettogesamtbeträge.
Details für jede Verkaufszeile (Waren oder Dienstleistungen), einschließlich Beschreibung, Menge, Mehrwertsteuersatz und Betrag.
Verweise auf frühere Quittungen bei der Erstellung von CORRECTION- oder CANCELLATION-Records.
Zusätzliche Operationstypen werden ebenfalls innerhalb von Record::TRANSACTION unterstützt, je nach Geschäftsprozess und Fiskalkontext.

Dieser Record-Typ bietet die vollständige Fiskaldarstellung der Transaktion, wie sie durch die französische Regulierung erforderlich ist.

Record-Status und -Modi

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

Status

Accepted – Der Record wurde empfangen, validiert und ist bereit zur Verarbeitung.
Rejected – Die Validierung ist fehlgeschlagen; Details sind in den Protokollmeldungen verfügbar.
Completed – Der Record wurde erfolgreich verarbeitet.
Failed – Der Record konnte aufgrund eines Fehlers mit einer externen Komponente nicht verarbeitet werden.

Modi

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

Übergänge

Übergang	Beschreibung
POST → Accepted	Der Record wird erstellt und tritt vorübergehend in den Status `Accepted` ein, wenn die Validierung erfolgreich ist, und geht sofort zum nächsten Schritt über.
POST → Rejected	Der Record besteht die Validierung nicht 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	Zeigt an, dass die Verarbeitung abgeschlossen wurde, unabhängig von Erfolg oder Misserfolg.

Dieses ereignisbasierte Design ermöglicht es, jede Fiskaloperation unabhängig zu verfolgen — ohne dieselbe Ressource zu aktualisieren — und stellt eine transparente, unveränderliche Prüfspur für jede Transaktion sicher.

Zusätzliche Vorgänge (nicht-transaktional)

Über den standardmäßigen INTENTION → TRANSACTION-Ablauf hinaus unterstützt SIGN FR auch nicht-transaktionale Fiskalvorgänge:

EVENT – Wird verwendet, um System- oder Konfigurationsereignisse zu protokollieren (zum Beispiel Schulungsmodus, Testoperationen oder Systemneustarts).
DUPLICATE – Erstellt ein Duplikat eines bestehenden Fiskaldokuments.
EXPORT – Generiert einen Fiskaldatenexport.

Diese Vorgänge werden als Records vom Typ INTENTION nur dargestellt und erfordern kein TRANSACTION-Gegenstück.
Sie erweitern die Fiskal-Rückverfolgbarkeit auf alle relevanten Kassensystemaktivitäten über Verkaufstransaktionen hinaus.

Zusammenfassung

Im täglichen Betrieb ersetzt SIGN FR den einfachen „Start → Ende”-Transaktionsablauf von SIGN DE durch ein multi-ressourcen-, ereignisgesteuertes Record-Modell.
Jede Operation — ob Verkauf, Korrektur, Export oder ein anderes Fiskalereignis — wird individuell signiert, journalisiert und archiviert, was vollständige Rückverfolgbarkeit und Konformität mit dem französischen Fiskalrecht gewährleistet.

Was this page helpful?