So funktioniert die Integration mit Microsoft Dynamics 365 Business Central

Die Integration mit Microsoft Dynamics 365 Business Central hält Ihre Pabau-Kunden mit den Kundendatensätzen in Business Central synchron. Wenn Sie einen Kunden in Pabau erstellen oder bearbeiten, wird die Änderung automatisch an Business Central übertragen — als Kundenerstellung oder -aktualisierung — nahezu in Echtzeit, sodass Ihr Finanzteam stets dieselben Kundendaten sieht wie Sie.

Dies ist ein Connector innerhalb des Data Sync-Tools von Pabau. Wenn Sie neu bei Data Sync sind, lesen Sie zunächst Wie Data Sync in Pabau funktioniert für die allgemeinen Konzepte (Trigger, Zuordnung, das Übermittlungsprotokoll und Wiederholungsversuche). Diese Anleitung behandelt alles Spezifische zu Business Central.

Hinweis: Der Connector synchronisiert das Objekt Kunde. Er sendet Pabau-Kunden an Business Central; er synchronisiert keine Rechnungen, Termine, Produkte oder Finanztransaktionen. Sie benötigen Administratorzugriff in Pabau, um ihn einzurichten.

Was der Connector macht

Erstellt einen Kunden in Business Central, wenn ein Kunde in Pabau erstellt wird.
Aktualisiert den entsprechenden Kunden, wenn ein Kunde in Pabau bearbeitet wird.
Kann optional den Kunden in Business Central sperren, wenn ein Kunde in Pabau gelöscht wird (Sperren wird gegenüber Löschen empfohlen und ist standardmäßig deaktiviert).
Kann optional neue Pabau-Kunden aus Business-Central-Kunden erstellen (standardmäßig deaktiviert — bei großen Kundenbeständen sollte dies deaktiviert bleiben).

Bevor Sie beginnen — was Sie von Ihrem IT-Team benötigen

