Die Unified API

Die fiskaly Unified API ist eine einheitliche Integrierungsarchitektur, die mehrere Länder abdeckt. Einmal für Frankreich oder Italien integrieren, und ein weiteres Land hinzufügen bedeutet, das Payload-Schema zu ändern — nicht die Integrierung neu zu schreiben.

Diese Seite dokumentiert, wie die Unified API funktioniert, wie ihr Ressourcenmodell aussieht und wie sie sich von den Spezialisierten APIs (SIGN DE, SIGN AT, SIGN ES) unterscheidet.

Zwei API-Architekturen

fiskaly bietet zwei API-Architekturen. Beide werden vollständig unterstützt und aktiv gepflegt:

	Unified API	Spezialisierte APIs
Länder	Frankreich (SIGN FR), Italien (SIGN IT), Schweden (folgt)	Deutschland (SIGN DE), Österreich (SIGN AT), Spanien (SIGN ES)
Basis-URLs	`test.api.fiskaly.com` / `live.api.fiskaly.com`	Produktspezifisch (z. B. `kassensichv.fiskaly.com`)
Organisationsverwaltung	In die Produkt-API integriert	Separate Management API (`management.fiskaly.com`)
Ressourcen-IDs	Server-generiert (verwenden Sie `X-Idempotency-Key`)	Client-generierte UUIDs
Versionsverwaltung	`X-Api-Version`-Header (datumsbasiert, keine Breaking Changes)	Kein Versions-Header (Breaking Changes möglich)
Ressourcen-Scoping	`X-Scope-Identifier`-Header	Pfad-Parameter
Terminologie	Organisation, Steuerpflichtiger, Standort, System, Datensatz	TSS, Client, Transaktion (variiert je Produkt)
Land hinzufügen	Payload-Schema innerhalb desselben Ressourcenmodells ändern	Separate API mit anderen Endpunkten integrieren

📘Keine der Architekturen ist veraltet

Die Spezialisierten APIs sind speziell für die länderspezifischen Regulierungen entwickelt. SIGN DE ist fiskaly’s ausgereiftestes Produkt mit über 10.000 Integrierungen und BSI-Zertifizierung gültig bis 2033. Die Unified API ist die Architektur, die fiskaly für eine effiziente Multi-Country-Expansion entwickelt hat.

Welche Architektur sollten Sie verwenden?

Szenario	Empfehlung
Sie benötigen nur Deutschland	SIGN DE (Spezialisierte API)
Sie benötigen nur Österreich	SIGN AT (Spezialisierte API)
Sie benötigen nur Spanien	SIGN ES (Spezialisierte API)
Sie benötigen nur Frankreich oder Italien	Unified API
Sie benötigen Frankreich + Italien (oder + Schweden)	Unified API — einmal integrieren, Länder per Payload-Schema hinzufügen
Sie benötigen Deutschland + Frankreich	Beide — SIGN DE (Spezialisiert) + SIGN FR (Unified). Gleiches Auth-Muster, unterschiedliche Ressourcenmodelle.
Sie starten neu und planen 3+ Länder	Beginnen Sie mit der Unified API für FR/IT, fügen Sie Spezialisierte APIs für DE/AT/ES nach Bedarf hinzu

Unified API Basis-URLs

Die Unified API verwendet separate Basis-URLs für jede Umgebung:

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

Dies unterscheidet sich von den Spezialisierten APIs (z. B. SIGN DE), wo eine einzelne Basis-URL verwendet wird und der API Key die Umgebung bestimmt.

Unified API Header

Jede Unified API-Anfrage enthält diese Header:

`X-Api-Version`

Bei jeder Anfrage erforderlich. Der Wert ist das Veröffentlichungsdatum der API-Version, auf die Sie abzielen (z. B. 2026-02-03).

X-Api-Version: 2026-02-03

Dies gibt Ihnen die volle Kontrolle darüber, wann Sie eine neue Version übernehmen. Sie können:

Eine neue Version in TEST testen, bevor Sie LIVE migrieren
Verschiedene Kunden gleichzeitig auf verschiedenen Versionen betreiben
Keine Breaking Changes innerhalb einer fixierten Version garantieren

