Quick Start

fiskaly bietet Fiskalkonformitäts-APIs in ganz Europa. Wählen Sie unten Ihr Land, um direkt zur Integrierungsanleitung zu springen, oder scrollen Sie nach unten für eine praktische SIGN DE-Komplettanleitung.

Wählen Sie Ihr Land

🇩🇪

Deutschland flagLive

Deutschland(SIGN DE)

KassenSichV — TSS, Client, Transaktion

🇦🇹

Österreich flagLive

Österreich(SIGN AT)

RKSV — SCU, Kasse, Bon

🇫🇷

Frankreich flagLive

Frankreich(SIGN FR)

NF 525 — Organisation, System, Datensatz

🇮🇹

Italien flagLive

Italien(SIGN IT)

RT-Konformität — Steuerpflichtiger, Standort, System, Datensatz

🇪🇸

Spanien flagLive

Spanien(SIGN ES)

TicketBAI & Verifactu — Steuerpflichtiger, Signer, Rechnung

🇵🇹

Portugal flagLive

Portugal(SIGN PT)

AT — Taxpayer, System, Document

🇧🇪

Belgien flagLive

Belgien(E-Invoice)

Peppol B2B E-Invoicing über die Unified API

🇸🇪

Schweden flagLive

Schweden(SIGN SE)

InfraSec TCS — zertifikatsbasierte Kontrollcodes

💡Multi-Country-Rollout?

Frankreich, Italien und Belgien teilen die Unified API — eine Integrierung deckt alle drei ab. Siehe Integrierungsplanung für Aufwandsschätzungen und Rollout-Zeitpläne.

---

Praxisbeispiel: SIGN DE in 5 Minuten

Die folgende Anleitung verwendet Deutschland (SIGN DE) als konkretes Beispiel. Der Ablauf ist: authentifizieren → TSS erstellen → Transaktion signieren.

📘Diese Anleitung verwendet die SIGN DE Spezialisierte API

Deutschland, Österreich und Spanien haben jeweils eine dedizierte Spezialisierte API. Frankreich und Italien verwenden die Unified API mit einem gemeinsamen Ressourcenmodell. Wählen Sie oben Ihr Land für den richtigen Guide.

Zeitbedarf: ~5 Minuten mit cURL, ~15 Minuten beim Einbau in Anwendungscode.

Voraussetzungen

Sie benötigen drei Dinge, bevor Sie beginnen:

1. Ein fiskaly-Konto — kostenlos registrieren unter hub.fiskaly.com
2. API-Zugangsdaten — generieren Sie einen API Key und ein Secret im HUB unter Ihrer Organisation
3. Einen HTTP-Client — cURL, Postman oder die HTTP-Bibliothek Ihrer Sprache

⚠️Ihr API Secret wird nur einmal angezeigt

Kopieren Sie das Secret sofort bei der Generierung. Wenn Sie es verlieren, müssen Sie ein neues Schlüsselpaar generieren. Speichern Sie Zugangsdaten in Umgebungsvariablen oder einem Secret-Manager — niemals in der Quellcodeverwaltung.

Umgebung

Dieser Guide verwendet die Sandbox (TEST)-Umgebung. Alle neuen Organisationen starten hier. Es werden keine echten Fiskaldaten erstellt und Ihnen werden keine Kosten berechnet.

	Sandbox (TEST)	Produktion (LIVE)
Basis-URL	https://kassensichv-middleware.fiskaly.com/api/v2	https://kassensichv.fiskaly.com/api/v2
Daten	Flüchtig — sicher zum Experimentieren	Dauerhaft — prüfungsrelevant
Abrechnung	Kostenlos	Per Vertrag
Wechsel	Standard für neue Orgs	Aktivierung über HUB

Schritt 1: Authentifizieren

Tauschen Sie Ihren API Key und Ihr Secret gegen einen Bearer-Token.

cURLJavaScriptPythonJavaC#

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, refresh_token } = await response.json();

import requests

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={
        "api_key": "YOUR_API_KEY",
        "api_secret": "YOUR_API_SECRET",
    },
)

data = response.json()
access_token = data["access_token"]
refresh_token = data["refresh_token"]

