Dieser Artikel erklärt die wichtigsten Konzepte, die Sie für die effektive Arbeit mit dem Ventoo Document Reader verstehen sollten.
Baustein-Prinzip: keine eigene Erfassungsmaske
Der Ventoo Document Reader ist bewusst als Baustein für andere Erweiterungen konzipiert, nicht als eigenständige Endbenutzer-Funktion. Es gibt keine Liste, keine Karte und keinen Button, über den Sie als Benutzer manuell eine QR-Rechnung auslesen. Stattdessen stellt die App eine öffentliche Codeunit-Prozedur (TryExtractFromAttachment) bereit, die von einer abhängigen Erweiterung aufgerufen wird, sobald diese einen PDF-Anhang verarbeitet.
Hinweis: Wenn Sie den Ventoo Document Reader ohne eine solche abhängige Erweiterung installieren, sehen Sie nach der Einrichtung ausser der Setup-Seite keine weiteren sichtbaren Funktionen. Das ist normal – die eigentliche Wirkung entfaltet sich erst über die aufrufende Erweiterung.
Datenfluss: von PDF zu strukturierten Zahlungsdaten
Ein Aufruf durchläuft immer denselben Ablauf:
-
Eingabe – Eine abhängige Erweiterung übergibt einen Business Central Document Attachment-Datensatz (ein PDF) an
TryExtractFromAttachment. -
Verarbeitung – Der Ventoo Document Reader übergibt das PDF sicher an die von Ventoo betriebene Azure Function, die nach einem eingebetteten Swiss-QR-Code sucht und dessen Inhalt gemäss dem Swiss-Payments-Code-Standard dekodiert.
-
Rückgabe – Das Ergebnis wird auf Business-Central-Seite in einen temporären Datensatz vom Typ QR-Bill Data übersetzt (Referenz, Kreditor, Debitor, Betrag, Mitteilungen).
Wichtig: Der temporäre Datensatz wird von der aufrufenden Erweiterung selbst deklariert und als Parameter übergeben (Record "QR Bill Data VTO" temporary). Der Ventoo Document Reader speichert selbst nichts dauerhaft ausser der Einrichtung.
Zweistufige Referenzprüfung
Die erkannte Zahlungsreferenz wird zweifach geprüft, bevor sie als gültig gilt:
|
Stufe |
Wo |
Was wird geprüft |
|---|---|---|
|
1 |
Azure Function |
Mod10r-Prüfziffer der Referenz (Standard-Prüfverfahren für Schweizer QR-Referenzen). |
|
2 |
Business Central |
Strukturelle Prüfung: Die Referenz muss exakt 27 numerische Ziffern umfassen. |
Nur wenn beide Stufen erfolgreich sind, gilt der Aufruf als vollständiger Treffer.
Wichtig – nur QRR-Referenzen gelten aktuell als Treffer: Die 27-stellige Prüfung in Stufe 2 ist spezifisch für den Referenztyp QRR. Referenzen vom Typ SCOR (alphanumerisch, ISO 11649) und Belege ohne Referenz (NON) bestehen diese Prüfung grundsätzlich nicht – auch wenn Kreditor-, Debitor- und Betragsdaten von der Azure Function korrekt dekodiert wurden. In diesen Fällen liefert TryExtractFromAttachment aktuell false zurück, obwohl technisch ein QR-Code erkannt wurde. Weitere Details dazu finden Sie unter https://ventoo.atlassian.net/wiki/x/XwCFGQE.
"Kein Treffer" ist kein Fehler
Ein PDF ohne Schweizer QR-Rechnung ist der erwartete Normalfall, kein Ausnahmezustand. TryExtractFromAttachment liefert in folgenden Fällen einfach false zurück, ohne einen Fehler auszulösen:
-
Der Ventoo Document Reader ist nicht aktiviert.
-
Function URL oder Function Key sind nicht hinterlegt.
-
Der PDF-Anhang enthält keinen erkennbaren QR-Code.
-
Die Azure Function meldet
"found": false. -
Die erkannte Referenz besteht die 27-stellige Prüfung nicht (siehe oben).
Nur eine tatsächliche Transport- oder HTTP-Störung (nicht erreichbare Function, Zeitüberschreitung, Statuscode ausserhalb 2xx) löst einen echten Fehler aus.
Sichere Ablage des Function Key
Der Function Key wird verschlüsselt gespeichert und nie im Klartext angezeigt, exportiert oder in einem Backup gesichert. Auf der Einrichtungsseite zeigt das Feld Function Key Punkte an, sobald ein Wert hinterlegt ist; um den Schlüssel zu wechseln, einfach überschreiben.
Zeitüberschreitung und Netzwerkfehler
Antwortet die Azure Function nicht innerhalb der eingestellten Timeout (ms)-Zeit, oder ist sie nicht erreichbar, bricht der Aufruf mit einer Fehlermeldung ab, die von der aufrufenden Erweiterung abgefangen werden kann. Es findet kein automatischer Wiederholungsversuch statt – dieser liegt in der Verantwortung der aufrufenden Erweiterung.