Grundkonzepte des Ventoo Pingen Connectors

Dieser Artikel erklärt die wichtigsten Konzepte, die Sie für die effektive Arbeit mit dem Ventoo Pingen Connector verstehen sollten.

Belegversand-Profil als Steuerungsmerkmal

Der Ventoo Pingen Connector nutzt das in Business Central vorhandene Belegversand-Profil als einziges Selektionsmerkmal: Nur Debitoren, deren Profil dem in der Einrichtung hinterlegten Code entspricht (z.B. POST), werden in den automatischen Versand aufgenommen.

Damit bleibt die Logik zentral steuerbar:

Ein Debitor wechselt von E-Mail- auf Postversand → einfach das Profil auf der Debitorenkarte anpassen. Ab der nächsten gebuchten Rechnung gilt der neue Status.
Ein Mandant deaktiviert den Postversand vorübergehend → den Profil-Code in der Einrichtung leeren.

Wichtig — Profil zum Buchungszeitpunkt: Die App "friert" das Belegversand-Profil beim Buchen jeder Rechnung in einem internen Markierungs-Flag (Pingen Auto-Send) ein. Spätere Profil-Änderungen auf der Debitorenkarte wirken nicht rückwirkend auf bereits gebuchte Belege. Das verhindert, dass ältere Rechnungen plötzlich versendet werden, nur weil ein Kunde später auf das POST-Profil umgestellt wird.

Hinweis: Ohne hinterlegtes Belegversand-Profil im Setup führt die Auftragswarteschlange keine Aktion aus.

Karenzzeit (Tage bis zum Versand)

Damit nicht jede gebuchte Rechnung sofort die Post verlässt, kann eine Karenzzeit definiert werden. Eine Rechnung wird erst versandt, wenn das Buchungsdatum mindestens N Tage zurückliegt:

Versanddatum >= Buchungsdatum + Tage bis zum Versand

So bleibt Zeit für Korrekturen, manuelles Sperren oder Stornierungen, bevor der Brief tatsächlich gedruckt wird.

Karenzzeit	Verhalten
`0`	Versand sofort beim nächsten Lauf der Auftragswarteschlange.
`4` (Standard)	Versand frühestens 4 Tage nach dem Buchungsdatum.
`14`	Versand frühestens 14 Tage nach dem Buchungsdatum (z.B. nach Zahlungsfrist Stufe 1).

Verarbeitungsstatus pro Beleg

Jeder unterstützte Beleg trägt zwei zusätzliche Felder, die seinen Pingen-Status abbilden:

Feld	Bedeutung
Verarbeitet	Wahr, sobald der Beleg an Pingen übergeben oder manuell für den Versand gesperrt wurde. Belege mit diesem Flag werden von der Auftragswarteschlange ignoriert.
Versandt via Pingen am	Zeitstempel des erfolgreichen Versands. Schreibgeschützt.

Hinweis: Über die Aktionen Pingen-Versand deaktivieren und Pingen-Versand aktivieren auf dem Beleg lässt sich das Flag manuell setzen oder zurücknehmen.

PDF-Generierung über Berichts-IDs

Für jede Belegart wird in der Einrichtung eine Berichts-ID hinterlegt, mit der das PDF erzeugt wird. Standardmässig sind die Microsoft-Standardberichte konfiguriert:

Belegart	Standard-Bericht
Verkaufsangebot	1304 (Standard Sales – Quote)
Verkaufsauftrag	1305 (Standard Sales – Order)
Gebuchte Verkaufsrechnung	1306 (Standard Sales – Invoice)
Gebuchte Verkaufsgutschrift	1307 (Standard Sales – Credit Memo)

Wer ein eigenes Layout (z.B. eine Custom Report Extension) verwendet, trägt einfach die ID des eigenen Berichts ein. Die App ruft den Bericht über Report.SaveAs mit dem aktuellen Datensatz als Filter auf und übergibt das resultierende PDF an Pingen.

Übertragungsablauf an Pingen

Der Versand eines Briefes erfolgt in vier Schritten gegen die Pingen-API:

Authentifizierung – Die App fordert mit Client-ID und Client Secret ein OAuth Access Token bei identity.pingen.com an.
Upload-URL anfordern – Über den Endpunkt /file-upload wird eine pre-signed S3-URL bezogen.
PDF hochladen – Das generierte PDF wird per PUT direkt an die S3-URL übertragen.
Brief erstellen – Über /organisations/{id}/letters wird der Brief mit Metadaten (Adressposition, Versandprodukt, Druckmodus, Farbmodus) bei Pingen angelegt.

Hinweis: Tritt in einem dieser Schritte ein Fehler auf, wird der Beleg nicht als verarbeitet markiert. Beim nächsten Lauf der Auftragswarteschlange wird ein erneuter Versuch unternommen.

Fehlerdetails: Bei einem fehlgeschlagenen API-Aufruf enthält die Fehlermeldung den HTTP-Statuscode und den Response-Body von Pingen — z.B. Pingen: Letter creation failed (HTTP 422). Response: .... Dadurch lässt sich am Job-Queue-Logeintrag direkt unterscheiden, ob es sich um ein Auth- (401), Validierungs- (422) oder Netzwerkproblem handelt.

Robustheit der Auftragswarteschlange: Schlägt der Versand für eine einzelne Rechnung fehl (z.B. unvollständige Adresse), bricht der Auftragswarteschlangen-Lauf nicht ab. Die App protokolliert den Fehler, übergeht den betroffenen Beleg und fährt mit der nächsten Rechnung fort. Bereits erfolgreich versandte Rechnungen aus dem laufenden Durchlauf bleiben erhalten.

Speicherung von Zugangsdaten

Das Pingen Client Secret wird nicht in einer Datenbank-Tabelle gespeichert, sondern verschlüsselt im Business Central Isolated Storage (Modul-Scope) abgelegt. Es ist damit weder über Tabellen anzeigen noch über Datenbank-Backups im Klartext einsehbar. Auf der Einrichtungsseite zeigt das Feld Client Secret Punkte an, sobald ein Wert hinterlegt ist; um das Secret zu wechseln, einfach die Punkte überschreiben.