Section navigation

API-Referenz

Diese Seite ist die zentrale Referenz für alle fiskaly API-Endpunkte, Basis-URLs, Authentifizierung und Rate-Limits. Nutzen Sie sie als Ausgangspunkt für jede Produktintegration.

fiskaly bietet zwei API-Architekturen an. Siehe Die Unified API für den vollständigen Vergleich.

Unified API

Die Unified API verwendet gemeinsame Basis-URLs und ein einheitliches Ressourcenmodell über Länder hinweg. Derzeit abgedeckt: SIGN FR, SIGN IT, SIGN PT, SIGN SE und SIGN CZ (Preview).

	Details
TEST-Basis-URL	`https://test.api.fiskaly.com`
LIVE-Basis-URL	`https://live.api.fiskaly.com`
Erforderliche Header	`X-Api-Version` (Datum, z. B. `2026-02-03`), `X-Idempotency-Key` (UUID, bei POST/PATCH), `X-Scope-Identifier` (Ressourcen-Scoping)
Ressourcen-IDs	Vom Server generiert (nutzen Sie `X-Idempotency-Key` für Idempotenz)
Org-Verwaltung	In die Produkt-API integriert (keine separate Management API)

Produkt	Neueste API-Version	Docs
SIGN FR	2026-06-01	Docs
SIGN IT	2026-06-01	Docs
SIGN PT	2026-06-01	Docs
SIGN SE	2026-06-01	Aktuelle Docs
SIGN CZ (Preview)	2026-06-01	Docs

Spezialisierte APIs

Jede spezialisierte API hat ihre eigene Basis-URL und ihr eigenes Ressourcenmodell, maßgeschneidert für ein bestimmtes Land. Verwendet die Management API für die Organisationsverwaltung.

Produkt	API-Version	Basis-URL (TEST)	Basis-URL (LIVE)	Docs
SIGN DE	v2	`kassensichv-middleware.fiskaly.com/api/v2`	`kassensichv.fiskaly.com/api/v2`	Interaktive Docs
SIGN AT	v1	`rksv-middleware.fiskaly.com/api/v1`	`rksv.fiskaly.com/api/v1`	Docs
SIGN ES	v1	fiskaly kontaktieren für Endpunkte	fiskaly kontaktieren für Endpunkte	Docs
Management	v0	`dashboard.fiskaly.com/api/v0`	`dashboard.fiskaly.com/api/v0`	Interaktive Docs

Ergänzende Produkt-APIs

Diese Produkte ergänzen SIGN und sind nicht an eine bestimmte API-Architektur gebunden:

Produkt	Basis-URL (TEST)	Basis-URL (LIVE)	Docs
DSFinV-K (Deutschland)	`dsfinvk-middleware.fiskaly.com/api/v1`	`dsfinvk.fiskaly.com/api/v1`	Docs
SUBMIT DE (Deutschland)	Über SIGN DE Middleware	Über SIGN DE Produktion	Docs
SAFE	fiskaly kontaktieren für Endpunkte	fiskaly kontaktieren für Endpunkte	Docs
E-Invoice	fiskaly kontaktieren für Endpunkte	fiskaly kontaktieren für Endpunkte	Docs
eReceipt	`receipt.fiskaly.com/api/v1`	`receipt.fiskaly.com/api/v1`	Interaktive Docs

📘Endpunkt-Verfügbarkeit

Einige neuere Produkte haben ihre Basis-URLs noch nicht öffentlich veröffentlicht. Wenden Sie sich an Ihren Account-Manager oder sales@fiskaly.com für den Zugang zu SIGN FR, SIGN ES, SIGN IT, SIGN PT, SIGN CZ, SAFE und E-Invoice-Endpunkten.

Authentifizierung

Alle fiskaly-APIs verwenden dasselbe Bearer-Token-Authentifizierungsmuster:

