Für SIGN DE-Kunden

SIGN FR-Integrationshandbuch 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 FR API. Er beschreibt alle notwendigen Schritte für Sie und Ihre Händler.

Unified-API-Ansatz

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

Im Gegensatz zu SIGN DE erfordert SIGN FR keine separate Management API. Alle notwendigen Endpunkte für Authentifizierung, Organisationserstellung, Konfiguration und Fiskalaufzeichnungen sind direkt in SIGN FR enthalten – was die Integration 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 mit einem LIVE-API-Schlüssel erstelltes Token erstellt LIVE-Ressourcen.
Ein mit einem TEST-API-Schlüssel erstelltes Token erstellt 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 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 auf eine neuere Version umsteigen, 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, 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 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 X-Scope-Identifier-Header ersetzt die Path-Parameter, die zuvor in der Management API verwendet wurden, um Beziehungen zwischen Ressourcen herzustellen.

Er macht Integrationen sauberer und flexibler, da der Header explizit den Geltungsbereich definiert (z. B. zu welchem Organization::Unit ein API-Schlüssel gehört).

Terminologie-Zuordnung: SIGN FR vs. SIGN DE

SIGN FR	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 `taxpayer` (SUBMIT DE)	Definiert den Steuerpflichtigen für die verknüpfte `Organization::UNIT`, der zur Erfüllung steuerlicher Pflichten erforderlich ist.
`Location`	Vergleichbar: `establishment` (SUBMIT DE)	Repräsentiert physische Standorte (z. B. Geschäfte), die vom Steuerpflichtigen betrieben werden.
`System::FISCAL_DEVICE`	`client`	Repräsentiert die POS/Kasse, die für die Fiskalisierung verwendet wird.
`Subject::API_KEY`	`API key`	API-Schlüssel-Authentifizierungsobjekt, das zur Autorisierung des Zugriffs verwendet wird.
`Record`	`transaction`	Repräsentiert einen an der Kasse durchgeführten Vorgang. Bei Sonderereignissen kann es nur aus einer `Record::INTENTION` bestehen. Bei Transaktionen sind immer zwei Aufrufe erforderlich: eine `Record::INTENTION` und eine `Record::TRANSACTION`.
`Record::INTENTION`	`Start-Transaction`	Markiert den Beginn eines Kaufvorgangs oder eines einzelnen anderen Ereignisses, das an der Kasse verarbeitet wird.
`Record::TRANSACTION`	`Finish-Transaction`	Markiert den Abschluss eines Kaufvorgangs.

SIGN FR Schritt für Schritt

Erste Organisation

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

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

POST: Token erstellen

Verwenden Sie dieses Token zur Authentifizierung bei der Erstellung der Organisationsstruktur für Frankreich.
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 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 API für SIGN DE erstellt wurde.

In diesem Schritt ist nur der Name der Organization::UNIT erforderlich.
Im Gegensatz zu SIGN DE gehört die Steuerpflichtigeninformation 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 Steuerpflichtiger (COMPANY / INDIVIDUAL) unten.

POST: Subject (API-Schlüssel) erstellen

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

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

POST: Token erstellen (bereichsbezogen)

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

Mit dem zuvor erstellten API-Schlüssel für die Organization::UNIT müssen Sie dieses bereichsbezogene Token erstellen.
Es wird für alle Vorgänge 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 den Steuerpflichtigen – entweder eine juristische Person (Unternehmen) oder eine natürliche Person (Einzelunternehmer).
Jeder Steuerpflichtige muss erstellt werden, bevor steuerliche Vorgänge durchgeführt werden können.

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

Allgemeine Informationen (länderübergreifend geteilt):
Diese umfassen gemeinsame Attribute wie Name und Adresse des Steuerpflichtigen.
Fiskalisierungsinformationen (länderspezifischer Abschnitt):
Dieser enthält steuerliche Attribute, die von nationalen Vorschriften verlangt werden, wie die Steuernummer und die Fiskaldaten.
In Frankreich umfasst dies steuerliche Attribute wie die SIREN-Nummer und das Fiskaljahrdatum, die von nationalen Vorschriften verlangt werden.

PATCH: Steuerpflichtigen aktualisieren

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

Im Gegensatz zu SIGN DE haben Steuerpflichtige in SIGN FR ein Status-Attribut.
Wenn ein Steuerpflichtiger erstellt wird, ist sein Ausgangsstatus ACQUIRED.
Bevor er verwendet werden kann, muss der Steuerpflichtige auf den Status COMMISSIONED aktualisiert werden.

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

