Schritt-für-Schritt-Integration

Diese Anleitung führt Sie durch den vollständigen Prozess der Einrichtung Ihres Systems mit fiskaly SIGN DE, unter Verwendung einer Kombination aus dem fiskaly HUB, der Management API und der SIGN DE API. Am Ende verfügen Sie über eine vollständig eingerichtete verwaltete Organisation mit einem TSS und einem Client, der bereit ist, Transaktionen zu signieren.

Bevor wir mit der Einrichtung beginnen, hier ist, was Sie konfigurieren werden:

🏢

Account & Gruppe

Ihr Account ist die übergeordnete Entität, die bei der Registrierung im HUB erstellt wird — er repräsentiert Ihr Unternehmen als POS-Anbieter oder Händler. Eine Gruppe ist eine Zwischenschicht innerhalb des Accounts, die dazu dient, verwaltete Organisationen logisch zu bündeln (z. B. eine Gruppe pro Land).

🔑

API-Schlüssel & Token

Im HUB generierte Zugangsdaten und über die Management API und SIGN DE erhaltene Token, die zur Authentifizierung aller nachfolgenden Anfragen verwendet werden.

🏬

Verwaltete Organisation

Repräsentiert einen einzelnen physischen Standort (z. B. ein Geschäft oder Restaurant), im HUB als Unit bezeichnet. Wird über die Management API erstellt und mit einer Gruppe innerhalb Ihres Accounts verknüpft.

🛡️

TSS (Technische Sicherheitseinrichtung)

Die zentrale Signierkomponente. Muss erstellt, mit einer Admin-PIN konfiguriert und initialisiert werden, bevor sie Transaktionen signieren kann.

💻

Client

Repräsentiert ein POS-Terminal oder eine Anwendung, die Transaktionen gegen ein TSS erstellt.

🧾

Transaktion

Ein signierter Fiskalbeleg. Sobald Ihr TSS und Client bereit sind, können Sie Transaktionen starten und abschließen, um kryptografische Signaturen zu erzeugen.

Voraussetzungen

📘Bevor Sie beginnen

Sie benötigen einen fiskaly-Account und Zugriff auf den fiskaly HUB. Falls Sie noch keinen Account haben, registrieren Sie sich hier. Sie benötigen außerdem ein Tool für HTTP-Anfragen — zum Beispiel cURL, Postman oder eigenen Anwendungscode.

Integrations-Workflow

Das folgende Diagramm zeigt alle zehn Schritte der SIGN DE-Integration. Klicken Sie auf eine Kachel, um zum entsprechenden Einrichtungsschritt zu springen.

Schritt-für-Schritt-Einrichtung

Im HUB registrieren
Gehen Sie zu hub.fiskaly.com und erstellen Sie Ihren fiskaly-Account. Sie erhalten eine Bestätigungs-E-Mail — klicken Sie auf den Link, um Ihre Adresse zu verifizieren und Ihren Account zu aktivieren.
Account & Gruppe erstellen
Wenn Sie sich zum ersten Mal im HUB anmelden, werden Sie aufgefordert, Ihren Account einzurichten — die übergeordnete Entität, die Ihr Unternehmen (POS-Anbieter oder Händler) repräsentiert. Der HUB führt Sie auch zur Erstellung einer Gruppe, einer Zwischenschicht innerhalb Ihres Accounts zur logischen Bündelung von verwalteten Organisationen (z. B. eine Gruppe pro Land).
💡Noch nicht bereit für die Produktion?
Für Testzwecke müssen Sie nicht alle Felder ausfüllen. Sie können die Rechnungsadresse leer lassen und später ergänzen.
Nach Abschluss der Einrichtung zeigt der HUB Ihre aktuelle Übersicht — zunächst mit 0 TSS und 0 Clients.
API-Schlüssel erstellen
Navigieren Sie im fiskaly HUB zum Bereich API-Schlüssel und erstellen Sie einen neuen API-Schlüssel für Ihren Account.
Sie erhalten einen API-Schlüssel und ein API-Geheimnis. Bewahren Sie diese sicher auf — Sie benötigen sie für alle nachfolgenden API-Anfragen.
⚠️Zugangsdaten sicher aufbewahren
Das API-Geheimnis wird nur einmal angezeigt. Stellen Sie sicher, dass Sie es kopieren und an einem sicheren Ort speichern, bevor Sie den Dialog schließen.

Token erstellen (Management API)

Verwenden Sie den API-Schlüssel und das API-Geheimnis aus dem vorherigen Schritt, um ein Management API-Zugriffstoken zu erhalten.

curl -X POST https://dashboard.fiskaly.com/api/v0/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "api_secret": "your_api_secret"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/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();

Beispielantwort (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "00000000-0000-0000-0000-000000000000"
  },
  "access_token_expires_in": 300,
  "access_token_expires_at": 1577833200,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 300,
  "refresh_token_expires_at": 1577833200
}

Verwenden Sie das access_token als Bearer-Token im Authorization-Header für alle Management API-Anfragen.

Verwaltete Organisation(en) erstellen

