Leitfaden für Neukunden

Dieser Leitfaden führt Sie durch den vollständigen Prozess der Einrichtung Ihres Systems mit fiskaly SIGN DE, unter Verwendung einer Kombination aus dem fiskaly HUB und API-Anfragen. Am Ende werden Sie über eine vollständig funktionsfähige TSS mit einem Client verfügen, der bereit ist, Transaktionen zu signieren.

Überblick

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

🏢

Organisation

Ihre übergeordnete Einheit bei fiskaly. Verwaltete Organisationen repräsentieren einzelne physische Standorte.

🔑

API-Schlüssel und -Geheimnis

Im HUB generierte Anmeldeinformationen, die zur Authentifizierung aller nachfolgenden API-Anfragen verwendet werden.

🔐

Authentifizierung

Verwenden Sie Ihren API-Schlüssel und Ihr Geheimnis, um ein Zugriffstoken zu generieren, das in allen weiteren API-Aufrufen verwendet wird.

🛡️

TSS (Technische Sicherheitseinrichtung)

Die zentrale Signierkomponente. Muss erstellt, mit einer Admin-PIN konfiguriert und initialisiert werden.

💻

Client

Repräsentiert ein Kassensystem oder eine Anwendung, die Transaktionen gegen eine TSS erstellt.

🧾

Transaktion

Ein signierter Fiskalbeleg. Sobald Ihre TSS und Ihr Client bereit sind, können Sie Transaktionen erstellen und signieren.

Schauen Sie sich unsere Video-Einführung für eine visuelle Erklärung des Einrichtungsprozesses an.

Voraussetzungen

📘Bevor Sie beginnen

Sie benötigen ein fiskaly-Konto und Zugang zum fiskaly HUB. Falls Sie noch kein Konto haben, registrieren Sie sich hier.

Sie benötigen außerdem ein Tool zum Durchführen von HTTP-Anfragen – zum Beispiel cURL (Befehlszeile), Postman oder Ihren eigenen Anwendungscode.

Schritt-für-Schritt-Einrichtung

Eine Organisation erstellen
Wenn Sie sich zum ersten Mal bei HUB anmelden, werden Sie aufgefordert, eine Organisation zu erstellen. Dies ist Ihre Hauptorganisation, und alle verwalteten Organisationen werden darunter erstellt.
Im Allgemeinen entspricht jede verwaltete Organisation einem physischen Standort (z. B. einem Geschäft oder Restaurant).
💡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 sie später ergänzen.
Nach dem Erstellen Ihrer Organisation zeigt HUB Ihre aktuelle Einrichtung – zunächst mit 0 TSS und 0 Clients.
Einen API-Schlüssel und ein Geheimnis generieren
Navigieren Sie zum Abschnitt „API-Schlüssel” im fiskaly HUB und erstellen Sie einen neuen API-Schlüssel.
Sie erhalten einen API-Schlüssel und ein API-Geheimnis. Speichern Sie diese sicher – Sie benötigen sie für alle nachfolgenden API-Anfragen.
⚠️Bewahren Sie Ihre Anmeldedaten sicher auf
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.
Unser Video-Tutorial demonstriert den Prozess der Generierung eines API-Schlüssels und -Geheimnisses.

Mit der API authentifizieren

Verwenden Sie Ihren API-Schlüssel und Ihr Geheimnis, um ein Zugriffstoken zu erhalten. Dieses Token ist für alle nachfolgenden Anfragen erforderlich.

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

Beispielantwort (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "access_token_claims": {
    "env": "TESTING",
    "organization_id": "your-org-id"
  },
  "access_token_expires_in": 86400,
  "access_token_expires_at": "2026-03-02T12:00:00Z",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 172800,
  "refresh_token_expires_at": "2026-03-03T12:00:00Z"
}

Die Antwort enthält ein access_token, das Sie als Bearer-Token im Authorization-Header aller folgenden Anfragen angeben müssen.

Eine TSS erstellen

Erstellen Sie eine neue Technische Sicherheitseinrichtung (TSS), indem Sie eine PUT-Anfrage mit einer eindeutigen TSS-ID (UUID) senden.

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": "My first TSS"
  }'

const tssId = crypto.randomUUID();

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

Beispielantwort (200 OK)

{
  "_id": "your-tss-id",
  "_type": "TSS",
  "_env": "TESTING",
  "_version": 1,
  "admin_puk": "initial-puk-from-creation",
  "state": "CREATED",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial_number": "a1b2c3d4e5f6...",
  "public_key": "BHxw...",
  "signature_algorithm": "ECDSA",
  "signature_timestamp_format": "ISO8601",
  "transaction_data_encoding": "UTF-8",
  "max_number_registered_clients": 100,
  "max_number_active_transactions": 1000,
  "time_creation": "2026-03-01T10:00:00Z",
  "metadata": {}
}

Nach der Erstellung müssen Sie die TSS initialisieren. Dies umfasst drei Teilschritte:

a) Admin-PIN ändern

Die TSS wird im Status UNINITIALIZED erstellt. Sie müssen eine neue Admin-PIN festlegen, bevor die Initialisierung erfolgt.

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": "initial-puk-from-creation",
    "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: "initial-puk-from-creation",
      new_admin_pin: "your-secure-admin-pin",
    }),
  }
);

b) 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"
  }'

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

c) TSS initialisieren

TSS-Status auf INITIALIZED aktualisieren:

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"
  }'

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

Einen Client erstellen

Mit der initialisierten TSS erstellen Sie einen Client, der Ihr Kassensystem 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",
    }),
  }
);

Eine Transaktion erstellen

Jetzt können Sie Ihre erste signierte Transaktion erstellen. Transaktionen folgen einem Lebenszyklus: Transaktion starten, dann beenden.

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 beenden

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

Die Antwort enthält die signierten Transaktionsdaten mit einer kryptographischen Signatur der TSS.

Admin abmelden
Melden Sie den Admin-Benutzer nach Abschluss der Einrichtung von der TSS ab.
curl -X POST "https://kassensichv-middleware.fiskaly.com/api/v2/tss/${TSS_ID}/admin/logout" \ -H "Authorization: Bearer ${ACCESS_TOKEN}"

💡Einrichtung automatisieren

Diese gesamte Abfolge von Anfragen kann in eine „Ein-Klick”- Bereitstellungslösung integriert werden, die keine manuelle Benutzerinteraktion erfordert. Die Implementierungsdetails liegen bei Ihnen.

Postman-Sammlung

Sie können diese Anfragen auch mit Postman durchführen. Laden Sie die Sammlung und die Umgebungsdateien herunter, um schnell loszulegen:

Postman-Sammlung herunterladen

Postman-Umgebung herunterladen

Weitere Anweisungen finden Sie im Postman-Tutorial.

Nächste Schritte

SIGN DE API-Dokumentation

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

HUB-Leitfaden

Erfahren Sie, wie Sie Organisationen, API-Schlüssel und TSS über den fiskaly HUB verwalten.

Was this page helpful?