Module LetterXpress (DE)
Modul LetterXpress
| Modulname | LetterXpress |
|---|---|
| Herausgeber | Goeger-IT |
| Status | Stabil |
| Version | 1.0.0 |
| Modul-ID | 194020 |
| Kompatibilität | Dolibarr 18 bis 24 (geprüft auf 18.0.9, 20.0.4 und 24.0.0) |
| Lizenz | GNU GPL v3 oder später |
| Sprachen | Deutsch und Englisch |
Überblick
LetterXpress versendet Dolibarr-Belege als Papierbrief über LetterXpress, einen Briefdienst der A&O Fischer GmbH & Co. KG. Das PDF, das Dolibarr ohnehin erzeugt, wird an den Dienst übergeben, dort gedruckt, gefalzt, frankiert und eingeworfen.
Versendet werden können Rechnungen, Angebote, Aufträge, Lieferscheine und Verträge. Ein Knopf auf der Belegmaske öffnet einen dreistufigen Assistenten: Versandoptionen wählen, Adresse prüfen, bestätigen.
Das Modul verändert keine Dateien der Dolibarr-Distribution. Es legt eine eigene Tabelle an und bindet sich über Hooks ein.
Woher die Empfängeranschrift kommt
Dieser Abschnitt ist wichtiger als die Funktionsliste, und zwar bei jedem Briefdienst.
Die LetterXpress-API kennt kein Adressfeld. LetterXpress liest die Empfängeranschrift aus dem PDF selbst, aus dem DIN-5008-Anschriftenfeld. Das ist bei Briefdiensten üblich — und genau dort geht es still schief: Eine Vorlage, die den Adressblock ein paar Millimeter versetzt platziert, erzeugt einen Brief, der gedruckt, frankiert und nie zugestellt wird. Man erfährt es Wochen später oder gar nicht.
Damit das sichtbar wird, bevor Geld ausgegeben ist, reicht das Modul den Brief zuerst im Testmodus ein. Dort landet der Auftrag in der LetterXpress-Postbox statt im Druck, kostet nichts und liefert zurück, was der Dienst tatsächlich gelesen hat. Der Assistent zeigt anschließend nebeneinander:
- die Anschrift, die LetterXpress aus dem PDF gelesen hat,
- die Anschrift, die Dolibarr zu diesem Kunden führt,
- Seitenzahl, Preis, Umsatzsteuer und das aktuelle Guthaben.
Erst danach wird der Brief verbindlich beauftragt.
Der Vergleich arbeitet wortweise. „Meier" gilt deshalb nicht als Treffer für „Meiersberg GmbH", und Hausnummer 1 nicht für Hausnummer 12. Felder in einer Schrift, die der Vergleich nicht lesen kann — kyrillisch, griechisch, türkisch —, werden als nicht prüfbar gemeldet statt als Treffer. Ein ausländischer Empfänger erzeugt so nie eine falsche Entwarnung.
Funktionen
- Versand von Rechnungen, Angeboten, Aufträgen, Lieferscheinen und Verträgen
- Adressprüfung über den LetterXpress-Testmodus, bevor Kosten entstehen
- Farbe oder Schwarzweiß, einseitig oder beidseitig, national, international oder automatisch
- Einschreiben (Einwurf und Standard), Wunsch-Versanddatum, C4-Umschlag für dickere Briefe
- Anzeige des Guthabens vor der Bestätigung, mit Warnung, wenn es nicht reicht
- Versandprotokoll je Beleg und systemweit, mit Zustellstatus und Sendungsnummer
- Statusabgleich über die geplanten Aufgaben von Dolibarr
- Schutz gegen doppelten Versand nach einem Verbindungsabbruch
- Testmodus für den gesamten Ablauf
- Einstellbare Aufbewahrung: gespeicherte Vergleichsadressen werden bei abgeschlossenen Aufträgen nach einer wählbaren Zahl von Tagen geleert, Auftragsnummern und Kosten bleiben für die Buchhaltung erhalten
- Verschlüsselte Ablage der Zugangsdaten, getrennt je Mandant
Installation
Das Modularchiv im DoliStore herunterladen.
- Start → Einstellungen → Module/Anwendungen → Externes Modul bereitstellen öffnen.
- Das Archiv hochladen.
- Den Reiter Interfaces mit externen Systemen öffnen und LetterXpress aktivieren.
Alternativ das Verzeichnis letterxpress nach htdocs/custom/ kopieren. Dazu muss custom in der conf.php als $dolibarr_main_document_root_alt freigeschaltet sein.
Einrichtung
Zugangsdaten
- Die Einstellungsseite des Moduls öffnen (Zahnradsymbol neben dem Modul).
- LetterXpress-Benutzernamen und API-Schlüssel eintragen; zu finden im LetterXpress-Kundenbereich unter Mein Konto → Zugangsdaten → LXP API.
- Den Betriebsmodus zunächst auf Testmodus belassen.
- Verbindung testen — es muss das Guthaben erscheinen.
- Berechtigungen unter Start → Benutzer und Gruppen → Berechtigungen vergeben.
PDF-Layout
Vier Dolibarr-Einstellungen entscheiden darüber, ob die Empfängeranschrift im DIN-5008-Fenster landet. Die Standardvorlage sponge trifft es korrekt, sobald sie gesetzt sind. Die Werte wurden gegen die echte LetterXpress-API gemessen, nicht geschätzt.
| Einstellung | Wert | Wirkung |
|---|---|---|
MAIN_PDF_FORMAT |
EUA4 |
LetterXpress nimmt ausschließlich A4 an |
MAIN_INVERT_SENDER_RECIPIENT |
1 |
Empfänger nach links, dorthin schaut das Fenster |
MAIN_PDF_USE_ISO_LOCATION |
1 |
vertikale Position nach ISO/DIN |
MAIN_PDF_MARGIN_LEFT |
17 |
Adressblock beginnt 20 mm vom Blattrand |
Ohne den letzten Wert beginnt der Block bei 13 mm. Die fehlenden sieben Millimeter schneiden pro Zeile zwei bis drei Zeichen ab: LetterXpress liest dann P Rechnungskontakt, stweg 5 statt LXP Rechnungskontakt, Testweg 5 — der Brief käme nicht an.
Die Einstellungsseite des Moduls prüft alle vier Werte und benennt die fehlenden.
Vorhandene PDF behalten ihr altes Layout — die betroffenen Belege nach der Umstellung neu erzeugen und anschließend mit einer Adressprüfung an einem Testbeleg kontrollieren, was LetterXpress tatsächlich liest.
Geplante Aufgabe
Zustellstatus, Sendungsnummern und das Aufräumen liegengebliebener Adressprüfungen laufen ausschließlich über die geplanten Aufgaben von Dolibarr. Das Modul führt dazwischen keine eigene Hintergrundprüfung aus.
Dafür muss auf dem Server ein Cron-Eintrag bestehen, der php scripts/cron/cron_run_jobs.php aufruft — oder, ohne Shell-Zugang, die HTTP-Variante public/cron/cron_run_jobs_by_url.php. Fehlt er, bleiben alle Aufträge dauerhaft auf dem Status stehen, den sie beim Absenden hatten.
Unter Start → Werkzeuge → Geplante Aufgaben prüfen, ob der LetterXpress-Eintrag vorhanden ist und wann er zuletzt lief.
Voraussetzungen
- Dolibarr 18.0 oder neuer
- PHP 7.4 oder neuer mit der curl-Erweiterung
- Ein LetterXpress-Konto mit API-Zugangsdaten
- Funktionierende geplante Aufgaben in Dolibarr für den automatischen Statusabgleich
Datenschutz
Beim Versand — auch bei der Adressprüfung im Testmodus — werden das vollständige Beleg-PDF und die darin enthaltene Empfängeranschrift an die A&O Fischer GmbH & Co. KG übertragen.
Datenschutzrechtlich ist der Betreiber der Dolibarr-Installation Verantwortlicher, LetterXpress ist Auftragsverarbeiter. Für den produktiven Einsatz ist ein Vertrag zur Auftragsverarbeitung nach Art. 28 DSGVO zwischen diesen beiden Parteien erforderlich. Das Modul läuft vollständig auf dem Server des Betreibers und spricht ausschließlich mit LetterXpress; es enthält keine Telemetrie und sendet nichts an den Modulanbieter. Ein Vertrag mit dem Modulanbieter ist für den Einsatz daher nicht nötig.
Bekannte Einschränkungen
- In Version 1.0.0 sind die Bezeichnungen der Berechtigungen nur auf Englisch hinterlegt und erscheinen auch in der deutschen Oberfläche unübersetzt.
- Dolibarrs eigene Wiederherstellung für hart abgebrochene geplante Aufgaben kann selbst scheitern (
mysqli object is already closed); die Aufgabe bleibt dann dauerhaft als laufend markiert. Das ist ein Verhalten des Kerns, nicht des Moduls — der Status lässt sich unter Start → Werkzeuge → Geplante Aufgaben zurücksetzen. Das Modul begrenzt seinen Stapel auf 30 Aufträge je Lauf, damit ein Lauf gar nicht erst in PHPs Zeitlimit gerät.