Erstellen Sie eine oder mehrere verwaltete Organisationen (im HUB auch als Units bezeichnet) unter Ihrer Gruppe. Jede Unit repräsentiert typischerweise einen einzelnen physischen Standort wie ein Geschäft oder Restaurant.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store Berlin",
    "managed_by_organization_id": "your-group-id",
    "address_line1": "Unter den Linden 1",
    "zip": "10117",
    "town": "Berlin",
    "country_code": "DEU"
  }'

const response = await fetch(
  "https://dashboard.fiskaly.com/api/v0/organizations",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "My Store Berlin",
      managed_by_organization_id: "your-group-id",
      address_line1: "Unter den Linden 1",
      zip: "10117",
      town: "Berlin",
      country_code: "DEU",
    }),
  }
);

const { _id: orgId } = await response.json();

Beispielantwort (200 OK)

{
  "_id": "your-managed-org-id",
  "_type": "ORGANIZATION",
  "name": "My Store Berlin",
  "managed_by_organization_id": "your-group-id",
  "address_line1": "Unter den Linden 1",
  "zip": "10117",
  "town": "Berlin",
  "country_code": "DEU",
  "state": "active",
  "time_creation": "2026-03-01T10:00:00Z"
}

Notieren Sie die _id aus der Antwort — dies ist Ihre verwaltete Organisations-ID, die Sie im nächsten Schritt benötigen.

💡Wo finden Sie Ihre Gruppen-ID?

Ihre Gruppen-ID (managed_by_organization_id) ist im fiskaly HUB unter Einstellungen → Organisation sichtbar, oder Sie können sie aus dem Feld organization_id in der Management API-Token-Antwort (POST /api/v0/auth) abrufen.

API-Schlüssel erstellen (verwaltete Organisation)

Generieren Sie einen dedizierten API-Schlüssel für die verwaltete Organisation. Dieser Schlüssel wird zur Authentifizierung von SIGN DE API-Anfragen verwendet, die auf diese Organisation beschränkt sind.

curl -X POST "https://dashboard.fiskaly.com/api/v0/organizations/${ORG_ID}/api-keys" \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sign-de-key",
    "status": "enabled",
    "managed_by_organization_id": "your-group-id"
  }'

const response = await fetch(
  `https://dashboard.fiskaly.com/api/v0/organizations/${orgId}/api-keys`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${managementToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "sign-de-key",
      status: "enabled",
      managed_by_organization_id: "your-group-id",
    }),
  }
);

const { key: apiKey, secret: apiSecret } = await response.json();

⚠️Diese Zugangsdaten speichern

Das secret für den API-Schlüssel der verwalteten Organisation wird nur einmal angezeigt. Bewahren Sie es sicher auf, bevor Sie fortfahren.

Beispielantwort (200 OK)

{
  "_id": "your-api-key-id",
  "_type": "MANAGED_API_KEY",
  "_envs": ["TEST"],
  "name": "sign-de-key",
  "key": "your-api-key",
  "secret": "your-api-secret",
  "status": "enabled",
  "managed_by_organization_id": "your-group-id",
  "created_at": 1577833200
}

Token erstellen (SIGN DE)

Verwenden Sie den API-Schlüssel und das API-Geheimnis der verwalteten Organisation, um ein SIGN DE-Zugriffstoken zu erhalten.

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "managed_org_api_key",
    "api_secret": "managed_org_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: "managed_org_api_key",
      api_secret: "managed_org_api_secret",
    }),
  }
);

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

Beispielantwort (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-managed-org-id"
  },
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800
}

Verwenden Sie dieses access_token als Bearer-Token für alle nachfolgenden SIGN DE API-Anfragen.

TSS erstellen
Erstellen Sie eine neue Technische Sicherheitseinrichtung (TSS) durch Senden einer PUT-Anfrage mit einer eindeutigen TSS-ID (UUID). Die TSS muss dann initialisiert werden, bevor sie Transaktionen signieren kann.
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 '{"metadata": {}}'
Beispielantwort (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "_env": "TEST", "_version": "2.2.2", "admin_puk": "initial-puk-from-creation", "state": "CREATED", "serial_number": "a1b2c3d4e5f6...", "public_key": "MFkwEwYH...", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "signature_algorithm": "ECDSA", "signature_timestamp_format": "unixTime", "transaction_data_encoding": "UTF-8", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": 1577833200, "metadata": {} }
⚠️Großzügigen Timeout verwenden
Die TSS-Erstellung und Personalisierung kann bis zu 30 Sekunden dauern. Setzen Sie für beide Aufrufe einen Request-Timeout von mindestens 30 Sekunden, um vorzeitige Fehler zu vermeiden.
Initialisieren Sie die TSS nach der Erstellung in vier Teilschritten:
a) TSS personalisieren
Verschieben Sie die TSS vom Zustand CREATED in den Zustand UNINITIALIZED, bevor Sie die Admin-PIN ändern:
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": "UNINITIALIZED"}'
b) Admin-PIN ändern
Die TSS wird im Zustand UNINITIALIZED erstellt. Sie müssen eine neue Admin-PIN mit dem admin_puk aus der Erstellungsantwort festlegen.
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": "puk-from-creation-response", "new_admin_pin": "your-secure-admin-pin" }'
c) 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" }'
d) TSS initialisieren
Aktualisieren Sie den TSS-Status auf INITIALIZED:
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" }'
Beispielantwort (200 OK)
{ "_id": "your-tss-id", "_type": "TSS", "state": "INITIALIZED", "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----", "serial_number": "a1b2c3d4e5f6...", "signature_algorithm": "ECDSA", "max_number_registered_clients": 100, "max_number_active_transactions": 1000, "time_creation": "2026-03-01T10:00:00Z" }
💡Admin nach Abschluss abmelden
Sobald die TSS initialisiert ist, melden Sie den Admin-Benutzer als Sicherheits-Best-Practice ab — vor dem Produktionseinsatz erforderlich.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

