← Übersicht

Rechnungs-Download und Buchhaltung

Frühere Version vom 2026-07-16T17:50:13.091757+02:00 · zur aktuellen Fassung

Rechnungs-Download und Buchhaltung

Orientierung für interessierte Laien

Der Prozess holt Rechnungen aus dem WEtell-Kundenkonto und übergibt sie an Lexoffice. WEtell ist die Quelle, Lexoffice das Buchhaltungsziel. Die PDF bleibt zusätzlich lokal als Originalbeleg erhalten.

Die Code-Links zeigen auf die jeweilige Datei in der `/code`-Ansicht. Die genannten Klassen und Methoden sind die darin enthaltenen Symbole. Die Architektur trennt fachliche Regeln von technischen Adaptern: Ein Use Case beschreibt, was fachlich geschieht; ein Port beschreibt eine benötigte Fähigkeit; ein Adapter verbindet diese Fähigkeit mit WEtell, Lexoffice, PDF-Werkzeugen oder Dateien.

1. Prozess starten und orchestrieren

`run-rechnung.php` lädt die Konfiguration für WEtell und Lexoffice, baut die Adapter zusammen und startet den zentralen Ingestions-Use-Case. Ein Use Case ist ein klar abgegrenzter Anwendungsvorgang. Das Ergebnis wird als JSON ausgegeben.

Relevante Symbole

2. Bei WEtell anmelden und Rechnungen entdecken

Ziel dieses Teilprozesses ist eine belastbare Liste der Rechnungen, die WEtell für das angemeldete Kundenkonto bereitstellt. In diesem Abschnitt wird noch keine PDF gebucht und kein Lexoffice-Kontakt verändert. Es werden nur Zugang, Sitzung und Rechnungsmetadaten vorbereitet.

2.1 Lauf und Konfiguration vorbereiten

  1. `run-rechnung.php` erzeugt beziehungsweise übernimmt eine Lauf-ID. Diese ID verbindet Logeinträge und alle späteren Zustandsänderungen eines Durchlaufs.
  2. Die WEtell-Konfiguration wird aus der vorgesehenen Credential-Konfiguration geladen. Benutzername und Passwort werden nur zur Laufzeit verwendet.
  3. Die Konfiguration wird auf erforderliche Werte geprüft. Fehlende WEtell-Zugangsdaten führen zu einem kontrollierten Fehler, bevor ein Loginversuch startet.
  4. Die Zieladressen des Headless-Services, Zeitlimits und optionalen Fallbacks werden aus der Konfiguration übernommen.
  5. Der PHP-Prozess erstellt den fachlichen `WetellSourcePort`. Dadurch kennt der Use Case nur die Fähigkeiten `login`, `discoverInvoices` und später `downloadInvoicePdf`, nicht die konkrete Browsertechnik.

2.2 Zugangsmethode auswählen

Der bevorzugte Zugang ist der bereitgestellte Node.js-/Playwright-Service. Die PHP-Anwendung steuert den Browser nicht direkt, sondern spricht den Service über den `HeadlessWetellSourceAdapter` an. Dadurch bleibt die Browserinstanz von der Buchungslogik getrennt.

Wenn der Headless-Service nicht erreichbar ist oder ausdrücklich anders konfiguriert wurde, kann der `FallbackWetellSourceAdapter` auf den alternativen `HttpWetellSourceAdapter` zurückgreifen. Der Fallback ist eine technische Ausweichroute, keine zweite fachliche Verarbeitung. Es wird nur eine Quelle erfolgreich verwendet.

2.3 Headless-Aufruf absichern

  1. Der Adapter erstellt eine interne Aktion für `login` oder `discover`.
  2. Er übergibt nur die notwendigen Lauf- und Zugangsdaten an den lokalen Headless-Service.
  3. Der Service prüft die Anfrage und, sofern konfiguriert, ein gemeinsames Geheimnis zwischen PHP und Node.js.
  4. Der Service antwortet als JSON. HTTP-Fehler, Timeout oder ungültiges JSON werden nicht als erfolgreiche Anmeldung behandelt.
  5. Der Adapter wandelt die technische Antwort wieder in das fachliche Ergebnis des `WetellSourcePort` um.

