Rechnungs-Download und Buchhaltung

Worum geht es?

Der Prozess holt eine Rechnung automatisch aus dem WEtell-Kundenkonto und übergibt sie an Lexoffice. WEtell ist dabei die Quelle der Rechnung, Lexoffice das Ziel für Kontakt und Buchungsbeleg. Die Original-PDF bleibt zusätzlich lokal als nachvollziehbarer Beleg erhalten.

Der Ablauf ist so gebaut, dass ein erneuter Start keine Rechnung doppelt verarbeitet. Dazu werden sowohl die tatsächliche Rechnungsnummer als auch ein SHA-256-Hash verwendet. Ein Hash ist ein eindeutiger digitaler Fingerabdruck einer Datei.

1. Prozess starten

`run.sh` startet die beiden technischen Teilprozesse in der richtigen Reihenfolge:

1. Node.js mit Playwright lädt die Rechnung von WEtell herunter.
2. PHP verarbeitet die heruntergeladene PDF und übergibt sie an Lexoffice.

Playwright ist ein Browsersteuerungswerkzeug. Es verwendet hier die bereits vorhandene Playwright-Instanz und nicht einen separat gestarteten Chromium-Prozess.

2. Bei WEtell anmelden

Der Browser öffnet das WEtell-Kundenkonto und meldet sich mit den hinterlegten Zugangsdaten an. Nach der Anmeldung wird geprüft, ob die erwartete Rechnungsübersicht erreichbar ist. Schlägt die Anmeldung fehl, wird keine Buchung gestartet.

Zugangsdaten werden nicht in der Dokumentation oder im Rechnungsdatensatz gespeichert. Sie bleiben in der lokalen Credential-Konfiguration.

3. Rechnung finden und herunterladen

Aus der WEtell-Rechnungsübersicht wird die relevante Rechnung ausgewählt. Die PDF wird zunächst in einem Arbeitsbereich heruntergeladen. Entscheidend ist nicht nur die Rechnungs-URL, sondern die tatsächlich gespeicherte Datei.

Die Datei wird anschließend unter dem kanonischen lokalen Pfad abgelegt:

`/var/www/demo.karlkratz.com/rechnungen/originale/wetell/`

So ist klar, welche Datei als Originalbeleg gilt und wo sie später wiedergefunden werden kann.

4. PDF faktisch prüfen

Vor jeder weiteren Verarbeitung wird die Datei geprüft:

• Die Datei existiert und ist nicht leer.
• Die Datei beginnt tatsächlich mit dem PDF-Dateikopf.
• Der Inhalt kann als PDF gelesen und extrahiert werden.
• Die heruntergeladene Datei entspricht dem erwarteten Rechnungsinhalt.

Eine URL allein gilt nicht als Beleg. Erst die lokal gespeicherte und lesbare PDF wird verarbeitet.

5. Duplikate erkennen

Vor der Buchung werden zwei unabhängige Prüfungen durchgeführt:

• Die Rechnungsnummer wird mit bereits verarbeiteten Rechnungen verglichen.
• Der SHA-256-Hash der PDF wird mit gespeicherten Dateifingerabdrücken verglichen.

Findet eine Prüfung eine Übereinstimmung, endet der Prozess kontrolliert mit `SCHON_VORHANDEN`. Die Rechnung wird nicht noch einmal in Lexoffice angelegt.

6. Rechnungsdaten aus dem PDF lesen

Der Lieferant wird nicht fest im Programm eingetragen. Stattdessen werden die Daten aus der PDF extrahiert. Dazu gehören insbesondere:

• Lieferantenname und Anschrift
• tatsächliche Rechnungsnummer
• Rechnungsdatum
• die für den Buchungsbeleg benötigten Rechnungsdaten

Die Rechnungsnummer stammt aus dem PDF und nicht aus einem Dateinamen. Dadurch wird beispielsweise `RF183233049809` verwendet, auch wenn die heruntergeladene Datei eine technische WEtell-ID im Namen trägt.

7. Lieferantenkontakt in Lexoffice abgleichen

Lexoffice wird nach einem bestehenden Kontakt mit den extrahierten Lieferantendaten durchsucht.

• Wird ein passender Kontakt gefunden, wird seine Lexoffice-ID wiederverwendet.
• Gibt es keinen passenden Kontakt, wird ein neuer Kontakt mit den extrahierten Daten angelegt.
• Die verwendete Kontakt-ID wird für die weitere Buchung gespeichert.

Dieser Abgleich verhindert, dass bei jedem Lauf ein neuer Lieferantenkontakt entsteht.

8. Rechnungsbeleg in Lexoffice anlegen

Mit den extrahierten Rechnungsdaten und der Kontakt-ID wird der Beleg in Lexoffice erstellt. Dabei wird die echte Rechnungsnummer verwendet. Nach erfolgreicher Anlage wird die PDF als Belegdatei an den Lexoffice-Beleg angehängt.

Die einzelnen Schritte werden nur als erfolgreich betrachtet, wenn Lexoffice eine erfolgreiche HTTP-Antwort und eine gültige Beleg-ID liefert.

9. Lokalen Verarbeitungsstatus schreiben

Nach erfolgreicher Lexoffice-Verarbeitung wird `rechnungen.json` aktualisiert. Der Datensatz enthält unter anderem:

• Quelle und lokale Originaldatei
• SHA-256-Hash der PDF
• Rechnungsnummer und Rechnungsdatum
• Lieferantenname
• Kontakt-ID
• Lexoffice-Beleg-ID
• Verarbeitungsstatus `POSTED`
• Ergebnisse der Duplikatprüfungen

Damit kann ein späterer Lauf nachvollziehen, was passiert ist, ohne die Rechnung erneut buchen zu müssen.

10. Fehler- und Wiederholungsverhalten

Der Prozess arbeitet schrittweise. Ein Fehler beim Login, Download, PDF-Lesen, Kontaktabgleich, Beleganlegen oder Datei-Anhängen beendet den Lauf mit einem Fehlerstatus. Ein unvollständiger Vorgang wird nicht als erfolgreich verbucht.

Ein erneuter Lauf prüft den lokalen Status und die Identifikatoren erneut. Bereits vollständig gebuchte Rechnungen werden als `BEREITS GEBUCHT` erkannt und ohne Doppelbuchung beendet.

Ergebnis

Bei Erfolg existieren drei zusammengehörige Nachweise:

1. die geprüfte Original-PDF unter `rechnungen/originale/wetell/`,
2. der lokale Statusdatensatz in `rechnungen.json`,
3. der Kontakt und der Beleg mit PDF-Anhang in Lexoffice.

Damit ist der Weg von der Online-Rechnung bis zum prüfbaren Buchhaltungsbeleg nachvollziehbar.