Kernkonzepte

Bevor Sie ein fiskaly-Produkt integrieren, hilft es, die Bausteine der Plattform zu verstehen. Diese Konzepte gelten für alle Länder und Produkte.

Organisationen

fiskaly verwendet ein hierarchisches Organisationsmodell, um Ihre Unternehmensstruktur abzubilden:

🏢

Account

Ihre übergeordnete Entität. Wird bei der Registrierung im HUB erstellt. Repräsentiert den POS-Anbieter oder Händler.

📂

Gruppe

Eine mittlere Ebene, die es Ihnen ermöglicht, mehrere Einheiten zu bündeln. Nützlich zur Organisation nach Region oder Marke.

🏪

Einheit

Repräsentiert einen einzelnen Händler oder eine juristische Person. Jede Einheit hat eigene Steuerpflichtigen-Daten und Fiskalressourcen.

In neueren APIs (SIGN IT, SIGN FR, E-Invoice) werden diese GROUP- und UNIT-Organisationstypen genannt. In SIGN DE dienen verwaltete Organisationen demselben Zweck.

Umgebungen

Jedes fiskaly-Konto verfügt über zwei isolierte Umgebungen:

Umgebung	Zweck	Daten
TEST	Integrierungsentwicklung und -tests	Simuliert — keine Verbindung zu Steuerbehörden
LIVE	Produktionsbetrieb	Real — Transaktionen werden an Steuerbehörden gemeldet

⚠️LIVE ist dauerhaft

In der LIVE-Umgebung erstellte Datensätze sind rechtlich bindend und werden an Steuerbehörden übermittelt. Entwickeln und testen Sie stets zuerst in der TEST-Umgebung.

In TEST generierte API Keys erstellen TEST-Ressourcen; in LIVE generierte Keys erstellen LIVE-Ressourcen. Die beiden Umgebungen sind vollständig getrennt — es findet keine Datenweitergabe zwischen ihnen statt.

Authentifizierung

Alle fiskaly-APIs verwenden JWT-basierte Authentifizierung:

POST /auth  (or POST /tokens)
  { "api_key": "...", "api_secret": "..." }
    → { "access_token": "...", "refresh_token": "..." }

Token	Gültigkeit	Verwendung
access_token	24 Stunden	Als Authorization: Bearer <token> in allen API-Anfragen einfügen
refresh_token	48 Stunden	Zum Abrufen eines neuen Access-Tokens ohne erneute Authentifizierung verwenden

💡Token zwischenspeichern

Authentifizieren Sie sich nicht bei jeder Anfrage neu. Cachen Sie den Access-Token und erneuern ihn nur, wenn Sie eine 401-Antwort erhalten. Eine erneute Authentifizierung bei jedem Aufruf verursacht unnötige Latenz im Kassierprozess.

Scoped-Authentifizierung (SIGN IT, SIGN FR, E-Invoice)

Neuere APIs verwenden zusätzliche Header, um Anfragen auf eine bestimmte Organisation zu beschränken:

Header	Zweck
Authorization: Bearer <token>	Authentifizierung
X-Api-Version: 2026-02-03	API-Versionsauswahl
X-Scope-Identifier: <org_id>	Anfragen auf eine bestimmte Organisationseinheit begrenzen
X-Idempotency-Key: <uuid>	Sicherstellen, dass Schreibvorgänge idempotent sind

Ressourcenmodell

Während die genauen Ressourcen je nach Land variieren, folgen die meisten fiskaly-Produkte einem gemeinsamen Muster:

Account / Group
  └── Unit (Organisation)
        └── Steuerpflichtiger
              └── Standort (Filiale / Hauptsitz)
                    └── System (Fiskalgerät / POS)
                          └── Datensatz / Transaktion

Ressourcen-Lebenszyklus

Die meisten Ressourcen folgen einem Zustandsautomaten:

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

• ACQUIRED: Ressource ist erstellt, aber noch nicht aktiv
• COMMISSIONED: Ressource ist aktiv und kann Transaktionen verarbeiten
• DECOMMISSIONED: Ressource ist außer Betrieb und akzeptiert keine neuen Vorgänge mehr

In SIGN DE sind die entsprechenden Zustände CREATED → INITIALIZED → DISABLED.

Länderspezifische Ressourcen

Konzept	Deutschland (SIGN DE)	Österreich (SIGN AT)	Spanien (SIGN ES)	Italien (SIGN IT)	Frankreich (SIGN FR)
Signing-Einheit	TSS	SCU	Signer	System	System
POS-Terminal	Client	Kasse	Client	System	System
Fiskalbeleg	Transaktion	Bon	Rechnung	Datensatz	Datensatz
Steuerbehörde	BSI / BZSt	FinanzOnline	AEAT / Baskische DFAs	AdE (Agenzia delle Entrate)	DGFiP

Basis-URLs

Jedes Produkt hat seinen eigenen API-Endpunkt. Siehe die Basis-URLs & Umgebungen-Referenz für eine vollständige Liste.

Produkt	Testumgebung	Live-Umgebung
SIGN DE	kassensichv-middleware.fiskaly.com/api/v2	kassensichv.fiskaly.com/api/v2
SIGN AT	rksv.fiskaly.com/api/v1	rksv.fiskaly.com/api/v1
SIGN ES	test.es.sign.fiskaly.com/api/v1	live.es.sign.fiskaly.com/api/v1
SIGN IT	test.api.fiskaly.com	live.api.fiskaly.com
SIGN FR	test.api.fiskaly.com	live.api.fiskaly.com

Was kommt als Nächstes?

Quick Start

Führen Sie Ihren ersten API-Aufruf in unter 5 Minuten durch

Authentifizierungs-Referenz

Ausführlicher Auth-Guide mit Token-Refresh-Flows

Fehlercodes

API-Fehler verstehen und beheben