2.4 Playwright-Sitzung herstellen

  1. Der Headless-Service öffnet einen isolierten Browser-Kontext.
  2. Der Kontext erhält die konfigurierten Laufzeitparameter, etwa User-Agent und Timeout.
  3. Eine neue Seite wird geöffnet und zur WEtell-Anmeldeseite navigiert.
  4. Die Seite wird auf den erwarteten DOM-Zustand geprüft. Ein unerwarteter Redirect oder eine nicht erreichbare Seite beendet den Schritt mit Fehler.
  5. Loginformular, Formularaktion und relevante Eingabefelder werden aus der Seite bestimmt, statt feste Sitzungswerte vorauszusetzen.

Die Sitzung bleibt innerhalb des aktuellen Dienstaufrufs gekapselt. Nach dem Ergebnis werden Seite, Kontext und Browserressourcen geschlossen, damit keine alte Sitzung unkontrolliert in den nächsten Lauf hineinwirkt.

2.5 Anmeldedaten übermitteln

  1. Benutzername und Passwort werden in das erkannte Formular eingesetzt.
  2. Das Formular wird an die erkannte WEtell-Aktion abgesendet.
  3. Der Service wartet auf den dokumentierten Ladezustand und berücksichtigt sowohl `domcontentloaded` als auch den Netzwerkzustand mit einem Timeout.
  4. Danach wird nicht nur der HTTP-Status bewertet. Die Seite wird zusätzlich inhaltlich darauf geprüft, ob sie als angemeldete Kontoseite erkennbar ist.
  5. Eine weiterhin sichtbare Loginseite, ein Fehlhinweis oder ein abweichender Zielzustand gilt als fehlgeschlagene Anmeldung.

Passwörter werden nicht in `rechnungen.json`, im Dokumentationsdatensatz oder in den fachlichen Rechnungsobjekten gespeichert.

2.6 Rechnungsübersicht öffnen

  1. Nach erfolgreicher Anmeldung navigiert der Service zur konfigurierten WEtell-Rechnungsübersicht.
  2. Die Seite wird geladen und als HTML-Dokument ausgelesen.
  3. Der Service sucht Rechnungszeilen, PDF-Links und die sichtbaren Begleitdaten im DOM.
  4. Für jede erkannte Zeile werden die verfügbaren Angaben wie Rechnungs-URL, Quell-ID, technische Dateibezeichnung sowie sichtbare Datums- oder Nummernhinweise zusammengeführt.
  5. Absolute und relative Links werden zu normalisierten URLs aufgelöst. Fehlende oder offensichtlich externe/ungültige Downloadziele werden nicht als gültige Rechnungsquelle ausgegeben.

2.7 Rechnungsobjekte erzeugen

Für jede erkannte Rechnung entsteht ein `SourceInvoice`. Dieses Objekt ist noch keine Buchung. Es beschreibt ausschließlich, was die Quelle WEtell geliefert hat:

Die Hinweise aus der Übersicht sind vorläufig. Die verbindliche Rechnungsnummer und der verbindliche Lieferant werden erst später aus der tatsächlich heruntergeladenen PDF extrahiert.

2.8 Entdeckungsergebnis bewerten

  1. Die Liste wird an `DiscoverInvoicesUseCase::execute` zurückgegeben.
  2. Ein leerer, aber technisch erfolgreicher Rechnungsbestand bedeutet: WEtell ist erreichbar, es wurde aber keine Rechnung gefunden.
  3. Ein technischer Fehler bedeutet dagegen: Login, Navigation oder Extraktion konnte nicht zuverlässig abgeschlossen werden.
  4. Nur valide `SourceInvoice`-Objekte gelangen in die nächsten Schritte.
  5. Für jedes Objekt wird anschließend der Rechnungsschlüssel gebildet und gegen den lokalen Zustand geprüft. Die eigentliche Duplikatentscheidung erfolgt im zentralen Ingestions-Use-Case.
  6. Erst nach diesem Teilprozess darf `DownloadInvoiceUseCase` den PDF-Inhalt anfordern.

2.9 Fehlerbilder und Zustände

Bei Fehlern wird kein Download als erfolgreich markiert und es wird keine Lexoffice-Aktion ausgelöst. Die Fehlerzuordnung erfolgt über Lauf-ID, Schrittname und Logger.

Relevante Symbole