Client erstellen

Mit der initialisierten TSS erstellen Sie einen Client, der Ihr POS-Terminal oder Ihre Anwendung repräsentiert.

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();

const response = 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" }),
  }
);

Beispielantwort (200 OK)

{
  "_id": "your-client-id",
  "_type": "CLIENT",
  "serial_number": "POS-001",
  "state": "REGISTERED",
  "tss_id": "your-tss-id",
  "time_creation": "2026-03-01T10:00:00Z"
}

⚠️serial_number ist dauerhaft

Die serial_number, die Sie einem Client zuweisen, kann nach der Erstellung nicht mehr geändert werden. Wählen Sie eine stabile, eindeutige Kennung für jedes POS-Terminal (z. B. eine Hardware-Seriennummer oder eine von Ihnen kontrollierte stabile UUID).

💡Einrichtung automatisieren

Diese gesamte Bereitstellungssequenz (Schritte 1–9) kann in einen vollständig automatisierten Workflow integriert werden. Einmal implementiert, erfordert das Onboarding eines neuen Standorts keine manuelle Benutzerinteraktion.

Täglicher Betrieb: Transaktion erstellen

Da Ihr TSS und Client nun bereitgestellt sind, sind Sie bereit für den täglichen Betrieb. Transaktionen folgen einem zweistufigen Lebenszyklus, der dem realen Kassierprozess entspricht:

Starten der Transaktion (Kasse öffnen) — senden Sie nur state: "ACTIVE" und client_id. An diesem Punkt ist kein Belegschema erforderlich.
Abschließen der Transaktion (nach Zahlungsabschluss) — senden Sie das vollständige Belegschema mit Beträgen und Zahlungsart, um die kryptografische Signatur zu erzeugen.

a) Transaktion starten

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();

const startResponse = 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

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" },
            ],
          },
        },
      },
    }),
  }
);

Beispielantwort (200 OK)

{
  "_id": "your-tx-id",
  "_type": "TRANSACTION",
  "state": "FINISHED",
  "client_id": "your-client-id",
  "tss_id": "your-tss-id",
  "time_start": "2026-03-01T10:00:00Z",
  "time_end": "2026-03-01T10:05:00Z",
  "qr_code_data": "V0;955002-00;Kassenbeleg-V1;...",
  "signature": {
    "value": "MEUCIQDx...",
    "timestamp": "2026-03-01T10:05:00Z",
    "serial_number": "a1b2c3d4e5f6..."
  }
}

Die Antwort enthält die signierte Transaktion mit einem qr_code_data-String für den Beleg-QR-Code und einer kryptografischen signature der TSS.

Nächste Schritte

SIGN DE API-Referenz

Vollständige API-Dokumentation für den KassenSichV v2-Endpoint — alle Ressourcen, Parameter und Antworten.

Leitfaden für Neukunden

Detaillierte Schritt-für-Schritt-Anleitung des Einrichtungsprozesses mit Postman-Collection-Downloads und Video-Tutorials.

HUB-Benutzerhandbuch

Erfahren Sie, wie Sie Organisationen, API-Schlüssel und TSS über die fiskaly HUB-Oberfläche verwalten.

QR-Code-Validierung

Verstehen Sie das QR-Code-Datenformat auf Ihren Belegen und wie Sie signierte Transaktionen validieren.

Was this page helpful?

Schritt-für-Schritt-Integration

Account & Gruppe

API-Schlüssel & Token

Verwaltete Organisation

TSS (Technische Sicherheitseinrichtung)

Client

Transaktion

Voraussetzungen

Integrations-Workflow

Schritt-für-Schritt-Einrichtung

Im HUB registrieren

Account & Gruppe erstellen

API-Schlüssel erstellen

Token erstellen (Management API)

Verwaltete Organisation(en) erstellen

API-Schlüssel erstellen (verwaltete Organisation)

Token erstellen (SIGN DE)

TSS erstellen

Client erstellen

Täglicher Betrieb: Transaktion erstellen

Nächste Schritte

SIGN DE API-Referenz

Leitfaden für Neukunden

HUB-Benutzerhandbuch

QR-Code-Validierung