Wenn ein Steuerpflichtiger nicht mehr verwendet wird, kann er auf den Status DECOMMISSIONED aktualisiert werden.
Auch dieser Schritt ist unwiderruflich und sollte nur durchgeführt werden, wenn sicher ist, dass der Kunde diesen Steuerpflichtigen nicht mehr verwenden wird.

Zusätzlich zu den Status hat jeder Steuerpflichtige in SIGN FR 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 FR-Dienst automatisch alle erforderlichen Konfigurationen.
Bei Erfolg wechselt der Modus zu OPERATIVE.
Wenn es ein Problem mit dem Steuerpflichtigen oder einer seiner abhängigen Ressourcen gibt, wechselt der Modus automatisch zu DEGRADED, bis das Problem behoben ist.
Sobald das Problem behoben wurde, setzt der SIGN FR-Dienst den Modus auf OPERATIVE zurück.
Der Modus SUSPENDED kann für Steuerpflichtige im Status COMMISSIONED manuell über den Aktualisierungsendpunkt gesetzt werden.
Dies ist nützlich, um den Fiskalbetrieb vorübergehend zu unterbrechen, zum Beispiel beim Aktualisieren von Anmeldedaten oder bei Wartungsarbeiten.
Wenn der SIGN FR-Dienst den Steuerpflichtigen aufgrund eines Problems, das Benutzeraktion erfordert, auf den Modus DEGRADED setzt, sollte der Modus zunächst auf SUSPENDED geändert werden, während die notwendigen Maßnahmen ergriffen 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 vom SIGN FR-Dienst aufgrund eines Problems gesetzt
SUSPENDED: Manueller Wartungsmodus

POST: Standort erstellen

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

Für jeden Standort eines Steuerpflichtigen sollte ein separater Location erstellt werden.
In der SIGN FR-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 einen zugehörigen Location haben.

PATCH: Standort aktualisieren

Aktualisieren Sie den Status des Location auf COMMISSIONED.

Wie bei Taxpayer::COMPANY oder Taxpayer::INDIVIDUAL muss auch der Location auf den Status COMMISSIONED aktualisiert werden, bevor er 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 eine Kasse.
Es entspricht dem Client in SIGN DE.
Jedes System ist mit einem Location verknüpft.

Im Gegensatz zu SIGN DE müssen beim Erstellen eines FISCAL_DEVICE zusätzliche Informationen über das elektronische Kassensystem selbst bereitgestellt werden.
Die meisten dieser Details werden in der Regel vom POS-Anbieter definiert.
In Deutschland werden diese Informationen normalerweise später im Rahmen des DSFinV-K DE- oder Submit DE-Prozesses hinzugefügt – in SIGN FR 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 wurde, 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 FR generell – unwiderruflich ist.

Das mode-Attribut spiegelt den Betriebszustand des Systems wider (z. B. OPERATIVE, SUSPENDED oder DEGRADED).
Diese Modi verhalten sich genauso wie für Taxpayer beschrieben und ermöglichen es Ihnen, den Betrieb vorübergehend zu unterbrechen oder eine beeinträchtigte Leistung aufgrund von Konfigurationsproblemen automatisch anzuzeigen.

Einrichtung abgeschlossen

Mit dem erfolgreich in Betrieb genommenen System ist die erste Einrichtungsphase abgeschlossen.
Alle organisatorischen und steuerlichen Strukturen – von Organization::UNIT über Taxpayer bis hin zu System – sind nun aktiv und bereit für den Produktionsbetrieb.

Von diesem Punkt an beschreiben die folgenden Schritte die täglichen Fiskalvorgänge an der Kasse.
Dazu gehören das Erstellen und Verarbeiten von Fiskalaufzeichnungen, die Verkäufe, Retouren und andere Ereignisse repräsentieren – entsprechend den Transaktionen in SIGN DE, jedoch mit erweiterten Fiskaldaten gemäß den Anforderungen in Frankreich.

Tägliche Vorgänge an der Kasse

Sobald die Einrichtung abgeschlossen und alle Ressourcen in Betrieb genommen sind, wird der Fiskalisierungsprozess in SIGN FR mit täglichen Vorgängen fortgesetzt.
Diese Vorgänge repräsentieren die täglichen Geschäftsaktivitäten an der Kasse – wie das Ausstellen von Belegen, die Verarbeitung von Retouren oder die Handhabung von Stornierungen.