Business Central authentifiziert Pabau über eine Microsoft-Entra-ID-App-Registrierung (eine „Service-to-Service"- bzw. S2S-Verbindung). Ihr Business-Central-Administrator muss Folgendes bereitstellen:

Verzeichnis-(Tenant-)ID — das Entra-ID-Verzeichnis Ihres Business-Central-Tenants.
Anwendungs-(Client-)ID — die Entra-ID-App-Registrierung, der Business-Central-API-Zugriff gewährt wurde.
Client-Geheimnis — das Geheimnis für diese App-Registrierung.
Unternehmens-ID — die Business-Central-Unternehmens-GUID (vom Companies-Endpunkt).
Der Name der Umgebung (zum Beispiel Produktion oder der Name einer Sandbox).

Ihr IT-Team muss der App-Registrierung außerdem die Berechtigung erteilen, Kunden über die Business-Central-API zu lesen und zu schreiben, und dafür in Entra ID die Admin-Zustimmung erteilen. Wenn Ihr Tenant statt der Standard-API einen eigenen benutzerdefinierten Kunden-Webdienst (benutzerdefinierte OData-Seiten) veröffentlicht, benötigen Sie zusätzlich den Unternehmensnamen und den Namen der Kundenseite, die für diesen Dienst verwendet werden.

Tipp: Fragen Sie Ihren Business-Central-Anbieter nach dem „Integrations-Onboarding-Paket". Es enthält genau die oben genannten Werte. Bewahren Sie das Client-Geheimnis sicher auf — Sie fügen es nur einmal in Pabau ein, und es wird verschlüsselt gespeichert.

Schritt 1: Verbindungseinstellungen

Wählen Sie unter Data Hub > Data Sync die Option Connector hinzufügen, wählen Sie Microsoft Dynamics 365 Business Central und dann Einrichten. Füllen Sie auf der Registerkarte Einstellungen die von Ihrem IT-Team bereitgestellten Felder aus.

The Business Central connection settings tab with its fields

Die Einstellungen, die Sie sehen werden:

Umgebung — der Name der Business-Central-Umgebung, üblicherweise production oder ein Sandbox-Name.
Unternehmens-ID — die Business-Central-Unternehmens-GUID.
API-Typ — Standard API v2.0 für die meisten Tenants oder Benutzerdefinierte OData-Seiten für Tenants, die einen eigenen Kunden-Webdienst veröffentlichen.
Unternehmensname (OData) und Name der Kundenseite (OData) — nur erforderlich für benutzerdefinierte OData-Seiten, z. B. Company('IBSSI') und CustomerAPI.
Kundennummer — Automatisch lässt Business Central die Kundennummer vergeben; Aus Pabau-ID generieren erstellt die Nummer anhand der Pabau-Kunden-ID (erforderlich bei Tenants, deren Integrationsbenutzer die Nummernserie nicht ausführen kann).
Präfix der Kundennummer — das Präfix für generierte Nummern (bis zu 10 Zeichen), z. B. ZPAB.
Beim Löschen eines Kunden — Kunden sperren (empfohlen) oder Datensatz löschen (nur wenn Ihre Business-Central-Berechtigungen das Löschen zulassen).
Beim ersten Update erstellen — wenn aktiviert, wird beim Bearbeiten eines Kunden, der noch nie synchronisiert wurde, der Kunde in Business Central erstellt, anstatt übersprungen zu werden.
Neue Kunden aus Business-Central-Kunden erstellen — wenn aktiviert, werden Business-Central-Kunden, die keinem bestehenden Kunden entsprechen, als neue Pabau-Kunden erstellt (maximal 25 pro Abfrage). Bei großen Kundenbeständen deaktiviert lassen.
API-Basis-URL — eine optionale Überschreibung für souveräne Clouds oder Proxys; andernfalls leer lassen.

Geben Sie die drei Anmeldedaten (Tenant-ID, Client-ID, Client-Geheimnis) im Abschnitt Anmeldedaten ein und wählen Sie dann Verbindung testen. Pabau speichert die Anmeldedaten verschlüsselt und bestätigt, dass sie gespeichert wurden.

Schritt 2: Trigger

Wählen Sie auf der Registerkarte Trigger, welche Pabau-Ereignisse an Business Central übertragen werden. Bei diesem Connector werden die Kundenereignisse wie folgt zugeordnet:

client.create → Kunden erstellen oder aktualisieren
client.update → Kunden erstellen oder aktualisieren
client.delete → Kunden beim Löschen sperren

The Triggers tab for the Business Central connector

Hinweis: client.delete ist standardmäßig deaktiviert. Aktivieren Sie ihn nur, wenn ein gelöschter Pabau-Kunde den entsprechenden Business-Central-Kunden sperren soll, und nur, wenn Ihre Business-Central-Berechtigungen die Sperr-Operation zulassen.

Schritt 3: Feldzuordnung

Erweitern Sie auf der Registerkarte Zuordnung den Bereich Kunden, um zu sehen, wie Pabau-Kundenfelder auf Business-Central-Kundenfelder abgebildet werden. Feldnamen sind standardmäßig auf die Standard-API ausgerichtet — wenn Ihr Tenant benutzerdefinierte OData-Seiten verwendet, richten Sie jedes Zielfeld über die Dropdown-Menüs auf den Feldnamen Ihrer benutzerdefinierten Seite aus.

The Business Central customer field mapping table

Die Standardzuordnung lautet:

Vollständiger Name (Vor- + Nachname) → Name (erforderlich)
Kunden-ID → Kundennummer (wird verwendet, wenn „Aus Pabau-ID generieren" eingestellt ist)
Mobiltelefon → Telefonnummer
Postanschrift Straße → Adresse
Postanschrift Stadt → Stadt
Postanschrift Bezirk → Bezirk
Postanschrift Postleitzahl → Postleitzahl
E-Mail → E-Mail (optional — siehe Hinweis unten)

Wichtig: Deaktivieren Sie ein Feld, wenn Ihr Business-Central-Tenant Schreibvorgänge dafür ablehnt. Business Central verarbeitet eine Aktualisierung als eine einzige Anfrage; wird also ein zugeordnetes Feld abgelehnt, schlägt die gesamte Aktualisierung fehl — einschließlich der Felder, die in Ordnung gewesen wären. Wenn ein bestimmtes Feld (zum Beispiel E-Mail) durch die Validierung Ihres Tenants konsequent abgelehnt wird, deaktivieren Sie es in der Zuordnung, bis Ihr IT-Team das Problem auf Business-Central-Seite gelöst hat.

Schritt 4: Bestehende Datensätze verknüpfen (vor dem Go-Live empfohlen)

Wenn Sie bereits Kunden in Business Central und Kunden in Pabau für dieselben Personen haben, führen Sie Bestehende Datensätze verknüpfen aus, bevor Sie sich auf die Synchronisierung verlassen. Dabei werden bereits auf beiden Seiten existierende Datensätze abgeglichen und verknüpft, sodass zukünftige Bearbeitungen den richtigen Datensatz aktualisieren, anstatt Duplikate zu erstellen. Es werden nur Verknüpfungen geschrieben — es werden niemals Datensätze auf beiden Seiten erstellt oder geändert —, und es wird immer zunächst als Testlauf ausgeführt, sodass Sie einen vollständigen Bericht prüfen können, bevor etwas verknüpft wird.

The Link existing records wizard showing a completed run

Sie legen fest, wie Datensätze abgeglichen werden — anhand einer gespeicherten Referenz (z. B. der benutzerdefinierten ID des Kunden oder des Kundenreferenzfelds) und optional zusätzlich anhand einer eindeutigen E-Mail-Adresse als Rückfalloption. Der Testlauf erzeugt einen herunterladbaren CSV-Bericht, der zeigt, wie viele Datensätze übereinstimmten, wie viele mehrdeutig waren (absichtlich nicht verknüpft) und wie viele nicht zugeordnet werden konnten. Wenn alles passt, bestätigen Sie den Lauf, um die Verknüpfungen zu schreiben.

Wichtig: Wenn Beim ersten Update erstellen aktiviert ist, während Ihre Datenbestände noch nicht verknüpft sind, erstellt das Bearbeiten eines nicht verknüpften Kunden einen doppelten Kunden in Business Central. Erwägen Sie, diese Option in den Einstellungen zu deaktivieren, bis der Verknüpfungslauf abgeschlossen ist, und aktivieren Sie sie danach wieder.

Schritt 5: Ende-zu-Ende testen

Wählen Sie auf der Registerkarte Zuordnung Testereignis senden, wählen Sie client.create oder client.update und wählen Sie Test senden. Pabau wählt einen echten Kunden aus, überträgt ihn durch die Live-Pipeline und protokolliert das Ergebnis im Protokoll, als Test gekennzeichnet. Öffnen Sie die Protokolle, um zu bestätigen, dass es erfolgreich war, und prüfen Sie dann, ob der Kunde in Business Central erscheint (oder aktualisiert wurde).

Fehlerbehebung: Fehler im Übermittlungsprotokoll lesen

Öffnen Sie Protokolle für den Connector, um jede Übermittlung zu sehen. Wählen Sie eine fehlgeschlagene Zeile aus, um die genaue von Pabau gesendete Anfrage, die von Business Central zurückgegebene Antwort und die Korrelations-ID zu sehen.

A failed Business Central delivery showing the request, response and error message

Die häufigsten Ergebnisse und ihre Bedeutung:

Abgelehnt (HTTP 400)

Business Central hat die Daten abgelehnt. Die Antwortmeldung teilt Ihnen genau mit, warum — zum Beispiel „The email address … is not valid." Dies ist ein dauerhafter Fehler (Pabau wiederholt ihn nicht), da eine erneute Übermittlung derselben Daten erneut fehlschlagen würde. Korrigieren Sie die Daten in Pabau, oder bitten Sie Ihr IT-Team, die Validierung in Business Central zu lockern, und senden Sie sie dann mit Neueste Daten synchronisieren erneut. Wenn ein ganzes Feld immer abgelehnt wird, deaktivieren Sie es in der Zuordnung (siehe Hinweis zur Zuordnung oben).

Authentifizierung fehlgeschlagen (HTTP 401 / 403)

Business Central hat die Anmeldedaten von Pabau nicht akzeptiert, oder der App-Registrierung ist es nicht gestattet, Kunden zu lesen/schreiben. Bitten Sie Ihr IT-Team zu bestätigen, dass die App-Registrierung Zugriff auf die Business-Central-API hat, dass die Admin-Zustimmung in Entra ID erteilt wurde und dass die Berechtigungssätze die Kunden-API-Seiten nicht ausschließen. Geben Sie die Anmeldedaten auf der Registerkarte Einstellungen erneut ein, falls sie geändert wurden.

Ratenbegrenzung (HTTP 429)

Business Central hat Pabau gebeten, langsamer zu senden. Dies ist vorübergehend — Pabau reduziert die Rate automatisch und wiederholt den Versuch. Keine Maßnahme erforderlich, es sei denn, das Problem besteht weiterhin.

Serverfehler (HTTP 5xx)

Ein Problem auf Seiten von Business Central. Vorübergehend — Pabau wiederholt den Versuch automatisch nach einem sich verlängernden Zeitplan, bis zu 8 Versuche lang.

Netzwerkfehler

Pabau konnte Business Central überhaupt nicht erreichen (ein Timeout- oder Verbindungsproblem). Vorübergehend — Pabau wiederholt den Versuch automatisch.

Nicht implementiert

Ein seltener, vorübergehender Zustand, der nur kurz während eines Pabau-Plattform-Updates auftritt, wenn die Laufzeitumgebung des Connectors noch nicht vollständig ausgerollt wurde. Er behebt sich beim nächsten Versuch oder beim nächsten automatischen Durchlauf von selbst; wenn er weiterhin auftritt, senden Sie die Übermittlung mit Neueste Daten synchronisieren erneut oder wenden Sie sich an den Support.

Hinweis: Nachdem Pabau einen vorübergehenden Fehler 8-mal ohne Erfolg versucht hat, wird der Vorgang gestoppt und die Übermittlung als fehlgeschlagen markiert. Sie können sie jederzeit manuell aus den Übermittlungsdetails erneut senden, sobald das zugrunde liegende Problem behoben ist.

Eine fehlgeschlagene Übermittlung erneut senden

Wählen Sie im Detailbereich einer fehlgeschlagenen Übermittlung eine der folgenden Optionen:

Ursprüngliche Nutzdaten wiedergeben — sendet genau das erneut, was zuvor gesendet wurde. Verwenden Sie dies, wenn die Daten in Ordnung waren und das Problem auf Seiten von Business Central lag (zum Beispiel eine Berechtigung, die inzwischen erteilt wurde).
Neueste Daten synchronisieren — erstellt die Anfrage anhand der aktuellen Werte des Kunden neu und sendet diese. Verwenden Sie dies, wenn Sie die Daten des Kunden in Pabau seit dem Fehlschlag korrigiert haben.

Tipp: Wenn Sie ein Support-Ticket zu einer Business-Central-Synchronisierung erstellen, geben Sie die Korrelations-ID aus den Übermittlungsdetails an. Business Central gibt ebenfalls eine eigene Korrelations-ID innerhalb der Fehlermeldung zurück — durch die Angabe beider können Ihr IT-Team und Pabau dieselbe Anfrage von beiden Seiten nachverfolgen.