Setup-Wizard durchklicken (Erst-Einrichtung)

KI

Wann taucht der Wizard auf?

Der Setup-Wizard erscheint automatisch für den initial vergebenen Setup-User nach Mandant-Provisioning — gesteuert über die Keycloak-Rolle APP_SPEAMCORE_DO_SETUP_WIZARD. Sobald Sie den Wizard mit Fertigstellen oder Überspringen verlassen, wird die Rolle entzogen und Sie sehen den Wizard nicht mehr.

Aufruf jederzeit möglich unter /setup-wizard (sofern die Rolle noch vorhanden ist) — z. B. wenn Sie Schritte später nachholen möchten. Bei wiederholtem Aufruf: bereits erledigte Schritte sind als ✓ markiert.

Direct-Check (seit Welle 115): Beim Login prüft SpeamCore über den Endpoint GET /api/setup/role-direct, ob die Wizard-Rolle Ihrem Account direkt zugewiesen ist (so kann sie beim Klick auf Fertigstellen sauber wieder entzogen werden). Wurde die Rolle nur per Keycloak-Gruppe geerbt, würde der Cleanup fehlschlagen und Sie würden bei jedem Login wieder im Wizard landen — in diesem Fall überspringt SpeamCore den Wizard-Redirect bewusst. Bei einem Fehler im Direct-Check (Netzwerk, BE down) sehen Sie den Wizard trotzdem, damit niemand auf einer leeren Seite stehenbleibt.

Modul-Doku mit Frontmatter + CASL: /setup-wizard.

Bei einem neuen Mandanten in SpeamCore führt der Setup-Wizard durch 12 Konfigurations-Schritte — von Firmen-Stammdaten bis Mailbox. Diese Anleitung zeigt Ihnen jeden Schritt mit konkreten Eingaben und Begründungen.

Wann mache ich das?

• Nach Mandant-Provisioning — als Initial-Admin (typisch IT/Kevin oder Mandanten-GF mit Admin-Rolle).
• Bei nachträglichem Setup — wenn Sie Schritte beim ersten Mal übersprungen haben und sie jetzt nachholen.
• Beim Konfigurations-Test — neuer Demo-Mandant für Schulungen.

i

Voraussetzung

• Sie haben die Keycloak-Rolle APP_SPEAMCORE_DO_SETUP_WIZARD (CASL: do:SetupWizard).
• Mandant ist im Tenant-Provisioning-Tool angelegt.
• Firmen-Daten liegen vor (Adresse, Steuernummer, USt-IdNr).
• Optional: Logo-Datei, Bankzugangsdaten (für finAPI), DATEV-Beraternummer.

Wizard-Übersicht — die 12 Schritte

