PPWR-Erklärungen automatisch aus Rechnungen

Business Central legt die Rechnungs-PDFs entweder direkt in einen Ordner (Berichtsausgabe) oder sie landen über eine Outlook-Regel dort, die Anhänge aus dem Rechnungsversand speichert. Das Skript verarbeitet, was neu ist.

:: Aufgabe anlegen: täglich, alle 15 Minuten wiederholen
schtasks /create /tn "PPWR-Erklaerungen" /sc minute /mo 15 ^
  /tr "C:\ppwr-generator\.venv\Scripts\python.exe -m ppwr --log C:\ppwr-generator\ppwr.log erzeugen C:\ppwr-generator\eingang --archiv C:\ppwr-generator\Archiv --weiter-bei-fehler" ^
  /ru "%USERNAME%"

Alternativ dauerhaft mitlaufen lassen: python -m ppwr ueberwachen eingang --erledigt erledigt. Vorteil dieser Stufe: kein Eingriff in Business Central, keine Freigabe durch die IT nötig. Nachteil: hängt am Rechnungslayout — ändert sich das Layout, müssen die Suchmuster nachgezogen werden (die Testsuite meldet das sofort).

Der saubere Endzustand: kein PDF-Parsing, kein Layout-Risiko. Zusätzlicher Gewinn — die Regel „keine Erklärung für Fracht und Rabatte“ ergibt sich aus dem Zeilentyp (lineType = "Item") statt aus Textmustern.

Einmalige Einrichtung

1. In Entra ID (früher Azure AD) eine App-Registrierung anlegen, Client-Secret erzeugen.
2. API-Berechtigung Dynamics 365 Business Central → Application permissions → API.ReadWrite.All hinzufügen und Administrator-Zustimmung erteilen.
3. In Business Central die Seite Microsoft Entra-Anwendungen öffnen, die Client-ID eintragen, Status auf Aktiviert setzen und den Berechtigungssatz D365 BASIC (lesend genügt) zuweisen.
4. Zugangsdaten in die Datei .env eintragen — sie gehört nicht ins Repository.

# Token holen (Client Credentials)
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
grant_type=client_credentials&scope=https://api.businesscentral.dynamics.com/.default

# Rechnungen eines Zeitraums
GET .../v2.0/{environment}/api/v2.0/companies({id})/salesInvoices
    ?$filter=invoiceDate ge 2026-07-01 and status eq 'Open'

# Positionen dazu
GET .../salesInvoices({invoiceId})/salesInvoiceLines

:: Aufruf im Projekt — dieselbe Ausgabe, dieselben Regeln wie beim PDF-Weg
python -m ppwr bc --top 20 --archiv Archiv
python -m ppwr bc --filter "number eq '103046'" --trocken

Das Modul ppwr/extract/bc_api_source.py ist fertig; die Feldzuordnung steht als Dictionary am Anfang der Klasse. Weicht euer Setup ab — etwa Rechnungsanschrift über billTo… statt sellTo… — ändert sich nur diese Zuordnung, kein Ablauf.

Statt eine zweite E-Mail zu verschicken, wandert die erzeugte Erklärung als Anhang an die gebuchte Rechnung. Damit ist sie im ERP auffindbar, geht auf demselben Weg wie die Rechnung nach draußen und die Aufbewahrung liegt dort, wo der Beleg ohnehin liegt.

# Anhang anlegen und Inhalt hochladen
POST .../companies({id})/salesInvoices({invoiceId})/attachments
     { "fileName": "PPWR_103046_Pos2.pdf", "parentId": "{invoiceId}" }
PATCH .../attachments({attachmentId})/attachmentContent  # Rohdaten des PDF

Für gebuchte Belege heißt die Route salesInvoices im API-v2.0-Endpunkt bzw. documentAttachments in der Standard-Web-Service-Variante — welche zur Verfügung steht, hängt an eurer BC-Version; das prüft die IT einmalig mit einem Testaufruf.

Business Central kann Änderungen an salesInvoices aktiv melden, statt abgefragt zu werden. Die Erklärung entsteht dann Sekunden nach dem Buchen. Nötig ist ein von außen erreichbarer HTTPS-Endpunkt, der die Registrierung beantwortet; Abonnements laufen nach drei Tagen ab und müssen automatisch erneuert werden.

Lohnt sich, wenn ohnehin ein Server vorhanden ist und die Erklärung zeitgleich mit der Rechnung rausgehen soll. Für den Anfang bringt die 15-Minuten-Abfrage aus Stufe 2 dasselbe Ergebnis bei deutlich weniger Technik.

Ein BC-Partner baut die Erklärung als Word-Layout-Bericht in BC nach und hängt einen Subscriber an das Buchen der Verkaufsrechnung. Je Artikelzeile wird der Bericht ausgeführt, als Beleganhang gespeichert und über die Berichtsauswahl mit der Rechnung versendet.

• Dafür: kein zweites System, kein PC der laufen muss, funktioniert für jeden Mandanten und aus der Cloud heraus.
• Dagegen: Entwicklungsaufwand beim Partner, jede Textänderung an der Erklärung läuft künftig über einen Entwicklungsvorgang statt über Word.
• Empfehlung: nur angehen, wenn ohnehin Partner-Budget eingeplant ist — der Nutzen gegenüber Stufe 2 + 3 ist überschaubar.