3. Rechnung herunterladen und Original speichern

Die gefundene Download-URL wird nicht ungeprüft als Beleg akzeptiert. Der Dateiinhalt wird geladen und als PDF validiert. Danach wird die Originaldatei datums- und lieferantenbezogen unter `rechnungen/originale/` gespeichert. Der SHA-256-Wert ist ein digitaler Fingerabdruck der gespeicherten Datei.

Relevante Symbole

4. PDF-Inhalt extrahieren und fachlich prüfen

Nach dem Download wird die PDF gelesen. Zuerst wird der normale Textextraktor verwendet. Ist der Textlayer unbrauchbar oder fehlt er, greift der Fallback über OCR. OCR bedeutet Texterkennung aus dem Bild einer Seite.

Aus dem PDF werden Lieferant, Anschrift, echte Rechnungsnummer, Rechnungsdatum sowie Beträge gelesen. Die fachlichen Prüfungen stellen sicher, dass Pflichtfelder vorhanden sind und die Beträge plausibel zusammenpassen. Die Rechnungsnummer stammt aus dem PDF, nicht aus einer technischen Datei-ID.

Relevante Symbole

5. Duplikate und idempotente Wiederholung behandeln

Vor der Buchung wird geprüft, ob dieselbe Quellrechnung oder derselbe fachliche Rechnungsschlüssel schon bekannt ist. Ein zweiter Lauf mit derselben Rechnung soll nicht zu einem zweiten Lexoffice-Beleg führen. Das nennt man idempotentes Verhalten: Wiederholen ist sicher, weil das Ergebnis nicht doppelt angelegt wird.

Relevante Symbole

6. Lieferantenkontakt in Lexoffice finden oder anlegen

Der Lieferant wird nicht fest im Programm kodiert. Die extrahierten Daten werden verwendet, um in Lexoffice nach einem passenden Kontakt zu suchen. Wird einer gefunden, wird seine ID wiederverwendet. Andernfalls wird ein neuer Kontakt mit Name und Adresssignatur angelegt.

Relevante Symbole

7. Rechnungsbeleg in Lexoffice anlegen

Mit der echten Rechnungsnummer, dem Rechnungsdatum, den extrahierten Beträgen und der Kontakt-ID wird der Lexoffice-Beleg erstellt. Danach wird die geprüfte lokale PDF als Anhang hochgeladen. Der Vorgang gilt erst als erfolgreich, wenn eine gültige Beleg-ID vorliegt und der Datei-Upload erfolgreich bestätigt wurde.

Relevante Symbole

8. Status und Protokoll schreiben

Jeder wichtige Schritt wird protokolliert. Der dauerhafte fachliche Zustand liegt in `rechnungen.json`; die einzelnen Logeinträge helfen bei der zeitlichen Nachvollziehbarkeit. Ein Status wie `POSTED` bedeutet, dass der Beleg erfolgreich verarbeitet wurde. Fehler und Wiederholungsversuche bleiben als Zustand erkennbar.

Relevante Symbole

9. Fehler behandeln und sicher wiederholen

Ein Fehler bei Anmeldung, Entdeckung, Download, PDF-Auslesung, Kontaktabgleich oder Lexoffice-Buchung wird dem jeweiligen Schritt zugeordnet. Der Lauf wird nicht fälschlich als vollständig erfolgreich markiert. Bei einem erneuten Lauf entscheiden Status, Quell-ID, Rechnungsschlüssel und Hash erneut, ob eine Rechnung verarbeitet werden muss.

Relevante Symbole

10. Nachweise des Gesamtergebnisses

Ein erfolgreicher Durchlauf hinterlässt drei zusammengehörige Nachweise:

  1. die geprüfte Original-PDF unter `rechnungen/originale/`,
  2. den lokalen Status in `rechnungen/rechnungen.json`,
  3. den Lexoffice-Kontakt und den Beleg mit PDF-Anhang.

Die fachliche Verarbeitung wird durch Application-Use-Cases gesteuert. Die technischen Details bleiben austauschbar: WEtell kann über Headless-Browser, HTTP oder Fallback angebunden werden; die PDF-Auslesung kann über `pdftotext` oder OCR erfolgen; Lexoffice wird über den API-Adapter angesprochen.

Relevante Symbole