API Connector

Der Connector verbindet Octoserv bidirektional mit beliebigen externen Systemen über REST-APIs. Kontakte und Firmen können sowohl empfangen als auch gesendet werden – vollständig konfigurierbar, ohne Programmierkenntnisse, direkt aus der Octoserv-Oberfläche.

Typische Einsatzszenarien sind die Anbindung eines externen CRM-Systems, die automatische Übernahme von Leads aus einem Drittanbieter oder die laufende Synchronisation von Kundenstammdaten zwischen zwei Plattformen. Der Connector unterstützt dabei eingehende Webhooks (das externe System sendet Daten an Octoserv), Pull-Synchronisation (Octoserv ruft Daten vom externen System ab) und Push-Synchronisation (Octoserv sendet Daten an das externe System).

Die Funktion ist erreichbar über Funktionen > Connector in der Seitennavigation.

Verbindung anlegen

Jede Anbindung an ein externes System wird als eigenständige Verbindung gespeichert. Zu einer Verbindung gehören die Zugangsdaten der externen API sowie alle Konfigurationsdetails für das Feld-Mapping und die Synchronisation.

1. Öffnen Sie Funktionen > Connector.
2. Klicken Sie auf Verbindung anlegen.
3. Vergeben Sie einen Namen (z. B. „Perfex CRM Produktion“).
4. Tragen Sie die API-Basis-URL des externen Systems ein (z. B. https://crm.beispiel.de/api).
5. Wählen Sie die Authentifizierungsart:
   • Ohne – für öffentliche APIs ohne Zugriffsschutz
   • API-Key – Header-Name und Schlüssel eingeben (z. B. X-API-Key)
   • Bearer-Token – Token eingeben, wird als Authorization: Bearer … übertragen
   • Basic Auth – Benutzername und Passwort eingeben
6. Optional: Tragen Sie zusätzliche HTTP-Header ein (ein Header pro Zeile, Format: Headername: Wert).
7. Klicken Sie auf Verbindung testen – bei Erfolg wird der HTTP-Statuscode angezeigt.
8. Klicken Sie auf Speichern.

Feld-Mapping konfigurieren

Das Feld-Mapping steuert, wie Daten zwischen dem externen System und Octoserv übersetzt werden. Es wird pro Verbindung und pro Entitätstyp (Kontakte oder Firmen) separat konfiguriert. Klicken Sie dazu auf der Verbindungskarte auf Mapping.

Kontakte

Im Tab Kontakte werden alle Einstellungen für die Synchronisation von Kontaktdatensätzen vorgenommen.

Endpunkte

Es werden zwei Endpunkte unterschieden:

• Eingehend (GET) – Die URL, unter der das externe System Kontaktdaten bereitstellt. Octoserv ruft diesen Endpunkt beim manuellen Pull-Sync ab. Beispiel: /contacts
• Ausgehend (POST / PUT / PATCH) – Die URL, an die Octoserv Kontaktdaten sendet (Push-Sync). Wählen Sie die passende HTTP-Methode aus dem Dropdown direkt neben dem Endpunktfeld. Beispiel: /contacts/{id}

Schlüsselfeld und Dublettenprüfung

Das Schlüsselfeld bestimmt, anhand welches Feldes Octoserv prüft, ob ein eingehender Datensatz bereits existiert (Standard: email). Die Dublettenprüfung sollte aktiviert bleiben, damit vorhandene Kontakte aktualisiert und keine Duplikate angelegt werden.

Standardwerte

Standardwerte werden gesetzt, wenn das externe System für ein bestimmtes Feld keinen Wert überträgt. Verfügbare Standardwerte:

• Status – Kontaktstatus, der bei neuen Datensätzen eingetragen wird
• Statuslevel – Statuslevel-Wert (wird nur gesetzt, wenn das Statuslevel-Modul aktiv ist)
• Quelle – Herkunftskanal des Kontakts (z. B. „CRM-Import“)
• Zuständig – Octoserv-Benutzer, der als Verantwortlicher eingetragen wird

Hinweis: Standardwerte greifen nur dann, wenn das Feld im eingehenden Datensatz leer ist. Wenn das Wertemapping (siehe Abschnitt unten) für dasselbe Feld eine Übersetzung definiert, hat das Wertemapping Vorrang.

Eingehender Webhook

Octoserv stellt für jede Verbindung automatisch eine Webhook-URL bereit. Das externe System kann diese URL aufrufen, um Daten in Echtzeit zu übertragen – ohne manuellen Sync-Lauf.

• Die URL lautet nach dem Schema: https://ihre-domain.de/octo/webhook/{ID}/{Token}
• Sie können die URL mit dem Kopieren-Button in die Zwischenablage übernehmen
• Der Neu generieren-Button erstellt einen neuen Token und macht die alte URL ungültig
• Dieselbe Webhook-URL gilt für alle Entitätstypen der Verbindung – Octoserv erkennt anhand der Nutzlast automatisch, ob es sich um Kontakt- oder Firmendaten handelt

Feld-Zuordnung

In der Tabelle ordnen Sie die Felder des externen Systems den Feldern in Octoserv zu:

1. Klicken Sie auf Zeile hinzufügen.
2. Wählen Sie links das Octoserv-Feld aus der Dropdown-Liste (Kern- und Zusatzfelder werden automatisch geladen).
3. Tragen Sie rechts den Feldname des externen Systems ein (exakt so, wie er in der API-Antwort erscheint).
4. Wählen Sie die Richtung: Bidirektional, nur eingehend oder nur ausgehend.
5. Wiederholen Sie die Schritte für alle benötigten Felder.
6. Klicken Sie auf Mapping speichern.

Firmen

Der Tab Firmen funktioniert identisch zum Kontakte-Tab. Tragen Sie hier die Endpunkte und die Feldzuordnung für Firmendatensätze ein.

Hinweis zu Firmenkontakten: Kontakte, die in Octoserv einer Firma zugeordnet sind, werden beim Push-Sync automatisch über den korrekten Kontakt-Endpunkt übertragen. Die Firmenzuordnung bleibt dabei im externen System erhalten.

Wertemapping

Das Wertemapping übersetzt numerische IDs oder systemspezifische Schlüssel des externen Systems in lesbare Werte in Octoserv – und umgekehrt. Es löst ein häufiges Problem bei CRM-Anbindungen: Externe Systeme verwenden oft interne Zahlenwerte für Status, Quellen oder Zuständige, die in Octoserv keine direkte Entsprechung haben.

Beispiel: Das externe System sendet staff_id: 1 für einen Mitarbeiter. Das Wertemapping übersetzt diesen Wert automatisch in den zugeordneten Octoserv-Benutzer „Rita Meier“. Beim Push in die umgekehrte Richtung wird Rita Meier wieder zu staff_id: 1 übersetzt.

Das Wertemapping gilt für beide Sync-Richtungen (eingehend und ausgehend) und hat Vorrang gegenüber den Standardwerten.

Wertemapping einrichten

1. Klicken Sie im Mapping-Dialog auf den Tab Wertemapping.
2. Klicken Sie auf Zeile hinzufügen im gewünschten Abschnitt (z. B. „Ansprechpartner“, „Status“ oder „Quelle“).
3. Tragen Sie im linken Feld den externen Wert ein (z. B. 1 für eine Mitarbeiter-ID).
4. Tragen Sie im rechten Feld den entsprechenden Octoserv-Wert ein (z. B. den internen Bezeichner des Benutzers oder Status-Schlüssel).
5. Klicken Sie abschließend auf Wertemapping speichern.

Typische Einsatzfälle:

Synchronisation starten

Klicken Sie auf der Verbindungskarte auf Sync, um eine manuelle Synchronisation zu starten.

1. Wählen Sie den Datenbereich: Kontakte oder Firmen.
2. Wählen Sie die Richtung:
   • Eingehend (Pull) – Octoserv ruft Daten vom externen System ab und importiert sie
   • Ausgehend (Push) – Octoserv sendet Daten an das externe System
3. Klicken Sie auf Sync starten.

Die Verarbeitung erfolgt in Batches. Der Fortschrittsbalken zeigt den aktuellen Stand. Nach Abschluss wird eine Übersicht mit Erstellt / Aktualisiert / Übersprungen / Fehler angezeigt.

Alle Sync-Läufe werden im Protokoll gespeichert und können über den Logs-Button auf der Verbindungskarte eingesehen werden.

Häufige Fragen