#	Schritt	Anforderung	Was wird konfiguriert?
1	Firmen-Stammdaten	Pflicht	Firmenname, Anschrift, Steuernr., USt-IdNr., HRB, GF
2	Sprache & Region	Pflicht	Standard-Sprache (DE/EN), Bundesland für Feiertage
3	Branding	optional	Logo, primaryColor, secondaryColor (für UiConfig/Customization)
4	SKR03-Kontenrahmen	empfohlen	DE-Standard-Kontenrahmen + Steuersätze + PEPPOL-Kategorien
5	DATEV-Settings	optional	Beraternr., Mandantennr., Geschäftsjahres-Beginn, Sachkontenlänge
6	Bankkonto	optional	manuell oder finAPI-OAuth
7	Master-Sync	empfohlen	Units + HS-Codes vom Master
8	Zahlungsziele	empfohlen	DE-Presets („14 Tage netto", „14 Tage 2% Skonto / 30 Tage netto", …)
9	Arbeitszeitmodelle	empfohlen	Presets („Vollzeit 40h Mo-Fr", „Teilzeit 20h", „4-Tage-Woche")
10	Standard-Textbausteine	empfohlen	Rechnungsfußtext, §14 UStG-Pflichtangaben, AGB-Hinweis, Mahn-Texte
11	Nummernkreise reviewen	Review	Bestehende NumberCircle-Records prüfen, ggf. Präfixe anpassen
12	Mailbox verbinden	optional	Direkt-Link auf /mail-accounts mit M365-Connect

Anforderungs-Stufen:

• Pflicht — kann nicht übersprungen werden, blockiert Wizard-Abschluss
• Empfohlen — kann übersprungen werden, aber dringend angeraten
• Optional — kann jederzeit später nachgeholt werden
• Review — bestehende Daten prüfen, bei Bedarf anpassen

Schritt für Schritt

1

Firmen-Stammdaten — Pflicht

Tragen Sie die rechtlichen Firmen-Daten ein:

Feld	Beispiel	Hinweis
Firmenname	KFT Sicherheitstechnik GmbH	exakter Name aus Handelsregister
Straße + Hausnummer	Musterstraße 12
PLZ + Stadt	70173 Stuttgart
Land	Deutschland
Steuernummer	12/345/67890	Finanzamt-Format
USt-IdNr.	DE123456789	wird über VIES validiert
Handelsregister	HRB 12345 Stuttgart	freiwillig aber empfohlen
Geschäftsführung	Max Müller, Anna Schmidt	mehrere möglich

Speichern → ✓ markiert.

2

Sprache & Region — Pflicht

Feld	Beispiel
Standard-Sprache	Deutsch (DE) — alternativ Englisch (EN)
Bundesland	Baden-Württemberg — relevant für Feiertage und ggf. Steuersätze

Das Bundesland steuert die geo-states/:id/holidays-Liste, die in Mitarbeiter-Abwesenheits-/Arbeitszeit-Berechnung verwendet wird.

3

Branding — optional

Visuelle Anpassung des Mandanten-Auftritts:

• Logo-Upload (PNG/SVG empfohlen, transparenter Hintergrund) — wird in PDFs (Rechnungen, Angebote, Verträge) und in der App-Top-Bar verwendet
• primaryColor (Hex, z. B. #0066CC) — Akzentfarbe der Buttons + Highlights
• secondaryColor (Hex) — Sekundärfarbe für Diagramme + Badges

Kann später jederzeit über /customization/general angepasst werden.

4

SKR03-Kontenrahmen — empfohlen

One-Click-Setup für deutsche Buchhaltungs-Standards:

Klick auf „Standards (DE) laden" lädt:

• ~250 SKR03-Konten (Kontenrahmen für Kapitalgesellschaften)
• Standard-Steuersätze (19% / 7% / 0% mit historischen Gültigkeiten)
• PEPPOL-Steuerkategorien für ZUGFeRD/XRechnung
• Skonto/Bonus/Rabatt-Verknüpfungen zu den passenden Konten

Wichtig: Wenn der Steuerberater einen anderen Kontenrahmen möchte (z. B. SKR04), diesen Schritt überspringen — nicht mehrfach laden, sonst Duplikate.

5

DATEV-Settings — optional

Wenn der Steuerberater DATEV nutzt, hier die Schnittstellen-Daten:

Feld	Beispiel
Beraternummer	123456 (vom Steuerberater)
Mandantennummer	78910
Geschäftsjahres-Beginn	01.01. (Standard) oder z. B. 01.07. bei abweichendem Geschäftsjahr
DATEV-Sachkontenlänge	4 oder 8 (Standard 4 für mittelständische Unternehmen)

Ohne DATEV-Anbindung: Schritt überspringen. Daten können später unter Settings → DATEV ergänzt werden.

6

Bankkonto — optional

Zwei Wege:

Weg A — manuell:

• IBAN, BIC, Bankname, Inhaber
• Geht für alle deutschen Banken; keine Live-Sync

Weg B — finAPI-OAuth:

• Online-Banking-Login direkt aus dem Wizard
• Sync via finAPI alle 4 Stunden (Banking-Sync-Cron)
• Auto-Allokation auf Open-Items möglich

Falls Bankzugang nicht griffbereit: überspringen, später unter /transaction-accounts nachholen.

7

Master-Sync — empfohlen

Master-Daten vom SpeamCore-Master ziehen:

• Units — Maßeinheiten (Stück, Stunde, Meter, …) — ~80 Einheiten
• HS-Codes — Zolltarif-Klassifikationen — ~5000 Einträge

Beide werden zentral vom SpeamCore-Master gepflegt (siehe Mandanten — Master-Sync). Nach dem Sync sind sie im Mandanten verfügbar.

Wichtig: Diese Daten sind read-only-Sync — Änderungen am Master überschreiben sie. Mandanten-spezifische Anpassungen (z. B. eigene Maßeinheit) gehen verloren.

8

Zahlungsziele — empfohlen

DE-Presets per Klick laden:

Preset	Bedeutung
Sofort fällig	Zahlung bei Erhalt
14 Tage netto	14 Tage Zahlungsziel ohne Skonto
30 Tage netto	30 Tage Zahlungsziel
14 Tage 2% Skonto / 30 Tage netto	klassisches Skonto-Modell
60 Tage netto	für B2B-Großkunden

Hinweis: Wenn Skonto verwendet wird, muss in DATEV das passende Skonto-Sachkonto verknüpft sein. Der Wizard zeigt einen Hinweis-Box dazu.

9

Arbeitszeitmodelle — empfohlen

Presets für typische Konstellationen:

Preset	Tage	Stunden
Vollzeit 40h Mo-Fr	5	8 / Tag
Vollzeit 38,5h	5	7,7 / Tag
Teilzeit 20h Mo-Fr	5	4 / Tag
4-Tage-Woche 32h	4	8 / Tag

Werden in Mitarbeiter-Verträgen verwendet (siehe Arbeitsvertrag erstellen). Nachträglich editierbar unter /work-time-models.

10

Standard-Textbausteine — empfohlen

DE-Defaults für Belege:

• Rechnungsfußtext — Bankverbindung, Geschäftsbedingungen-Hinweis, Steuer-Hinweis
• §14 UStG-Pflichtangaben — Pflicht-Felder für Rechnungen (Steuernummer, Leistungsdatum, …)
• AGB-Hinweis — Verweis auf hinterlegte AGB
• Mahn-Texte — Vorlagen für Stufe 1, 2, 3

Werden via TextBlock verwaltet. Nach dem Wizard editierbar.

11

Nummernkreise reviewen — Review

Der Wizard zeigt die bestehenden NumberCircle-Einträge:

Beleg-Typ	Beispiel-Nummer
Sales Document (Rechnung)	RE-2026-00001
Purchase Document (Eingangsrechnung)	ER-2026-00001
Workorder (Auftrag)	WOR-2026-00001
Project Request	PR-2026-00001
Inventory	INV-2026-00001

Falls ein Mandant ein anderes Schema möchte (z. B. RG statt RE für Rechnungen, oder ohne Jahres-Suffix), hier anpassen. Vorsicht: nachträgliche Änderungen sind möglich, aber alte Nummern werden nicht umnummeriert.

12

Mailbox verbinden — optional

Direkt-Link auf /mail-accounts mit Microsoft 365-Connect-Flow. Wenn der Mandant M365 nutzt:

1. „Mit Microsoft 365 verbinden" klicken
2. OAuth-Flow durchlaufen
3. Mailbox wird in SpeamCore eingerichtet, Mail-Sync-Worker startet

Ohne M365: überspringen. Mail-Versand funktioniert dann über das Standard-SMTP, das in den Settings konfiguriert wird.

Nach den 12 Schritten — Fertigstellen

Mit Fertigstellen signalisiert der Admin: alle gewünschten Schritte sind erledigt. Das System:

1. Schreibt Audit-Log-Eintrag (wer, wann, abgeschlossen)
2. Entzieht die Keycloak-Rolle APP_SPEAMCORE_DO_SETUP_WIZARD
3. Forciert einen Token-Refresh im Browser (signinSilent())
4. Wizard verschwindet, Redirect zur Home-Seite

Überspringen statt Fertigstellen

Wenn Sie noch nicht alle Schritte erledigen können (z. B. Logo fehlt, finAPI-Zugang noch nicht da), klicken Sie auf Überspringen. Auswirkungen:

• Audit-Log: „Setup übersprungen, Status: 5/12 erledigt"
• Keycloak-Rolle wird trotzdem entzogen — der Wizard erscheint nicht mehr
• Übersprungene Schritte können später über die jeweiligen Module nachgeholt werden:
  • Branding → /customization/general
  • SKR03 → /transaction-accounts
  • DATEV → /settings
  • Bankkonto → /transaction-accounts
  • Master-Sync → /units, /hscodes
  • usw.

Stolpersteine

!

SKR03 mehrfach laden

Wenn Sie versehentlich „Standards (DE) laden" zweimal klicken, werden ~250 Konten doppelt angelegt. Lösung: Doubletten manuell löschen oder Mandant verwerfen + neu provisionieren. Vor dem zweiten Klick prüfen, ob die Konten schon da sind.

!

Wizard verlassen ohne Finish/Skip

Wenn Sie den Browser-Tab schließen ohne Finish/Skip, bleibt die Keycloak-Rolle bestehen — der Wizard erscheint beim nächsten Login wieder. Bewusst entscheiden: erledigen oder überspringen.

!

USt-IdNr. ungültig

Die VIES-Validierung kann temporär fehlschlagen (VIES-Server down). Wenn Sie sicher sind dass die ID korrekt ist, mit Hinweis-Toast „bitte später erneut prüfen" trotzdem speichern. SpeamCore validiert nightly erneut.

!

finAPI-Bank nicht angeboten

Nicht alle Banken sind über finAPI erreichbar. Wenn Ihre Bank fehlt: manuell anlegen mit IBAN/BIC, Banking-Sync läuft dann nicht automatisch — alternativ MT940/CAMT-Datei-Upload.

Verwandte Tutorials

• Modul-Doku /setup-wizard — CASL + Frontmatter
• Settings + Customization
• Mandanten-Setup für GF
• Buchhaltungskonten-Konzept