Produktübergreifendes Ressourcen-Mapping

Diese Referenz zeigt, wie Schlüsselkonzepte über fiskaly’s API-Architekturen hinweg abgebildet werden. Verwenden Sie sie bei der Migration zwischen Produkten oder beim Integrieren mehrerer Länder.

Ressourcen-Mapping-Tabelle

Konzept	SIGN DE (Spezialisiert)	Unified API (FR/IT)	Management API
Oberste Entität	Organisation (über HUB)	Organisation `GROUP`	Organisation
Geschäftseinheit	Verwaltete Organisation	Organisation `UNIT`	Verwaltete Organisation
Signing-Gerät	TSS (Technisches Sicherheitssystem)	System `FISCAL_DEVICE`	—
POS-Terminal	Client	— (implizit über System)	—
Transaktion	Transaktion (PUT mit Zustand)	Datensatz (Intention → Transaktion)	—
Steuerliche Entität	— (über SUBMIT DE)	Steuerpflichtiger (`COMPANY` / `INDIVIDUAL`)	—
Standort	— (über DSFinV-K)	Standort `BRANCH`	—
Zugangsdaten	API Key + Secret (HUB)	Subject `API_KEY` (API)	API Key (HUB)
Auth-Endpunkt	`POST /api/v2/auth`	`POST /api/v1/auth/token`	`POST /api/v0/auth`
Ressourcen-IDs	Client-generierte UUID	Server-generiert	Client-generierte UUID
Idempotenz	PUT mit UUID in URL	`X-Idempotency-Key`-Header	PUT mit UUID in URL

Lebenszyklus-Zustände

Ressourcen in jeder Architektur folgen unterschiedlichen Zustandsautomaten:

SIGN DE — TSS-Zustände

UNINITIALIZED → INITIALIZED → DISABLED

Vor der Initialisierung muss Admin-PIN gesetzt und authentifiziert werden
Kann nach Deaktivierung nicht wieder aktiviert werden

Unified API — Ressourcenzustände

ACQUIRED → COMMISSIONED → DECOMMISSIONED

Gilt für: Steuerpflichtiger, Standort, System

Ressourcen werden im Zustand ACQUIRED erstellt
Müssen auf COMMISSIONED aktualisiert werden, bevor sie betrieblich verwendet werden können
DECOMMISSIONED ist endgültig

SIGN DE — Transaktionszustände

ACTIVE (Revision 1) → FINISHED (Revision 2)

Unified API — Datensatz-Ablauf

INTENTION → TRANSACTION

Zwei separate API-Aufrufe erforderlich
Transaktion referenziert die Intention anhand der ID

Einrichtungssequenz-Vergleich

SIGN DE (Deutschland)

Organisation erstellen (HUB)
API Key generieren (HUB)
Authentifizieren (POST /auth)
TSS erstellen (PUT /tss/{id})
TSS initialisieren (Admin-PIN → Auth → Zustandsänderung)
Client erstellen (PUT /tss/{id}/client/{id})
Transaktion erstellen (PUT /tss/{id}/tx/{id})

Unified API (Frankreich/Italien)

Im HUB registrieren
Organisation GROUP erstellen (HUB)
API Key generieren (HUB)
Token erstellen (POST /auth/token)
Organisation UNIT erstellen
Subject API_KEY erstellen
Token (für UNIT) erstellen
Steuerpflichtigen erstellen → In Betrieb nehmen
Standort erstellen → In Betrieb nehmen
System erstellen → In Betrieb nehmen
Datensatz erstellen (Intention → Transaktion)

📘Mehr Schritte, mehr Struktur

Die Unified API hat mehr Einrichtungsschritte, da sie direkt in der Produkt-API Organisationsverwaltung (GROUP/UNIT-Hierarchie), Steuerpflichtigen-Daten und Standort-Tracking enthält — Funktionen, die SIGN DE durch separate Produkte (Management API, SUBMIT DE, DSFinV-K) abwickelt.

Wesentliche Unterschiede

Aspekt	Spezialisierte APIs	Unified API
Basis-URLs	Pro Produkt (z. B. `kassensichv.fiskaly.com`)	Geteilt (`test.api.fiskaly.com`)
Organisationsverwaltung	Über Management API + HUB	In Produkt-API integriert
Ressourcenerstellung	PUT mit client-generierter UUID	POST mit server-generierter ID
Versionierung	URL-Pfad (`/api/v2`)	Header (`X-Api-Version: 2026-02-03`)
Scoping	Implizit (über Auth-Token)	Explizit (`X-Scope-Identifier`-Header)
Transaktionsmodell	Einzelne Ressource mit Zustandsänderungen	Zweistufig: Intention, dann Transaktion