POST /auth mit Ihrem api_key und api_secret
Empfangen Sie ein access_token (24h) und ein refresh_token (48h)
Fügen Sie das Token als Authorization: Bearer <token> in alle nachfolgenden Anfragen ein
Bei 401, neu authentifizieren — nicht mit demselben abgelaufenen Token erneut versuchen

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "YOUR_API_KEY",
      api_secret: "YOUR_API_SECRET",
    }),
  }
);

const { access_token } = await response.json();

Fügen Sie dann das Token in nachfolgende Anfragen ein:

curl -X GET https://kassensichv-middleware.fiskaly.com/api/v2/tss \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

⚠️Halten Sie Ihre Secrets sicher

Übertragen Sie niemals API-Secrets an die Versionskontrolle oder exponieren Sie sie in client-seitigem Code. Speichern Sie sie in Umgebungsvariablen oder einem Secret-Manager.

💡Token cachen

Das Access-Token ist 24 Stunden gültig. Eine erneute Authentifizierung bei jeder Anfrage fügt unnötige Latenz hinzu. Cachen Sie das Token und erneuern Sie es nur bei 401.

Umgebungen

Jedes Produkt verfügt über eine TEST (Sandbox)- und eine LIVE (Produktions)-Umgebung:

	TEST (Sandbox)	LIVE (Produktion)
Zweck	Entwicklung und Integrationstests	Echte Transaktionen, prüfungsrelevante Daten
Daten	Ephemer — sicher zum Experimentieren, kann zurückgesetzt werden	Permanent — rechtlich bindende Aufzeichnungen
Abrechnung	Kostenlos	Vertragsgemäß
Standard	Alle neuen Organisationen starten hier	Aktivierung über HUB
Basis-URL-Präfix	Enthält normalerweise `middleware`	Direkte Produktdomäne

⚠️TEST und LIVE sind getrennt

In TEST erstellte Ressourcen existieren nicht in LIVE. Beim Wechsel in die Produktion müssen alle Ressourcen neu provisioniert werden (TSS, Clients, Signing Units usw.).

Rate-Limits

API-Rate-Limits variieren je nach Produkt und Abonnementplan. Allgemeine Richtlinien:

Operation	Typisches Limit	Hinweise
Authentifizierung	10 Anfragen/min	Token cachen — nicht pro Transaktion authentifizieren
Transaktionssignierung	200 Anfragen/min	Sollte für normalen Checkout kein Engpass sein
Export-Generierung	Niedrigere Limits	Ressourcenintensive Vorgänge — Async-Polling verwenden
Management-Vorgänge	60 Anfragen/min	Organisations-/API-Key-Verwaltung

Rate-Limit-Header

Jede API-Antwort enthält Header, die bei der Verwaltung Ihres Anfrage-Budgets helfen:

Header	Beschreibung
`X-RateLimit-Limit`	Maximale Anfragen im aktuellen Zeitfenster
`X-RateLimit-Remaining`	Verbleibende Anfragen im aktuellen Zeitfenster
`X-RateLimit-Reset`	Unix-Zeitstempel, wann das Rate-Limit-Fenster zurückgesetzt wird
`Retry-After`	Sekunden bis zum nächsten Versuch (nur bei 429-Antworten)

Bei einem 429 Too Many Requests mit exponentiellem Backoff warten. Siehe Wiederholungsstrategie für Implementierungshinweise.

Für Enterprise-Rate-Limits oder benutzerdefinierte Anforderungen wenden Sie sich an Ihren Account-Manager.

Paginierung

fiskaly-APIs verwenden zwei verschiedene Paginierungsmuster je nach API-Architektur.

Spezialisierte APIs (SIGN DE, DSFinV-K)

Spezialisierte APIs verwenden offset-basierte Paginierung mit limit- und offset-Abfrageparametern.

Parameter	Standard	Maximum	Beschreibung
`limit`	100	1000	Anzahl der zurückzugebenden Elemente
`offset`	0	—	Anzahl der zu überspringenden Elemente

Die Antwort enthält count (Gesamtelemente), data (Ergebnisarray), offset und limit.

curl -X GET "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/tss?limit=50&offset=100",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  }
);