HttpClient client = HttpClient.newHttpClient();
String body = """ 
    {"api_key":"YOUR_API_KEY","api_secret":"YOUR_API_SECRET"}
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://kassensichv-middleware.fiskaly.com/api/v2/auth"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
// Parse response.body() for access_token

using var client = new HttpClient();
var payload = new {
    api_key = "YOUR_API_KEY",
    api_secret = "YOUR_API_SECRET"
};

var response = await client.PostAsJsonAsync(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    payload);

var result = await response.Content
    .ReadFromJsonAsync<JsonElement>();
var accessToken = result
    .GetProperty("access_token").GetString();

Erwartete Antwort (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token_expires_in": 172800
}

Der access_token ist 24 Stunden gültig. Der refresh_token ist 48 Stunden gültig. Fügen Sie den Access-Token als Authorization: Bearer <token> in alle nachfolgenden Anfragen ein.

💡Authentifizieren Sie sich nicht bei jeder Anfrage neu

Cachen Sie den Token und erneuern ihn nur bei 401-Antworten. Eine erneute Authentifizierung pro Anfrage verursacht unnötige Latenz im Kassierprozess.

Schritt 2: TSS erstellen und initialisieren

Ein TSS (Technisches Sicherheitssystem) ist die zertifizierte Signing-Ressource. Sie benötigen eines pro physischem Standort. Das Erstellen eines TSS umfasst drei Unterschritte: erstellen, Admin-PIN setzen und initialisieren.

a) TSS erstellen

cURLJavaScript

TSS_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Mein erstes TSS"
  }'

const tssId = crypto.randomUUID();

const tssResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "My first TSS",
    }),
  }
);

const tss = await tssResponse.json();
// Save tss.admin_puk — you need it to set the Admin PIN

Erwartete Antwort (200 OK) — beachten Sie das Feld admin_puk:

{
  "_id": "a1b2c3d4-...",
  "description": "My first TSS",
  "state": "UNINITIALIZED",
  "admin_puk": "123456"
}

b) Admin-PIN setzen (mit dem admin_puk aus der obigen Antwort):

cURLJavaScript

curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "admin_puk": "123456",
    "new_admin_pin": "your-secure-admin-pin"
  }'

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      admin_puk: tss.admin_puk,
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

c) Als Admin authentifizieren und initialisieren:

cURLJavaScript

# Als Admin authentifizieren
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/auth" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "admin_pin": "your-secure-admin-pin" }'

# TSS initialisieren
curl -X PATCH "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "state": "INITIALIZED" }'

// Als Admin authentifizieren
await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/admin/auth`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ admin_pin: "your-secure-admin-pin" }),
  }
);

// TSS initialisieren
await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ state: "INITIALIZED" }),
  }
);

Nach der Initialisierung ändert sich der TSS-state zu INITIALIZED. Sie können nun Clients erstellen und Transaktionen signieren.

Schritt 3: Client erstellen

Ein Client repräsentiert ein einzelnes POS-Terminal oder eine Anwendungsinstanz, die mit dem TSS verbunden ist.

cURLJavaScript

CLIENT_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/client/${CLIENT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "serial_number": "POS-001" }'

const clientId = crypto.randomUUID();

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/client/${clientId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ serial_number: "POS-001" }),
  }
);

Schritt 4: Transaktion signieren

Transaktionen haben einen Lebenszyklus: starten (Status ACTIVE) dann abschließen (Status FINISHED). Die Abschluss-Antwort enthält die kryptografische Signatur.

a) Transaktion starten:

cURLJavaScript

TX_ID=$(uuidgen)

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=1" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "ACTIVE",
    "client_id": "YOUR_CLIENT_ID"
  }'

const txId = crypto.randomUUID();

await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=1`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "ACTIVE",
      client_id: clientId,
    }),
  }
);

b) Transaktion abschließen (hier wird die Signatur generiert):

cURLJavaScript

curl -X PUT "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/tx/${TX_ID}?tx_revision=2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "FINISHED",
    "client_id": "YOUR_CLIENT_ID",
    "schema": {
      "standard_v1": {
        "receipt": {
          "receipt_type": "RECEIPT",
          "amounts_per_vat_rate": [
            { "vat_rate": "NORMAL", "amount": "10.00" }
          ],
          "amounts_per_payment_type": [
            { "payment_type": "CASH", "amount": "10.00" }
          ]
        }
      }
    }
  }'

const finishResponse = await fetch(
  `https://kassensichv-middleware.fiskaly.com/api/v2/tss/${tssId}/tx/${txId}?tx_revision=2`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "FINISHED",
      client_id: clientId,
      schema: {
        standard_v1: {
          receipt: {
            receipt_type: "RECEIPT",
            amounts_per_vat_rate: [
              { vat_rate: "NORMAL", amount: "10.00" },
            ],
            amounts_per_payment_type: [
              { payment_type: "CASH", amount: "10.00" },
            ],
          },
        },
      },
    }),
  }
);

const signedTx = await finishResponse.json();
console.log(signedTx.signature);

Erwartete Antwort (200 OK) — die Schlüsselfelder sind signature und qr_code_data:

{
  "_id": "tx-uuid-...",
  "state": "FINISHED",
  "number": 1,
  "time_start": 1700000000,
  "time_end": 1700000001,
  "signature": {
    "value": "dGVzdC1zaWduYXR1cmU=",
    "algorithm": "ecdsa-plain-SHA384",
    "counter": 1,
    "public_key": "BHHz..."
  },
  "qr_code_data": "V0;TSS-ID;TX-NUMBER;..."
}

Der qr_code_data-String ist das, was Sie in den QR-Code kodieren, der auf dem Beleg gedruckt wird.

Schritt 5: Admin abmelden

Nach Abschluss der Einrichtung melden Sie den Admin vom TSS ab:

curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Häufige Fehler beim ersten Mal

Fehler	Ursache	Lösung
401 Unauthorized	Abgelaufener oder falscher Token	Erneut mit /auth authentifizieren. Prüfen Sie, ob Sie den richtigen API Key für diese Umgebung verwenden.
400 E_TSS_NOT_INITIALIZED	Versuch, einen Client oder eine Transaktion auf einem nicht initialisierten TSS zu erstellen	Alle drei TSS-Einrichtungsschritte abschließen: erstellen, Admin-PIN setzen, initialisieren.
400 mit “admin_puk”-Fehler	Falscher PUK beim Setzen der Admin-PIN	Verwenden Sie den admin_puk-Wert aus der TSS-Erstellungsantwort, nicht einen selbst gewählten Wert.
409 Conflict	Wiederverwendete UUID, die bereits existiert	Generieren Sie eine neue UUID für jede Ressource (TSS, Client, Transaktion).
422 E_TX_INVALID_STATE	Versuch, eine Transaktion abzuschließen, die nicht ACTIVE ist	Starten Sie die Transaktion zuerst (Revision 1 mit state: ACTIVE), dann abschließen (Revision 2).

Für die vollständige Fehlerreferenz siehe Fehlercodes.

Postman verwenden

Wenn Sie einen GUI-basierten Workflow bevorzugen, laden Sie die vorkonfigurierte Postman-Sammlung herunter:

1. Herunterladen

   Laden Sie die Postman-Sammlung und die Umgebungsdatei herunter.

2. Importieren

   Importieren Sie beide Dateien in Postman.
3. Konfigurieren

   Setzen Sie Ihren api_key und Ihr api_secret in den Umgebungsvariablen.

4. Ausführen

   Führen Sie die Anfragen der Reihe nach aus — die Sammlung verwendet Variablen, um Antworten automatisch zu verketten.

Siehe das vollständige Postman-Tutorial für eine detaillierte Anleitung.

Was als Nächstes aufbauen

Vollständiger SIGN DE-Guide

Vollständige Einrichtung inklusive Organisationshierarchie, Produktionsbereitstellung und Beleg-QR-Codes

Fehlerbehandlung

Timeout-Strategie, Wiederholungslogik und was zu tun ist, wenn das TSS nicht verfügbar ist

DSFinV-K-Integrierung

Für Deutschland erforderlich: konforme Fiskaldatenexporte für Prüfungen generieren

API-Referenz

Vollständige Endpunkt-Dokumentation, alle Produkt-Basis-URLs und Rate Limits

In ein weiteres Land expandieren

Was sich ändert, wenn Sie Österreich, Frankreich, Spanien, Italien oder Schweden hinzufügen

Integrierungsplanung (PMs)

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