Integrierungsplanung

Diese Seite richtet sich an Produktmanager und technische Leads, die eine fiskaly-Integrierung planen. Sie enthält Aufwandsschätzungen, Teamanforderungen, Produkt-Abhängigkeiten, Konformitäts-Meilensteine und eine Rollout-Zeitplan-Vorlage.

💡Für Entwickler

Wenn Sie Code schreiben möchten, starten Sie stattdessen mit dem Quick Start.

Schritt 1: API-Architektur wählen

fiskaly bietet zwei API-Architekturen. Ihre Wahl hängt davon ab, welche Länder Sie benötigen:

Wenn Sie benötigen…	Verwenden Sie…	Warum
Nur Deutschland, Österreich oder Spanien	Spezialisierte API für das Land	Speziell entwickelt, tiefste länderspezifische Unterstützung
Nur Frankreich oder Italien	Unified API	Multi-Country-Architektur — das andere hinzuzufügen dauert ~1 Woche
Frankreich + Italien (oder + Schweden)	Unified API	Einmal integrieren, durch Schema-Änderung expandieren
Deutschland + Frankreich/Italien	Beide	Spezialisierte API für DE + Unified API für FR/IT. Gleiches Auth-Muster, unterschiedliche Ressourcenmodelle.
3+ Länder einschließlich FR/IT	Mit Unified API beginnen	Dann Spezialisierte APIs für DE/AT/ES bei Bedarf hinzufügen

Siehe Die Unified API für den vollständigen Architekturvergleich, das Ressourcenmodell und das Terminologie-Mapping.

Schritt 2: Produktumfang bestimmen

Welche fiskaly-Produkte Sie benötigen, hängt davon ab, wo Sie tätig sind und welche Regulierungen gelten. Verwenden Sie diesen Entscheidungsbaum:

Betreiben Sie POS-Systeme in einem dieser Länder?

• Deutschland -> SIGN DE + DSFinV-K + SUBMIT DE (alle drei verpflichtend)
• Österreich -> SIGN AT
• Frankreich -> SIGN FR (NF525-Zertifizierung erforderlich)
• Spanien -> SIGN ES (TicketBAI oder Verifactu, je nach Region)
• Italien -> SIGN IT
• Schweden -> SIGN SE (InfraSec TCS)
• Belgien -> E-Invoice (nur B2B, über Peppol)

Benötigen Sie konformes Langzeitarchiv? -> SAFE oder SAFE flex hinzufügen

Möchten Sie Papierbelege ersetzen? -> eReceipt hinzufügen (optional, jedes EU-Land)

Deutschland ist am komplexesten

Deutschland erfordert drei Produkte, die zusammenarbeiten. Hier ist ihre Beziehung:

SIGN DE (Transaktionssignierung)
  |
  +--> DSFinV-K (Fiskalexport-Generierung, referenziert SIGN DE-Daten)
  |
  +--> SUBMIT DE (ELSTER-Einreichung, referenziert SIGN DE-Clients und TSS)
  |
  +--> SAFE (optionale Archivierung von Exporten)

Für andere Länder ist SIGN typischerweise die einzige verpflichtende Integrierung.

Schritt 3: Integrierungsaufwand schätzen

Dies sind typische Zeitpläne für ein Team aus 1–2 Backend-Entwicklern mit POS-Domänenerfahrung. Ihr tatsächlicher Zeitplan hängt von Ihrer POS-Architektur, Ihrem Release-Rhythmus und Ihren Testanforderungen ab.

Spezialisierte APIs (SIGN DE, SIGN AT, SIGN ES)

Produkt	Erste Integrierung	Ab SIGN DE	Hinweise
SIGN DE	4–8 Wochen	—	TSS-Bereitstellung, Transaktionssignierung, Beleg-QR-Code, Fehlerbehandlung
SIGN AT	3–5 Wochen	1–2 Wochen	SIGN DE am ähnlichsten. SCU statt TSS, FinanzOnline-Registrierung.
SIGN ES	5–7 Wochen	2–4 Wochen	Zertifikatsverwaltung, 6 Rechnungstypen, Echtzeit-Einreichung

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