Während das Gesamtkonzept SIGN DE ähnelt, führt SIGN FR ein einheitliches und datengereichteres Record-Modell ein.
Jede Transaktion wird als eine oder mehrere Records dargestellt, die digital signiert, journalisiert und archiviert werden, um vollständige Fiskal-Compliance 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 eine oder mehrere Records dargestellt.
Dieses Modell ersetzt den zweistufigen Transaktionsaktualisierungsprozess von SIGN DE (ACTIVE → FINISHED) durch zwei unabhängige Ressourcen: eine Record vom Typ INTENTION und eine weitere 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: eine Record vom Typ INTENTION.

Eine Record vom Typ INTENTION markiert den Beginn eines Fiskalvorgangs oder führt direkt Vorgänge durch, die nur einen einzigen Schritt erfordern, wie EVENT, EXPORT oder DUPLICATE.
In Frankreich werden folgende Intention-Vorgänge unterstützt: TRANSACTION, EVENT, EXPORT und DUPLICATE.

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

Das System (System::FISCAL_DEVICE), das den Vorgang durchführt.
Der Vorgangstyp, entsprechend einem der oben aufgeführten unterstützten Intention-Vorgänge.

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: eine Record vom Typ TRANSACTION.

Eine Record vom Typ TRANSACTION schließt den Fiskalvorgang ab und referenziert die zuvor erstellte Record vom Typ INTENTION.
Sie enthält alle steuerlichen und transaktionalen Daten, die für den Vorgang erforderlich sind.
Im Vergleich zu SIGN DE sind Datenumfang und -struktur umfangreicher und stärker an die Informationen ausgerichtet, die in einer Transaktion innerhalb eines Kassenabschlusses in DSFinV-K DE enthalten sind.

Sie umfasst:

Dokumentinformationen wie Dokumentnummer, Datum sowie Gesamt-Brutto- und -Nettobetrag.
Details für jede Verkaufsposition (Waren oder Dienstleistungen), einschließlich Beschreibung, Menge, MwSt.-Satz und Betrag.
Referenzen auf frühere Belege bei der Erstellung von CORRECTION- oder CANCELLATION-Records.
Weitere Vorgangstypen werden ebenfalls innerhalb von Record::TRANSACTION unterstützt, abhängig vom Geschäftsprozess und fiskalischen Kontext.

Dieser Record-Typ liefert die vollständige fiskalische Darstellung der Transaktion, wie sie von der französischen Regulierung gefordert wird.

Record-Status und -Modi

Jede Record in SIGN FR (ob INTENTION, TRANSACTION oder andere Typen) folgt ihrem eigenen Status und Modus, der ihren Lebenszyklus innerhalb des Fiskalisierungsprozesses widerspiegelt.

Status

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

Modi

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

Übergänge

Übergang	Beschreibung
POST → Accepted	Die 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	Die Record schlägt bei der Validierung fehl und wechselt automatisch zu `Rejected`, wobei Fehlerprotokolle bereitgestellt werden.
Accepted → Completed	Automatisch gesetzt, wenn die Verarbeitung erfolgreich abgeschlossen wurde.
Accepted → Failed	Gesetzt, wenn die Verarbeitung aufgrund einer externen Komponente fehlschlägt.
Processing → Finished	Gibt an, dass die Verarbeitung abgeschlossen wurde, unabhängig von Erfolg oder Misserfolg.

Dieses ereignisbasierte Design ermöglicht es, jeden Fiskalvorgang unabhängig zu verfolgen – ohne dieselbe Ressource zu aktualisieren – und gewährleistet so eine transparente, unveränderliche Prüfspur für jede Transaktion.

Zusätzliche Vorgänge (Nicht-Transaktionale)

Über den Standard-INTENTION → TRANSACTION-Ablauf hinaus unterstützt SIGN FR auch nicht-transaktionale Fiskolvorgänge:

EVENT – Wird verwendet, um System- oder Konfigurationsereignisse zu protokollieren (z. B. Trainingsmodus, Testbetrieb oder Systemneustarts).
DUPLICATE – Erstellt ein Duplikat eines vorhandenen Fiskaldokuments.
EXPORT – Generiert einen Fiskaldatenexport.

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

Zusammenfassung

Im täglichen Betrieb ersetzt SIGN FR den einfachen „Start → Finish”-Transaktionsablauf von SIGN DE durch ein multi-ressourcen-, ereignisgesteuertes Record-Modell.
Jeder Vorgang – ob Verkauf, Korrektur, Export oder ein anderes Fiskaleregnis – wird individuell signiert, journalisiert und archiviert, um vollständige Rückverfolgbarkeit und Compliance mit dem französischen Fiskalrecht zu gewährleisten.

Was this page helpful?