`X-Idempotency-Key`

Bei allen POST- und PATCH-Anfragen erforderlich. Da Ressourcen-IDs server-generiert sind (nicht client-seitig wie in SIGN DE), stellt dieser Header sicher, dass wiederholte Anfragen keine doppelten Ressourcen erstellen.

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Verwenden Sie eine neue UUIDv4 oder UUIDv3 für jeden einzelnen Vorgang. Verwenden Sie einen neuen Key beim Wiederholen einer fehlgeschlagenen Anfrage.

`X-Scope-Identifier`

Wird verwendet, um Ressourcenbeziehungen herzustellen. Ersetzt die Pfad-Parameter, die in der Management API und den Spezialisierten APIs verwendet werden.

X-Scope-Identifier: organization-unit-id

Wenn Sie beispielsweise einen API Key für eine bestimmte Organization::UNIT erstellen, enthält der X-Scope-Identifier-Header die ID der Unit, anstatt sie im URL-Pfad zu kodieren.

Ressourcenmodell

Die Unified API verwendet eine standardisierte Ressourcenhierarchie über alle Länder hinweg:

Organization::ACCOUNT       ← Ihr Unternehmen (oberste Ebene, verwaltet in HUB)
  │
  └── Organization::GROUP   ← Logisches Cluster (Region, Marke, Franchise)
        │
        └── Organization::UNIT   ← Einzelner Händler / Steuerpflichtiger
              │
              ├── Subject::API_KEY   ← API-Zugangsdaten für diese Unit
              │
              ├── Taxpayer (COMPANY oder INDIVIDUAL)
              │     │
              │     ├── Allgemeine Informationen (Name, Adresse — länderübergreifend)
              │     │
              │     └── Fiskalisierungs-Informationen (länderspezifisch: SIREN für FR,
              │         Codice Fiscale für IT, usw.)
              │
              ├── Location   ← Physischer Geschäftsstandort (Filiale, Geschäft)
              │
              └── System::FISCAL_DEVICE   ← POS-Terminal / Kasse

Ressourcenzustände

Jede wichtige Ressource (Steuerpflichtiger, Standort, System) folgt demselben Zustandsautomaten:

ACQUIRED ──→ COMMISSIONED ──→ DECOMMISSIONED
(erstellt)      (aktiv)          (außer Betrieb)

ACQUIRED — Ressource ist erstellt, aber noch nicht aktiv. Modus: INACTIVE.
COMMISSIONED — Ressource ist aktiv und produktionsbereit. Modus: OPERATIVE. Dieser Übergang ist irreversibel und startet die Abrechnung.
DECOMMISSIONED — Ressource ist dauerhaft außer Betrieb. Modus: INACTIVE. Ebenfalls irreversibel.

Betriebsmodi innerhalb des COMMISSIONED-Zustands:

Modus	Bedeutung	Gesetzt durch
`OPERATIVE`	Normaler Betrieb	Automatisch (bei Inbetriebnahme oder nach Problemlösung)
`DEGRADED`	Problem erkannt	Automatisch (durch den Dienst)
`SUSPENDED`	Wartungspause	Manuell (durch Sie, per API)

Datensätze (das Transaktionsmodell)

In der Unified API werden Transaktionen Records genannt und verwenden ein zweistufiges Modell:

Record::INTENTION — markiert den Beginn eines Fiskalsatzes (entspricht Start-Transaction in SIGN DE)
Record::TRANSACTION — schließt den Fiskalsatz mit vollständigem Payload ab (entspricht Finish-Transaction in SIGN DE)

Weitere Vorgangstypen werden nur über Record::INTENTION unterstützt (kein TRANSACTION-Gegenstück erforderlich):

EVENT — Systemereignisse (Trainingsmodus, Testbetrieb, Neustarts)
DUPLICATE — Duplikat eines vorhandenen Fiskaldokuments
EXPORT — Generierung von Fiskaldatenexporten

📘Nicht alle Vorgänge sind in jedem Land verfügbar

