Externe REST-Integration (API-Schluessel)
Eine externe REST-Integration ist eine kontrollierte „Tuer", durch die ein anderes System (ERP, Website-Backend, 1C oder eine Integrationsschicht, eine eigene Anwendung) ueber eine standardisierte API mit Zugriffsschluessel Aufgaben und Deals in LadVen OS anlegen und aktualisieren kann. Dabei uebergibt niemand Login und Passwort und arbeitet niemand unter dem Administrator.
Jeder Aufruf wird von einem eigenen Servicekonto (Bot) mit minimal noetigen Berechtigungen ausgefuehrt: nur die Aktionen, die Sie erlaubt haben, und nur in den Abteilungen, Projekten, Pipelines und Stufen, die Sie festgelegt haben. Alle Anfragen durchlaufen die ueblichen Portalregeln – Zugriff, Pruefungen, Automatisierung, Benachrichtigungen – und werden in einem Protokoll erfasst, das sich je Integration einsehen laesst.
Eine Verbindung wird einmalig im Integrations-Hub hinzugefuegt (Bereich CRM → Integrationen, Route /crm/integrations).
Wann zu verwenden
Eine REST-Integration ist noetig, wenn „in einem anderen System etwas passiert – und in LadVen OS automatisch eine Aufgabe oder ein Deal entstehen soll". Typische Szenarien:
- ein ERP oder eine Website legt eine Aufgabe oder Anfrage an, wenn eine Bestellung, ein Antrag oder ein Ticket eingeht;
- eine eigene Anwendung haelt Aufgaben und Deals mit einer externen Datenbank synchron;
- ein externes System haengt Dateien an, hinterlaesst Kommentare, erfasst Zeit oder verschiebt einen Deal ueber die Stufen, waehrend die Arbeit auf der anderen Seite voranschreitet.
Worin sich das von Formularen und Webhooks unterscheidet: ein Website-Formular und ein Webhook sind eine einseitige Anfrageaufnahme ins CRM. Eine REST-Integration ist eine programmatische beidseitige Verbindung: das externe System liest (es erhaelt Aufgaben, Deals, Historie) und schreibt (es legt an und aktualisiert). Das Portal selbst versendet ueber diese Verbindung keine ausgehenden Webhooks – die externe Seite wendet sich selbst an das Portal.
So richten Sie es ein
Eine Verbindung wird ueber einen schrittweisen Assistenten erstellt (CRM → Integrationen → „Externe REST-Integration" hinzufuegen). Schritt fuer Schritt, in praktischen Begriffen:
- Name und Aktivitaet. Geben Sie der Integration einen verstaendlichen Namen und entscheiden Sie, ob Sie sie sofort aktivieren. Sie koennen direkt eine Verbindungspruefung starten.
- Servicekonto. Waehlen Sie einen vorhandenen Bot oder erstellen Sie direkt im Assistenten einen neuen (Name und Login). Das ist weder ein Mitarbeiter noch ein Administrator: Die Integration arbeitet in seinem Namen. Waehlen Sie ein Konto mit Administratorrechten, warnt der Assistent – das ist gewollt, denn Integrationen erhalten ein Minimum an Rechten.
- Szenario und Berechtigungsstufe. Waehlen Sie einen Satz an Operationen passend zur Aufgabe: „Aufgaben und CRM", „Nur Aufgaben" oder „Nur CRM". Dann die Berechtigungsstufe: nur Lesen, Anlegen und Bearbeiten oder Verwalten. Die Berechtigungen werden vor der Ausstellung des Schluessels auf das Servicekonto angewendet.
- Erlaubte Aktionen. Markieren Sie die konkreten Operationen, die die Integration ausfuehren darf. Das Prinzip lautet: das noetige Minimum – aktivieren Sie nur, was wirklich gebraucht wird. Alles, was nicht markiert ist, wird vor der Ausfuehrung abgelehnt.
- Geltungsbereich. Begrenzen Sie die Integration auf die noetigen Abteilungen, Projekte, Pipelines und Stufen. Das ist ein Rahmen ueber den Kontoberechtigungen: Selbst eine erlaubte Aktion greift nur innerhalb des festgelegten Geltungsbereichs.
- Felder und Limits. Legen Sie fest, welche Felder von Aufgaben und Deals die Integration aendern darf, das Anfragelimit pro Minute und den zulaessigen Spitzenwert sowie eine Positivliste (Whitelist) der IP-Adressen, von denen Aufrufe erlaubt sind.
- Schlusselerstellung und Pruefung. Speichern Sie – das Portal zeigt den Zugriffsschluessel einmalig auf dem Ergebnisbildschirm mit einer Kopierschaltflaeche an. Hier laesst sich auch eine Verbindungspruefung starten.
Nach der Erstellung verfuegt die Verbindung ueber ein Anfrageprotokoll: welche Operationen aufgerufen wurden, mit welchem Ergebnis und mit Details zu jedem Aufruf (sensible Daten sind in den Eintraegen verborgen).
Sicherheit und Zugriffsschluessel
Die REST-Integration beruht auf dem Prinzip der geringsten Rechte – das ist fuer den Unternehmensinhaber wichtig:
- Der Schluessel wird einmal angezeigt. Kopieren Sie ihn und speichern Sie ihn sofort in einem Geheimnis-Manager. Das Portal zeigt diesen Schluessel nicht erneut an und speichert ihn nicht im Klartext. Muss der Schluessel gewechselt werden, stellen Sie ihn neu aus, indem Sie den Assistenten fuer diese Verbindung erneut durchlaufen.
- Eigenes Servicekonto. Die Integration arbeitet nicht unter einer Person oder einem Administrator; sie hat ihren eigenen Verantwortungsbereich und ihre eigenen Berechtigungen.
- Zugriffsrahmen. Die erlaubten Aktionen, der Geltungsbereich (Abteilungen, Projekte, Pipelines, Stufen), die Positivliste der Felder, das Anfragelimit und die IP-Positivliste begrenzen, was und von wo aus die Integration tun kann.
- Protokoll. Jeder Aufruf wird erfasst – so laesst sich nachvollziehen, wer was ueber die Integration geaendert hat.
Zeigen Sie niemals auf Screenshots und veroeffentlichen Sie niemals einen echten Schluessel, den Autorisierungs-Header, IP-Adressen aus der Positivliste oder das Login des Servicekontos. Verwenden Sie fuer Illustrationen offensichtlich unechte Werte.
Haeufige Fehler
- Der Integration ein Administratorkonto statt eines Service-Bots geben.
- Mehr Aktionen aktivieren als noetig, statt des minimal noetigen Satzes.
- Den einmaligen Schluessel bei der Erstellung nicht kopieren.
- Keine IP-Positivliste und kein Anfragelimit festlegen.
- Einen zu weiten Geltungsbereich festlegen – das ganze Portal statt der einen benoetigten Pipeline.
- Erwarten, dass das Portal von selbst ausgehende Webhooks versendet: Die Integration arbeitet ueber eingehende Aufrufe, das externe System wendet sich an das Portal.
So pruefen Sie, dass es funktioniert
- Starten Sie am Ende des Assistenten die Verbindungspruefung (oder aktivieren Sie den sofortigen Start der Pruefung).
- Stellen Sie sicher, dass die Verbindungskarte einen aktiven und einwandfreien Zustand anzeigt.
- Sehen Sie sich das Anfrageprotokoll an – dort sollten erfolgreiche Aufrufe stehen.
- Pruefen Sie, dass eine Testaufgabe oder ein Test-Deal mit dem richtigen Verantwortlichen, der richtigen Pipeline und Stufe erschienen ist und dass Automatisierung und Benachrichtigungen wie gewohnt funktioniert haben.