Schrittweise Integration

Um den Integrationsprozess zu beginnen, folgen Sie bitte den detaillierten Schritt-für-Schritt-Anweisungen auf dieser Seite.

Das begleitende Diagramm veranschaulicht den Arbeitsablauf und hebt die wesentlichen Schritte hervor, die für eine erfolgreiche Integration erforderlich sind.

Für die Integration müssen Sie den fiskaly HUB, die Management API und die SIGN AT API nutzen.

Bevor Sie mit der Einrichtung beginnen, hier eine Übersicht der zu konfigurierenden Elemente:

🏢

Organisation

Ihre übergeordnete Einheit in fiskaly. Verwaltete Organisationen repräsentieren einzelne Händler.

🔑

API-Schlüssel & Secret

Im HUB generierte Zugangsdaten, die zur Authentifizierung aller nachfolgenden SIGN AT API-Anfragen verwendet werden.

🇦🇹

FON-Authentifizierung

FinanzOnline-Zugangsdaten des Steuerpflichtigen zur Aktivierung der Synchronisation mit der österreichischen Steuerbehörde.

🛡️

SCU (Signature Creation Unit)

Die zentrale Signierkomponente. Eine SCU pro verwalteter Organisation übernimmt die kryptografische Signierung von Belegen.

💻

Registrierkasse

Repräsentiert eine physische oder virtuelle Registrierkasse. Muss bei FinanzOnline registriert und initialisiert werden.

🧾

Beleg

Ein signierter RKSV-konformer Fiskalbeleg, der QR-Code-Daten und Belegmetadaten enthält.

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 Ausführen von HTTP-Anfragen – beispielsweise cURL (Kommandozeile), Postman oder Ihren eigenen Anwendungscode. Sie können unsere Postman-Sammlung herunterladen, die Ihre Integration erleichtern kann.

Integrationsablauf

Das nachstehende Diagramm veranschaulicht den Arbeitsablauf und hebt die wesentlichen Schritte hervor, die für eine erfolgreiche Integration erforderlich sind. Jede Kachel verweist direkt auf den entsprechenden Einrichtungsschritt weiter unten.

Schrittweise Einrichtung

Im Dashboard registrieren
Beginnen Sie mit der Registrierung im fiskaly HUB. Die Erstellung eines Kontos ist der erste Schritt, danach können Sie die Organisationsstruktur für Ihr Unternehmen in unserem System einrichten.
💡Schnell starten
Der HUB bietet einen geführten Onboarding-Ablauf, der Sie durch die Kontoerstellung und die Ersteinrichtung führt.
Erste Organisation erstellen
Fahren Sie mit der Erstellung Ihrer ersten Organisation über den HUB fort. Diese Organisation repräsentiert den POS-Anbieter oder Händler mit seinem eigenen POS-System. In diesem Schritt muss die Rechnungsadresse angegeben werden. Diese Adresse wird ausschließlich für Abrechnungszwecke von fiskaly verwendet.
💡Noch nicht für den Produktivbetrieb bereit?
Für Testzwecke müssen Sie nicht alle Felder ausfüllen. Sie können die Rechnungsadresse leer lassen und diese später ergänzen.
Verwaltete Organisationen erstellen
Nach der Einrichtung Ihrer ersten Organisation erstellen Sie verwaltete Organisationen. Jede verwaltete Organisation repräsentiert einen Händler, sodass Sie diese separat verwalten können. Wenn Sie Ihren Prozess automatisieren möchten, empfehlen wir die Nutzung des createOrganization-Endpunkts der Management API.
💡Automatisierung im großen Maßstab
Wenn Sie viele Händler verwalten, verwenden Sie die Management API, um verwaltete Organisationen programmgesteuert statt manuell über den HUB zu erstellen.
API-Schlüssel erstellen
Im nächsten Schritt generieren Sie einen API-Schlüssel innerhalb jeder verwalteten Organisation. Dies kann über den HUB oder den createApiKey-Endpunkt der Management API erfolgen. Dieses API-Schlüssel-Secret-Paar wird zur Generierung eines Zugriffstokens benötigt, das für alle nachfolgenden API-Aufrufe verwendet wird.
⚠️Zugangsdaten sicher aufbewahren
Das API-Secret wird nur einmal angezeigt. Stellen Sie sicher, dass Sie es kopieren und an einem sicheren Ort speichern, bevor Sie den Dialog schließen.
📘TEST vs. LIVE
Mit API-Schlüsseln aus der TEST-Umgebung generierte Ressourcen sind TEST-Ressourcen, während solche aus der LIVE-Umgebung LIVE-Ressourcen erzeugen. Weitere Informationen finden Sie in unserem Artikel über TEST- und LIVE-Umgebungen.
Ab dem nächsten Schritt verwenden Sie die SIGN AT API.
Mit der API authentifizieren
Verwenden Sie Ihren API-Schlüssel und Ihr Secret, um ein Zugriffstoken zu erhalten. Dieses Token ist für alle nachfolgenden Anfragen erforderlich.
curl -X POST https://rksv.fiskaly.com/api/v1/auth \ -H "Content-Type: application/json" \ -d '{ "api_key": "your_api_key", "api_secret": "your_api_secret" }'
Die Antwort enthält ein access_token, das Sie als Bearer-Token im Authorization-Header aller folgenden Anfragen angeben müssen.

FON authentifizieren

Nach der Authentifizierung mit dem zuvor generierten API-Schlüssel-Secret-Paar muss der authenticateFon-Endpunkt einmal pro Steuerpflichtigen aufgerufen werden.

Um die Synchronisation mit FinanzOnline zu ermöglichen, muss der Steuerpflichtige zunächst den „Kassensystem-Webservicebenutzer” direkt in FinanzOnline erstellen und Ihnen die Zugangsdaten dieses Benutzers mitteilen.