Frankreich unterstützt TRANSACTION, EVENT, DUPLICATE und EXPORT-Intentionen. Italien unterstützt derzeit nur TRANSACTION. Prüfen Sie die länderspezifische Dokumentation für die vollständige Liste.

Terminologie-Mapping (Unified API vs. SIGN DE)

Wenn Sie von einer SIGN DE-Integrierung kommen, ordnet diese Tabelle die Konzepte zu:

Unified API	SIGN DE	Erläuterung
`Organization::ACCOUNT`	(kein Äquivalent)	Struktur der obersten Ebene in HUB
`Organization::GROUP`	`organization`	Hauptorganisation, unter der Steuerpflichtige geschachtelt sind
`Organization::UNIT`	`managed_organization`	Einzelner Händler. Verknüpft mit einem Steuerpflichtigen.
`Taxpayer` (COMPANY/INDIVIDUAL)	Teil von `managed_organization` oder `taxpayer` (SUBMIT DE)	Die fiskalische Entität
`Location`	`establishment` (SUBMIT DE)	Physischer Geschäftsstandort
`System::FISCAL_DEVICE`	`client`	POS-Terminal / Kasse
`Subject::API_KEY`	`API key`	Authentifizierungs-Zugangsdaten
`Record`	`transaction`	Ein Fiskalvorgang
`Record::INTENTION`	Start-Transaction	Markiert den Beginn eines Kaufvorgangs
`Record::TRANSACTION`	Finish-Transaction	Schließt den Kauf mit vollständigen Fiskaldaten ab

Was sich je Land ändert

Der Mehrwert der Unified API liegt darin, dass der Großteil der Integrierung geteilt wird. Hier ist, was gleich bleibt und was sich unterscheidet:

Für alle Unified API-Länder gemeinsam	Länderspezifisch
Authentifizierung (`POST /tokens`)	Abschnitt `fiscalization` des Steuerpflichtigen (z. B. SIREN für FR; Steuer-ID, USt-ID und Zugangsdaten für IT)
Organisationshierarchie (ACCOUNT > GROUP > UNIT)	Record-Payload-Schema (Belegstruktur, Mehrwertsteuer-Handling, Dokumenttypen)
Header (X-Api-Version, X-Idempotency-Key, X-Scope-Identifier)	Unterstützte Intentions-Vorgänge (FR hat EVENT/DUPLICATE/EXPORT; IT hat nur TRANSACTION)
Ressourcen-Lebenszyklus (ACQUIRED > COMMISSIONED > DECOMMISSIONED)	Regulatorische Anforderungen (NF525-Zertifizierung für FR, Belegslotterie für IT)
Zustands- und Modusverwaltung (OPERATIVE, DEGRADED, SUSPENDED)	Verbindungsverlust-Handling (unterschiedliche Protokolle je Land)
Basis-URLs (test.api.fiskaly.com / live.api.fiskaly.com)	—

Typischer Aufwand zum Hinzufügen eines zweiten Unified API-Landes: ~1 Woche für ein Team, das bereits das erste Land integriert hat. Sie passen den Abschnitt fiscalization des Steuerpflichtigen und das Record-Payload-Schema an — alles andere ist wiederverwendbar.

Integrierungs-Komplettanleitung

Hier ist der vollständige Einrichtungsablauf für ein Unified API-Land (mit SIGN FR als Beispiel). Der Ablauf ist für SIGN IT identisch.