Produkt	Erstes Unified API-Land	Jedes weitere	Ab SIGN DE	Hinweise
SIGN FR	4–6 Wochen	—	1–3 Wochen	NF525-Zertifizierung fügt separat 4–8 Wochen hinzu
SIGN IT	4–6 Wochen	—	1–3 Wochen	Belegslotterie, Verbindungsverlust-Handling
FR + IT	4–6 Wochen (erst)	~1 Woche (zweite)	—	Gleiches Ressourcenmodell — nur Payload und Taxpayer-Fiskalisierung unterscheidet sich
SIGN SE	2–4 Wochen	—	—	Derzeit InfraSec TCS (XML, X.509); Unified API folgt

Ergänzende Produkte

Produkt	Dauer	Hinweise
DSFinV-K	2–4 Wochen	Nur Deutschland. POS-Datenmodell auf DSFinV-K-Taxonomie abbilden.
SUBMIT DE	1–2 Wochen	Nur Deutschland. Einfach, wenn SIGN DE bereits integriert ist.
SAFE	1 Woche (SAFE) / 2 Wochen (flex)	SAFE verknüpft sich automatisch mit SIGN; SAFE flex erfordert manuelle Upload-Logik.
E-Invoice	2–4 Wochen	Belgien live; andere folgen. Separat von SIGN.
eReceipt	1–2 Wochen	Länderunabhängig. Hauptsächlich Frontend-Arbeit (QR-Anzeige).

Typischer Deutschland-Zeitplan

Woche 1–2:  Konto-Einrichtung, Sandbox-Zugang, SIGN DE Auth + TSS-Bereitstellung
Woche 3–5:  Transaktionssignierung, Beleggenerierung, Fehlerbehandlung
Woche 5–6:  DSFinV-K-Mapping und Export-Generierung
Woche 6–7:  SUBMIT DE-Integrierung
Woche 7–8:  End-to-End-Tests in der Sandbox
Woche 8–9:  Go-Live-Vorbereitung, LIVE-Umgebungs-Bereitstellung
Woche 9–10: Produktions-Rollout, Monitoring

Gesamt: ~10 Wochen vom Kickoff bis zur Produktion für Deutschland (SIGN DE + DSFinV-K + SUBMIT DE).

Multi-Country-Rollout-Zeitplan

Wenn Sie von einer bestehenden SIGN DE-Integrierung expandieren:

Woche 1:    Zielland-Dokumentation prüfen, Payload-Unterschiede identifizieren
Woche 2:    Länderspezifischen Adapter implementieren, Sandbox-Tests
Woche 3:    QA, Beleg-Konformitätsvalidierung, Go-Live

Gesamt: ~3 Wochen pro weiteres Land (AT, FR, IT, ES).

Schritt 4: Team planen

Rolle	Verantwortlichkeit	Wann erforderlich
Backend-Entwickler (1–2)	API-Integrierung, Transaktionssignierung, Fehlerbehandlung, Wiederholungslogik	Gesamter Integrierungszeitraum
Frontend-Entwickler (0–1)	Beleg-Rendering, QR-Code-Anzeige, eReceipt-UI	Nach funktionierender Backend-Signierung
QA-Ingenieur (1)	End-to-End-Tests, Konformitätsvalidierung, Grenzfälle (Timeouts, Offline)	Ab Woche 5+
Produktmanager	Umfangsentscheidungen, Konformitätsanforderungen, Go-Live-Checkliste	Durchgehend
DevOps / Infrastruktur (0–1)	Secret-Verwaltung, Monitoring, Alerting bei Signierungsfehlern	Go-Live-Vorbereitung

Schritt 5: Konformitäts-Checkliste verstehen

Prüfen Sie vor dem Go-Live in jedem Land diese Punkte:

Universelle Checkliste (alle Länder)