📘FON-Zugangsdaten sind separat

Die Zugangsdaten entsprechen nicht den allgemeinen FinanzOnline-Zugangsdaten. Sie entsprechen den Zugangsdaten des dedizierten Kassensystem-Webservicebenutzers, der vom Steuerpflichtigen erstellt wurde.

curl -X POST https://rksv.fiskaly.com/api/v1/fon/auth \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "fon_participant_id": "your_fon_participant_id",
    "fon_user_id": "your_fon_user_id",
    "fon_user_pin": "your_fon_user_pin"
  }'

const fonResponse = await fetch(
  "https://rksv.fiskaly.com/api/v1/fon/auth",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fon_participant_id: "your_fon_participant_id",
      fon_user_id: "your_fon_user_id",
      fon_user_pin: "your_fon_user_pin",
    }),
  }
);

SCU erstellen

Fahren Sie mit der Erstellung einer SCU über den createSignatureCreationUnit-Endpunkt fort. Pro verwalteter Organisation muss nur eine SCU erstellt werden. Nach der Erstellung hat eine SCU den Status CREATED.

SCU_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_entity_id": {
      "vat_id": "ATU12345678"
    }
  }'

const scuId = crypto.randomUUID();

const scuResponse = await fetch(
  `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      legal_entity_id: {
        vat_id: "ATU12345678",
      },
    }),
  }
);

📘Note

Ersetzen Sie ATU12345678 durch die tatsächliche UID des Steuerpflichtigen.

Registrierkasse(n) erstellen

Fahren Sie mit der Erstellung mindestens einer Registrierkasse über den createCashRegister-Endpunkt fort. Die Anzahl der Registrierkassen sollte der Anzahl der in einem bestimmten Geschäft oder einer Filiale verwendeten Registrierkassen entsprechen. Die Erstellung einer Registrierkasse setzt den Status auf CREATED.

CASH_REGISTER_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Main POS Terminal"
  }'

const cashRegisterId = crypto.randomUUID();

const crResponse = await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Main POS Terminal",
    }),
  }
);

SCU auf INITIALIZED aktualisieren

Für die Belegsignierung müssen sowohl die SCU als auch die Registrierkasse(n) auf INITIALIZED aktualisiert werden. Rufen Sie den updateSignatureCreationUnit-Endpunkt auf und setzen Sie den Status auf INITIALIZED. Dieser Statusübergang registriert die SCU automatisch im FinanzOnline-Portal.

curl -X PATCH "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "INITIALIZED"
  }'

await fetch(
  `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Registrierkasse(n) aktualisieren

Im Gegensatz zur Aktualisierung der SCU müssen Registrierkasse(n) zweimal über updateCashRegister aktualisiert werden:

a) Registrierkasse registrieren

Ändern Sie zuerst den Status der Registrierkasse auf REGISTERED. Dieser Statusübergang registriert die Registrierkasse automatisch im FinanzOnline-Portal.

curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "REGISTERED"
  }'

await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "REGISTERED",
    }),
  }
);

b) Registrierkasse initialisieren

Ändern Sie dann in einem zweiten Aufruf den Status auf INITIALIZED. Dieser Statusübergang löst die Erstellung und Validierung des Startbelegs im FinanzOnline-Portal aus.

curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "INITIALIZED"
  }'

await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      state: "INITIALIZED",
    }),
  }
);

Sowohl die SCU als auch die Registrierkasse sind nun bereit, Belege zu signieren.

Belege signieren

Nachdem alle vorherigen Schritte abgeschlossen sind, können Sie nun Belege über den signReceipt-Endpunkt signieren.

RECEIPT_ID=$(uuidgen)

curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}/receipt/${RECEIPT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_type": "NORMAL",
    "schema": {
      "standard_v1": {
        "receipt": {
          "amounts_per_vat_rate": [
            {
              "vat_rate": "STANDARD",
              "amount": "12.00"
            }
          ],
          "amounts_per_payment_type": [
            {
              "payment_type": "CASH",
              "amount": "12.00"
            }
          ]
        }
      }
    }
  }'

const receiptId = crypto.randomUUID();

const receiptResponse = await fetch(
  `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}/receipt/${receiptId}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      receipt_type: "NORMAL",
      schema: {
        standard_v1: {
          receipt: {
            amounts_per_vat_rate: [
              { vat_rate: "STANDARD", amount: "12.00" },
            ],
            amounts_per_payment_type: [
              { payment_type: "CASH", amount: "12.00" },
            ],
          },
        },
      },
    }),
  }
);

const signedReceipt = await receiptResponse.json();

SIGN AT stellt sicher, dass alle Belege RKSV-konform sind. Die Antwort enthält alle Informationen, die für die Ergänzung des endgültigen, an den Kunden ausgehändigten Belegs erforderlich sind:

qr_code_data — enthält die Daten für den RKSV-QR-Code, der in grafischer Form angezeigt werden soll
receipt_number, time_signature und cash_register_serial_number — Informationen zur Anzeige in Textform
Alle Rohbruttobeträge

💡Einrichtung automatisieren

Diese gesamte Anfragesequenz kann in eine „One-Click”-Provisionierungslösung integriert werden, die keine manuelle Benutzerinteraktion erfordert. Die Implementierungsdetails liegen bei Ihnen.

Nächste Schritte

SIGN AT API-Dokumentation

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

Belegdaten

Detaillierte Referenz für Belegfelder, MwSt.-Sätze und von SIGN AT unterstützte Zahlungsarten.

Glossar

Schlüsselbegriffe und Definitionen für das österreichische RKSV-Fiskalpflichtsystem.

HUB-Leitfaden

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

Was this page helpful?