Token erstellen
POST /tokens mit Ihrem API Key und Secret (wie bei allen fiskaly-Produkten). Dieser Token wird verwendet, um die Organisationsstruktur zu erstellen.
Organization::UNIT erstellen
POST /organizations mit X-Idempotency-Key. An diesem Punkt ist nur der Name erforderlich. Dies repräsentiert Ihren Kunden (Händler).
Subject::API_KEY erstellen
POST /subjects mit X-Scope-Identifier auf die Organization::UNIT-ID gesetzt. Jeder Kunde benötigt einen eigenen API Key.
Scoped Token erstellen
POST /tokens mit dem API Key des Kunden. Dieser Scoped Token wird für alle steuerpflichtigenbezogenen Vorgänge verwendet.
Steuerpflichtigen erstellen
POST /taxpayers mit allgemeinen Informationen (Name, Adresse) und dem länderspezifischen Abschnitt fiscalization (z. B. SIREN-Nummer für Frankreich, Steuer-ID, USt-ID und Zugangsdaten für IT).
Steuerpflichtigen in Betrieb nehmen
PATCH /taxpayers/{id} — Zustand von ACQUIRED auf COMMISSIONED aktualisieren. Dies ist irreversibel und aktiviert die Abrechnung.
Standort erstellen und in Betrieb nehmen
POST /locations dann PATCH /locations/{id} zur Inbetriebnahme. Repräsentiert einen physischen Geschäftsstandort.
System erstellen und in Betrieb nehmen
POST /systems dann PATCH /systems/{id} zur Inbetriebnahme. Repräsentiert ein POS-Terminal. In SIGN FR geben Sie hier auch Details zum elektronischen Kassensystem an.
Record::INTENTION erstellen
POST /records mit Vorgangstyp (z. B. TRANSACTION) und der System-ID. Dies startet den Fiskalvorgang.
Record::TRANSACTION erstellen
POST /records mit Verweis auf den INTENTION-Datensatz. Enthält den vollständigen Fiskal-Payload (Positionen, Beträge, Mehrwertsteuer, Zahlungsmethoden). Die Antwort enthält die kryptografische Signatur.

Keine separate Management API

Im Gegensatz zu den Spezialisierten APIs (SIGN DE, SIGN AT, SIGN ES) erfordert die Unified API keine Management API (management.fiskaly.com). Die gesamte Organisationsverwaltung, API-Key-Erstellung und Konfiguration wird direkt innerhalb der Produkt-API abgewickelt.

Das bedeutet weniger zu integrierende API-Oberflächen, weniger zu verwaltende Zugangsdaten und eine insgesamt einfachere Architektur.

Länder auf der Unified API

Frankreich (SIGN FR)

NF525-Zertifizierung, Periodenabschlüsse, Offline-Replay, Archive

Italien (SIGN IT)

Cloudbasierte APIs für die Fiskalbeleg-Übermittlung an die italienische Steuerbehörde (AdE).

Schweden (SIGN SE)

InfraSec TCS — wird derzeit in die Unified API integriert

Länder auf Spezialisierten APIs

Deutschland (SIGN DE)

BSI-zertifiziertes Cloud-TSS, KassenSichV, DSFinV-K, SUBMIT DE

Österreich (SIGN AT)

RKSV-Konformität, SCU-basierte Signierung, FinanzOnline-Registrierung

Spanien (SIGN ES)

TicketBAI + Verifactu + SII aus einer API, XML-Rechnungssignierung

Nächste Schritte

SIGN FR für SIGN DE-Kunden

Detaillierter Migrationsleitfaden mit schrittweisen API-Aufrufen

SIGN IT für SIGN DE-Kunden

Detaillierter Migrationsleitfaden mit schrittweisen API-Aufrufen

Integrierungsplanung

Aufwandsschätzungen, Zeitpläne und Konformitäts-Checklisten

Was this page helpful?

Die Unified API

Zwei API-Architekturen

Welche Architektur sollten Sie verwenden?

Unified API Basis-URLs

Unified API Header

X-Api-Version

X-Idempotency-Key

X-Scope-Identifier

Ressourcenmodell

Ressourcenzustände

Datensätze (das Transaktionsmodell)

Terminologie-Mapping (Unified API vs. SIGN DE)

Was sich je Land ändert

Integrierungs-Komplettanleitung

Token erstellen

Organization::UNIT erstellen

Subject::API_KEY erstellen

Scoped Token erstellen

Steuerpflichtigen erstellen

Steuerpflichtigen in Betrieb nehmen

Standort erstellen und in Betrieb nehmen

System erstellen und in Betrieb nehmen

Record::INTENTION erstellen

Record::TRANSACTION erstellen