const { count, data, offset, limit } = await response.json();
// count: 250, data: [...50 items], offset: 100, limit: 50

Unified API (SIGN FR, SIGN IT, SIGN PT, SIGN SE, SIGN CZ)

Die Unified API verwendet token-basierte Paginierung mit den Abfrageparametern limit und token.

Parameter	Standard	Maximum	Beschreibung
`limit`	10	100	Anzahl der zurückzugebenden Elemente
`token`	—	—	Opaker Cursor aus dem `pagination.token` einer vorherigen Antwort

Die Antwort enthält results (Ressourcen-Array) und, wenn weitere Seiten existieren, ein pagination-Objekt mit token (Cursor für die nächste Seite), next (direkt nutzbare URL der nächsten Seite) und limit. Auf der letzten Seite fehlt das pagination-Objekt komplett.

# Erste Seite
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

# Nächste Seite (pagination.token aus vorheriger Antwort verwenden)
curl -X GET "https://test.api.fiskaly.com/organizations?limit=25&token=eyJpZCI6ImFiYzEyMyJ9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Api-Version: 2026-06-01"

let token = null;
let allItems = [];

do {
  const url = new URL("https://test.api.fiskaly.com/organizations");
  url.searchParams.set("limit", "25");
  if (token) url.searchParams.set("token", token);

  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Version": "2026-06-01",
    },
  });

  const { results, pagination } = await response.json();
  allItems.push(...results);
  token = pagination?.token ?? null;
} while (token);

💡Das richtige Muster wählen

Prüfen Sie, welche API-Architektur Ihr Produkt verwendet (Unified vs. Spezialisiert), um zu bestimmen, welches Paginierungsmuster implementiert werden soll. Siehe die Tabellen am Anfang dieser Seite.

SIGN-APIs

SIGN DE v2

Interaktive API-Referenz — vollständige Endpunkt-Dokumentation mit Try-it-out

SIGN AT v1

Österreichische RKSV — Integrationsleitfaden und Endpunkt-Referenz

SIGN FR

Französische NF525 — Signierung, Abschlüsse, Archive, Offline-Modus

SIGN ES v1

Spanische TicketBAI & Verifactu — XML-Generierung, Signierung, Übermittlung

SIGN IT

Italienischer Registratore Telematico — Cloud-RT, Belegeslotterie

SIGN PT

Portugiesisches SAF-T (PT) — zertifizierte Dokumentensignierung mit ATCUD

SIGN SE (TCS)

Schwedische Fiskalisierung — X.509, XML-API, Kontrollcodes

SIGN CZ (Preview)

Tschechische EET 2.0 — Echtzeit-Umsatzregistrierung mit POK-Bestätigung

Ergänzende Produkt-APIs

DSFinV-K v1

Deutsches Fiskaldatenexport — Kassenabschlüsse, Prüfungsexporte

SUBMIT DE v1

ELSTER-Einreichung — Steuerpflichtige-Registrierung und Erklärungsübermittlung

SAFE

Konforme Fiskalarchivierung — automatisiert oder API-gesteuert

E-Invoice

B2B E-Rechnung über Peppol — Belgien live, weitere Länder folgen

eReceipt v1

Digitale Beleggenerierung — QR-Code, E-Mail und Link-Zustellung

Management API v0

Organisations-, Benutzer- und API-Key-Verwaltung

SDKs und Tools

Postman-Collections

Vorkonfigurierte Anfragen für SIGN DE — interaktive API-Erkundung

Quick Start

Erste signierte Transaktion in unter 5 Minuten mit Code-Beispielen

Fehlercodes

Jeder Fehlercode, seine Ursache und Behebung

📘Keine Client-SDKs (noch)

fiskaly bietet derzeit keine offiziellen Client-SDKs an. Alle Integrationen erfolgen über direkte REST-API-Aufrufe. Die API-Oberfläche ist klein genug, sodass ein dünner HTTP- Wrapper in Ihrer bevorzugten Sprache normalerweise ausreicht. Prüfen Sie das Changelog für SDK-Ankündigungen.