Web Services - EXFID
Einleitung
ExFlow kann Dokumente aus mehreren Quellen importieren, z. B. Lokales Dateisystem, Azure Storage oder Web Services.
Diese Seite beschreibt den ExFlow-Webdienst EXFID: was er leistet, wie er eingerichtet wird und welche Methoden er bietet. EXFID ist ein SOAP-Webdienst, daher kann die Integration in jeder Sprache geschrieben werden, die SOAP-Anfragen senden kann, z. B. C# oder VB.NET.
Mit EXFID können Drittanbieter-Integratoren oder Business Central-Partner elektronische Rechnungen über ein standardisiertes Protokoll an ExFlow senden.
Allgemeines
Eine in ExFlow importierte Rechnung besteht normalerweise aus zwei Dateien:
- Einer XML-Datei mit der Rechnung in einer bekannten Struktur.
- Einer PDF-Datei mit einer Darstellung der Rechnung.
In einigen Fällen ist nur eine der beiden Dateien erforderlich:
- Nur XML: Wenn die Datenaustauschdefinition ein Stylesheet (XSL) enthält, generiert ExFlow die PDF-Datei aus der XML-Datei.
- Nur PDF: Wenn die PDF-Datei eine PDF/A-3-Datei mit eingebetteter XML-Datei ist, z. B. ZUGFeRD oder Factur-X, extrahiert ExFlow die XML-Datei und alle eingebetteten Anlagen aus der PDF-Datei.
Der Import über EXFID wird vom externen System gestartet, nicht von ExFlow oder einem Aufgabenwarteschlangeneintrag. Das externe System ruft EXFID in Business Central auf, und jeder Aufruf erstellt ein eingehendes Dokument mit den Dateien als eingehende Dokumentanlagen. Die Dokumente werden anschließend verarbeitet, wenn der Import im ExFlow-Importjournal ausgeführt wird.
Business Central / ExFlow
Installieren Sie ExFlow und führen Sie den Assistenten aus, um eine Einrichtung zu erhalten.
Importieren Sie eine passende Datenaustauschdefinition (DED), entweder eine von ExFlow oder eine bestehende DED in Business Central.
Webdienst EXFID
Gehen Sie zu: ExFlow-Einrichtung --> Standard-Webdienste erstellen/aktualisieren
Stellen Sie sicher, dass die Webdienste EXFID und EXFWEB unter Webdienste in Business Central vorhanden sind. Wenn sie fehlen, führen Sie Standard-Webdienste erstellen/aktualisieren in der ExFlow-Einrichtung aus.
Die SOAP-Adresse von EXFID wird unter Webdienste in Business Central angezeigt. Für Business Central online hat sie folgendes Format:
https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<environment>/WS/<company name>/Codeunit/EXFID
ExFlow-Einrichtung
Gehen Sie zu: ExFlow-Einrichtung --> OCR-Import
| Feld | Beschreibung |
|---|---|
| Web Def. Datenaustauschtyp | Wählen Sie den Datenaustauschtyp aus, der für über EXFID importierte Dokumente verwendet wird. Wenn die Liste leer ist, führen Sie Datenaustausch-Definitionen importieren in der ExFlow-Einrichtung aus und importieren Sie eine oder mehrere Datenaustauschdefinitionen. |
| Web Optional Doc. XPath | Optional. Der XPath in der Rechnungs-XML, der auf optionale Anlagen verweist. Weitere Informationen finden Sie unten unter Optionale Anlagen. |
Importjournal
Gehen Sie zu: ExFlow-Importjournale
Erstellen oder konfigurieren Sie ein ExFlow-Importjournal, um über EXFID importierte Dokumente zu verarbeiten.
Um ein neues ExFlow-Importjournal zu erstellen, bearbeiten Sie die Liste und legen Sie einen Namen und eine Beschreibung für das neue Journal fest. Setzen Sie dann Quelltyp auf Webdienst.
Verarbeiten Sie die importierten Dokumente, indem Sie Dokumente importieren im Importjournal oder Batch-Dokumente importieren ausführen.
Methoden
Alle Dateien werden als Base64-kodierter Text gesendet. Der Inhalt kann vor der Base64-Kodierung zusätzlich mit gzip komprimiert werden. ExFlow erkennt dies und dekomprimiert den Inhalt automatisch.
| Methode | Beschreibung |
|---|---|
| AddDocument | Sendet ein Dokument. Parameter: XML-Dateiname, XML-Datei, PDF-Dateiname, PDF-Datei. |
| AddDocumentByDocumentId | Wie AddDocument, jedoch mit einer Document Id. Wird verwendet, um Anlagen zu verknüpfen, die zuvor mit AddAttachment gesendet wurden. |
| AddAttachment | Sendet eine optionale Anlage vor dem Dokument. Gibt eine Document Id zurück, die anschließend in AddDocumentByDocumentId verwendet wird. |
| AddAttachmentChunk | Wie AddAttachment, jedoch für große Dateien, die in mehreren Teilen gesendet werden. |
| AddDocumentChunk | Sendet ein großes Dokument in mehreren Teilen. |
| CreateDocumentFromChunks | Erstellt das Dokument aus allen mit AddDocumentChunk gesendeten Teilen. |
Große Dokumente – Chunks
Große Dateien können in mehrere Teile (Chunks) aufgeteilt und einzeln gesendet werden.
- Rufen Sie AddDocumentChunk mit Chunk Id 1 und einer leeren Document Id auf. ExFlow gibt eine Document Id zurück.
- Rufen Sie AddDocumentChunk für die nächsten Teile mit derselben Document Id und Chunk Id 2, 3 usw. auf. Die Dateinamen (XML und PDF) werden nur mit dem letzten Teil gesendet.
- Rufen Sie CreateDocumentFromChunks mit der Document Id auf. ExFlow fügt die Teile in der Reihenfolge der Chunk Id zusammen und erstellt das Dokument.
Der Base64-Text wird in Teile aufgeteilt, und die Teile werden in derselben Reihenfolge wieder zusammengefügt. Teile, die innerhalb einer Stunde nicht verwendet wurden, werden gelöscht.
Optionale Anlagen
Optionale Anlagen können hinzugefügt werden, um mehr Dokumente als die XML- und PDF-Datei einzuschließen. Dafür gibt es zwei Möglichkeiten:
Eingebettete Anlagen
Einige XML-Formate, wie Peppol und OIOUBL, enthalten Anlagen in der XML-Datei als Base64-kodierte Daten, optional mit gzip komprimiert. Um zu sehen, wie dies eingerichtet ist, importieren Sie die Peppol- oder OIOUBL-Datenaustauschdefinition. Dieselbe Einrichtung kann für jedes XML-Format verwendet werden.
Vorab gesendete Anlagen
Wenn das XML-Format keine eingebetteten Anlagen unterstützt oder das Einbetten technisch schwierig ist, können die Anlagen vor dem Dokument gesendet werden:
- Rufen Sie für jede Anlage AddAttachment (oder AddAttachmentChunk für große Dateien) auf. Der erste Aufruf gibt eine Document Id zurück. Verwenden Sie dieselbe Document Id für die nächsten Anlagen.
- Rufen Sie AddDocumentByDocumentId mit derselben Document Id auf, um die XML- und PDF-Datei zu senden.
Alle mit dieser Document Id gesendeten Anlagen werden dem eingehenden Dokument hinzugefügt. Wenn Web Optional Doc. XPath in der ExFlow-Einrichtung festgelegt ist, werden nur die Anlagen hinzugefügt, deren Dateiname unter diesem XPath in der Rechnungs-XML gefunden wird. Wenn der Wert unter dem XPath eine URL ist, lädt ExFlow die Datei stattdessen von dieser URL herunter.
Anlagen, die innerhalb einer Stunde nicht verwendet wurden, werden gelöscht.
Authentifizierung
OAuth
Seit ExFlow 19.2 unterstützt EXFID die Authentifizierung über OAuth (Service-to-Service). Dies ist für Business Central online erforderlich.
1. Eine Anwendung in Azure registrieren
Gehen Sie zu: Azure Portal --> Microsoft Entra ID --> App-Registrierungen
- Registrieren Sie eine neue Anwendung, geben Sie ihr einen Namen und wählen Sie den relevanten Kontotyp aus.
- Kopieren Sie die Anwendungs-ID (Client-ID). Sie wird in Business Central und in der Integration benötigt.
- Erstellen Sie einen geheimen Clientschlüssel (oder ein Zertifikat) für die Integration.
- Fügen Sie unter API-Berechtigungen Dynamics 365 Business Central --> Anwendungsberechtigungen --> API.ReadWrite.All hinzu.
- Klicken Sie auf Administratorzustimmung erteilen. Dies erfordert einen globalen Administrator oder einen Benutzer mit der Berechtigung, die Administratorzustimmung zu erteilen.
2. Die Microsoft Entra-Anwendung in Business Central erstellen
Gehen Sie zu: Microsoft Entra-Anwendungen
- Erstellen Sie eine neue Karte und geben Sie die Client-ID aus der App-Registrierung ein.
- Fügen Sie eine relevante Beschreibung hinzu und setzen Sie Status auf Aktiviert.
- Fügen Sie unter Benutzerberechtigungssätze den Berechtigungssatz EX WEB SERVICE hinzu. Lassen Sie das Feld Unternehmen leer, damit er für alle Unternehmen gilt.
- Klicken Sie auf Zustimmung erteilen.
Die Integration kann nun ein Zugriffstoken von Microsoft Entra ID abrufen (Client-Credentials-Flow, Bereich https://api.businesscentral.dynamics.com/.default) und EXFID damit aufrufen.
Webdienstzugangsschlüssel
Ein Webdienstzugangsschlüssel kann nur mit Business Central On-Premises oder einem lokalen Container verwendet werden. Business Central online unterstützt keine Webdienstzugangsschlüssel.
Öffnen Sie die Benutzerkarte in Business Central und erstellen Sie einen Webdienstzugangsschlüssel. Verwenden Sie den Benutzernamen und den Schlüssel als Anmeldeinformationen in der Integration.
