EKDOS/docs/N8N.md

n8n-Schnittstelle

Alle Fachdaten von EK-DOS-WEB liegen in n8n. Das Backend hält davon nichts vor ausser einem kurzlebigen Cache.

Adressen

Der n8n-Hauptdienst auf Port 5678 ist ausschliesslich über https://n8n.elektro-krueger.eu erreichbar. Jeder weitere n8n-Dienst auf einem anderen Port ist nicht veröffentlicht und wird über 10.0.11.131 angesprochen.

In backend/src/N8n/Endpoints.php:

$url->webhook('/offene-tickets');            // https://n8n.elektro-krueger.eu/webhook/ek-dos-web/offene-tickets
$url->internal(5679, '/webhook/irgendwas');  // http://10.0.11.131:5679/webhook/irgendwas

Neue Adressen gehören in diese Klasse, nicht verstreut in die Controller.

Endpunkte

Alle unter /webhook/ek-dos-web. Die Spalte Cache nennt Gruppe sowie frische und Rückfall-Haltbarkeit in Sekunden.

Pfad	Verwendung	Cache
/offene-tickets	Ticketliste	tickets 15 / 600
/offene-tickets/kundenruecksprache	Ergebnis speichern	schreibend
/tickets/digitale-akte	PDF	–
/tickets/servicebericht	PDF	–
/angebote	Angebotsliste	offers 30 / 600
/angebote/versendet /beauftragt /zuruecksetzen /loeschen	Aktionen	schreibend
/kundenstamm	Kundenliste, Anlage, Änderung	customers 120 / 1800
/kundenstamm/digitale-akte	PDF	–
/rechnungen	Rechnungen eines Kunden	invoices 30 / 600
/rechnungen/alle	Gesamtübersicht (geschützt)	invoices 30 / 600
/rechnungen/zuordnen /sync	Zuordnung, Abgleich (geschützt)	schreibend
/rechnungen/pdf	PDF	–
/rechnungen-anfertigen	Aufgabenliste	invoices-create 30/600
/rechnungen-anfertigen/erledigt	Aufgabe abschließen	schreibend
/rechnungen-pruefen	Prüfliste	invoices-review 30/600
/rechnungen-versenden	Versandliste und -bestätigung	invoices-send 30/600
/digitale-akte	PDF als base64 im JSON	–
/interne-aufgaben (+ /erledigt /bearbeiten /loeschen)	Aufgaben	tasks 20 / 600
/online-kaeufe (+ /erledigt /loeschen)	Online-Käufe	purchases 30 / 600
/stundennachweise	Monatsreport	hours 300 / 3600

Geteilte Geheimnisse

Kopfzeile	aus	wofür
x-ekdos-invoice-sync	N8N_INVOICE_SYNC_SECRET	Rechnungsübersicht, Zuordnung, Abgleich, Kundenanlage, Angebot zurücksetzen
X-EK-DOS-Customer-Key	N8N_CUSTOMER_KEY	Lesen und Ändern im Kundenstamm
x-ekdos-webhook-secret	N8N_REFRESH_SECRET	n8n meldet EK-DOS eine Ticketänderung

Fehlt eines davon, antworten die betroffenen Routen mit 503 und einer Meldung, die genau das sagt -- sie schlagen nicht stumm fehl.

Der Kundenschlüssel stand in der Next.js-Fassung als Literal im Quelltext (app/api/customers/route.ts). Er liegt jetzt in .env. Er sollte in n8n gewechselt werden, weil der alte Wert in der Versionsgeschichte steht.

n8n meldet eine Ticketänderung

Der Workflow Datenübergabe an EK-DOS-WEB darf weiter auf seinen Endpunkt zeigen, nur ohne Port:

POST https://schulung.elektro-krueger.local/api/tickets/refresh
x-ekdos-webhook-secret: <N8N_REFRESH_SECRET>

Anders als früher ist das kein Platzhalter mehr. In der Next.js-Fassung antwortete die Route nur {ok:true} und tat sonst nichts; die Oberfläche sah neue Tickets rein zufällig beim nächsten 20-Sekunden-Takt. Jetzt verwirft der Aufruf den Ticket-Cache, sodass die nächste Abfrage die neuen Daten garantiert sieht.

Ohne gesetztes N8N_REFRESH_SECRET verlangt die Route eine angemeldete Sitzung und weist den Aufruf aus n8n mit 401 ab.

Feldabbildung Tickets

Die einzige Stelle, an der das Backend n8n-Felder umbenennt (backend/src/Relay/TicketsController.php):

n8n	Oberfläche
ticketnummer / id	id
kunde / customer	customer
liegenschaft / property	property
letzter_servicebericht_status	reportStatus
fortsetzung	continuation
entscheidung_code	decisionCode
kundenruecksprache_ergebnis	consultationResult
kundenruecksprache_am / _von	consultationUpdatedAt / By

requiresCustomerConsultation wird abgeleitet: entweder entscheidung_code === "TEILERLEDIGUNG_RUECKSPRACHE_KUNDE", oder der Fortsetzungstext enthält „nimmt mit Kunden für das weitere Vorgehen Kontakt auf". Zeilen ohne Ticketnummer werden verworfen.

Bekannte Kopplung

Interne Aufgaben kennen in n8n genau zwei Empfänger: sascha und svenja. Ein drittes EK-DOS-Konto kann sich anmelden und alle Ansichten nutzen, aber noch keine Aufgaben zugewiesen bekommen. Dafür müsste der n8n-Workflow Interne Aufgaben einen freien Empfängerschlüssel annehmen.