• API-Zugangsdaten in einem Secret-Manager gespeichert (nicht im Quellcode)
• Token-Caching implementiert (keine erneute Authentifizierung pro Transaktion)
• Wiederholungslogik mit exponentiellem Backoff für 5xx- und Timeout-Fehler
• Signierungstimeout konfiguriert (3–5 Sekunden) und blockiert nicht den Kassierprozess
• Beleg enthält alle Pflichtfelder für das Zielland
• Fehlerbehandlung deckt TSS-Nichtverfügbarkeit ab (siehe Fehlerbehandlungs-Guide)
• TEST-Umgebungs-Integrationstests bestanden
• LIVE-Umgebung über HUB bereitgestellt
• Monitoring/Alerting für Signierungsfehler und Latenz eingerichtet

Deutschland-spezifische Checkliste

• TSS erstellt, Admin-PIN gesetzt und TSS initialisiert
• Client für jedes POS-Terminal erstellt
• Beleg enthält KassenSichV-QR-Code (siehe Belegdaten)
• QR-Code validiert korrekt (siehe QR-Code-Validierung)
• DSFinV-K-Export generiert und validiert
• SUBMIT DE-Meldung erfolgreich an ELSTER übermittelt
• Admin-Abmeldung nach der Bereitstellung

Frankreich-spezifische Checkliste

• NF525-Zertifizierungsprozess mit fiskaly-Support gestartet
• Periodenabschlüsse implementiert (täglich, monatlich, jährlich)
• Archiv-Generierung automatisiert
• Offline-Replay-Modus getestet

Italien-spezifische Checkliste

• Felder der Belegslotterie (Lotteria degli Scontrini) enthalten
• Verbindungsverlust-Handling getestet
• Steuerpflichtigen-Standort- und Systemzustände korrekt verwaltet

Schritt 6: Go-Live-Vorbereitung

1. Sandbox-Tests abschließen

   Führen Sie Ihre vollständige Testsuite gegen die TEST-Umgebung aus. Prüfen Sie alle Transaktionstypen, Fehlerszenarios und Export-Generierung.

2. LIVE-Zugang beantragen

   Wechseln Sie Ihre Organisation über HUB in die LIVE-Umgebung. Kontaktieren Sie Ihren Account-Manager, wenn Sie Unterstützung benötigen.

3. LIVE-Ressourcen bereitstellen

   Ressourcen aus TEST werden nicht übertragen. Führen Sie Ihren Bereitstellungsablauf (TSS-Erstellung, Client-Registrierung) in der LIVE-Umgebung erneut durch.

4. Schrittweiser Rollout

   Starten Sie mit einem einzigen Standort oder Terminal. Überwachen Sie Signierungslatenz, Fehlerraten und Beleg-Konformität für 1–2 Wochen, bevor Sie expandieren.

5. Monitoring einrichten

   Verfolgen Sie: Signierungserfolgsrate, durchschnittliche Signierungslatenz, 401-Fehlerrate (Token-Refresh-Probleme) und 5xx-Fehlerrate (Dienstprobleme). Alerting bei einer Signierungsfehlerrate > 1%.

⚠️TEST und LIVE sind vollständig getrennt

TSS, Clients, Transaktionen und Exporte, die in TEST erstellt wurden, existieren in LIVE nicht. Ihre Go-Live-Bereitstellung muss einen Bereitstellungsschritt umfassen.

Wichtige Links für PMs

Produktübersicht

Was jedes Produkt leistet und wann Sie es benötigen

Länderabdeckung (E-Invoice)

Wann neue Länder-Module verfügbar werden

SAFE vs. SAFE flex

Welche Archivierungsoption zu Ihrem Anwendungsfall passt

Fehlercodes-Referenz

Jeder Fehler, dem Ihr Team begegnen wird, und wie er zu lösen ist

HUB (Dashboard)

Organisationen, API Keys und Konformitätsexporte ohne Code verwalten

Changelog

API-Änderungen, neue Funktionen und Deprecation-Hinweise