Integrationen
Überblick
Integrationen sind die Anbindungen an fremde Systeme — die Stelle, an der die Zugangsdaten für externe Dienste liegen.
Sie unterscheiden sich von den API-Token in der Richtung: Ein Token lässt ein fremdes System zu uns herein, eine Integration lässt uns nach draußen. Beide Richtungen werden getrennt verwaltet, weil sie getrennt widerrufen werden müssen.
Kernaufgaben
Integration anlegen. Neue Integration verlangt einen Namen, einen Anbieter und die Konfiguration als Schlüssel/Wert-Paare.
Anbieter-Vorlage nutzen. Für bekannte Dienste — LinkedIn, Meta (Facebook/Instagram) und X — füllt eine Vorlage den Anbieter und die erwarteten Konfigurationsschlüssel vor. Das erspart das Nachschlagen, wie ein Schlüssel genau heißen muss. Der freie Weg ohne Vorlage bleibt für alles andere nutzbar.
Zugangsdaten hinterlegen. Token-Schlüssel wie access_token oder page_access_token werden verschlüsselt und nur schreibend gespeichert: Beim erneuten Laden erscheinen sie maskiert als ********. Sie können sie überschreiben, aber nicht auslesen — auch nicht als Administrator.
Aktiv schalten. Der Aktiv-Zustand entscheidet, ob die Anbindung verwendet wird. Die Liste zeigt Name, Anbieter, Status und Änderungsdatum.
Verbindung im Blick behalten. Die Spalte Verbindung zeigt je Integration das Ergebnis der jüngsten Prüfung: Verbunden, Fehler oder Nie geprüft — dazu, wann geprüft wurde, und bei einem Fehler die Meldung der Gegenstelle. Geheimnisse stehen darin nie; ein Anbieter, der den Schlüssel in seiner Fehlermeldung zitiert, erscheint geschwärzt. Jede aktive Integration wird stündlich geprüft; Verbindung jetzt prüfen (Herz-Symbol) prüft sofort. Deaktivierte Integrationen werden nicht geprüft — sie benutzt niemand, ihr letzter Stand bleibt stehen.
Wie tief die Prüfung geht. Für jede Anbindung mit eigenem Plugin ruft die Prüfung die Gegenstelle — mit dem billigsten Aufruf, der die Zugangsdaten beweist: Token erneuern, Profil, Konto oder Modell-Liste abfragen. Das gilt für Google, Microsoft, die KI-Anbieter, lexoffice, Slack, die Social-Netzwerke (LinkedIn, Meta, X, TikTok, YouTube), HubSpot, awork, alle Versanddienstleister, die Verkaufskanäle, Stripe, PayPal, finAPI, Twilio, Zoom, Calendly, Postmark, Google Workspace, den Geokodierer (geocoder, Suche nach einem festen Ort) und den Lizenzserver (license_server, erste Seite der Aktivierungen). Angelegt, gesendet oder gebucht wird dabei nichts. Versanddienstleister ohne „Wer bin ich"-Abfrage fragen eine bewusst unbekannte Sendungsnummer ab: nur eine Ablehnung der Anmeldung zählt als Fehler. Ein Verkaufskanal-Zugang wird über den Kanal geprüft, der ihn benutzt — ohne Kanal fehlt die Shop-Adresse (Zugangsdatum fehlt: salesChannel). Für die übrigen Zugänge (CalDAV-Kalender, ICS-Abos, Shopware-Konto) prüft sie die Zugangsdaten: lesbar (nicht durch einen Schlüsselwechsel verloren), nicht abgelaufen, überhaupt hinterlegt. Unter dem Status steht, welche der beiden Prüfungen gilt.
Sync-Log lesen. Das Listen-Symbol öffnet das Sync-Log der Integration: die jüngsten Läufe mit Zeitpunkt, Art (Verbindungs-Prüfung, Kontakt-, Kalender- und Kanal-Abgleich, Postfach- und Umsatz-Abruf, HubSpot- und awork-Übernahme, lexoffice-Übergabe und -Zahlungsabgleich, Abgleich mit dem Lizenzserver …), Ergebnis, Anzahl übertragener Datensätze, Dauer und Meldung. Je Integration und Art bleiben die jüngsten 50 Läufe stehen — eine stündliche Prüfung verdrängt keinen Abgleich.
Twilio für WhatsApp und SMS. Die Integration mit Anbieter twilio trägt account_sid, die eigenen Nummern sms_from/whatsapp_from und als Zugangsdatum das auth_token. Eingehende Nachrichten kommen über den Messages-Webhook https://<ihre-domain>/api/v1/sms/public/twilio-inbound (optional inbound_webhook_url, wenn die signierte Adresse abweicht) und werden Tickets. Bilder und Dateien einer Nachricht (MMS, WhatsApp-Medien) legt das System als Anlage am Ticket ab — auch eine Nachricht nur mit Foto wird ein Ticket. Abgerufen werden Medien ausschließlich von Twilio-Adressen. Alternativ lässt sich die Conversations-API anbinden: conversations_service_sid (der Conversations-Dienst, IS…), als Post-Event- Webhook onMessageAdded dieselbe Adresse wie oben, https://<ihre-domain>/api/v1/sms/public/twilio-inbound (optional conversations_webhook_url) und als Absendername der Antworten conversations_author (Vorgabe support). Jedes Gespräch wird ein Ticket, weitere Nachrichten hängen daran, und Antworten aus dem Ticket gehen in dasselbe Gespräch. Zustell-Rückmeldung: Beim Versand einer SMS oder WhatsApp-Nachricht bestellt das System bei Twilio den Statusrückruf an dieselbe Adresse wie oben, https://<ihre-domain>/api/v1/sms/public/twilio-inbound (aus inbound_webhook_url, sonst die App-Adresse) — einzurichten ist dafür nichts. Danach steht am Verlaufseintrag Zugestellt oder Unzustellbar samt Twilio-Code. Ohne öffentliche Adresse (etwa auf einem Testsystem unter localhost) bleibt es bei Gesendet.
Slack-Support-Channels. In der Slack-Integration nennt support_channels die Channel-Ids, aus denen Tickets entstehen (kommagetrennt) — mehr unter Slack verbinden.
Eingehenden Webhook einrichten. Neben den ausgehenden Webhooks (wir melden etwas nach draußen) gibt es die Gegenrichtung: ein Fremdsystem meldet etwas an uns. Der Webhook bekommt dafür die Richtung eingehend und ein Geheimnis; die Adresse lautet https://<ihre-domain>/api/v1/platform/public/webhooks/<kennung>. Der Absender unterschreibt den Rumpf damit (HMAC-SHA256, Kopfzeile X-Octibiz-Signature) — ohne gültige Unterschrift wird abgewiesen. Die Strecke ist anmeldefrei und deshalb dreifach abgesichert: Anfragegrenze je Absender-Adresse, Größendeckel für den Rumpf, Unterschrift. Ein angenommener Aufruf antwortet sofort mit angenommen und löst danach den Automations-Auslöser Webhook empfangen aus — der Absender wartet nie auf unsere Verarbeitung. Wird derselbe Aufruf zweimal geschickt, meldet die Antwort Doppelt, und es passiert nichts ein zweites Mal. Das Geheimnis lässt sich jederzeit neu ausstellen; danach muss der Absender es übernehmen.
Hinweise der Anbindungen beachten. Über der Liste melden sich Anbindungen, deren Einrichtung nicht mehr trägt — etwa Sendcloud, solange als Versandart noch eine Nummer der alten Schnittstelle eingetragen ist: damit entstehen keine Etiketten mehr. Der Hinweis nennt die Nummer und was stattdessen einzutragen ist; derselbe Hinweis steht nach einem System-Update im Protokoll. Genauso gemeldet werden Versandkosten-Regeln, die eine solche Nummer als Versandart vorschreiben (mit Kennung, Zone und Dienstleister — nachbessern unter Einstellungen → Versand, Feld Versandart), und Sendungen ohne Etikett mit einer solchen Nummer: deren Etikett-Nachkauf scheitert, sie sind zu stornieren und mit dem Code der Versandoption neu anzulegen. Ebenso OctiConnect-Abläufe, deren Versand-Baustein eine solche Nummer gespeichert hat — der Hinweis nennt den Ablauf und springt hinein.
Felder im Detail
| Feld | Pflicht | Werte / Format | Was es bewirkt |
|---|---|---|---|
Anbieter provider | ja | verfügbarer Anbieter, max. 100 Zeichen | Womit verbunden wird. Der Anbieter bestimmt, welche Einstellungen darunter erscheinen und welche Anmeldung nötig ist. |
Name name | ja | Text, max. 255 Zeichen | Wie die Verbindung heißt. Bei mehreren Konten desselben Anbieters die einzige Unterscheidung — „Google Workspace Buchhaltung" statt „Google". |
Einstellungen config | nein | je nach Anbieter | Zugangsdaten, Schlüssel, Ziele. Geheimnisse werden verschlüsselt abgelegt und nie wieder angezeigt; erneutes Eintragen ersetzt sie. |
Marke brandId | nein | eine Ihrer Marken | Für welche Marke die Verbindung gilt. Je Marke ein eigenes Konto ist möglich und oft nötig. |
Aktiv active | nein | Ja/Nein | Ob die Verbindung genutzt wird. Aus hält sie an, ohne die Einrichtung zu verlieren — der erste Griff, wenn ein Anbieter Ärger macht. |
Läuft eine Anmeldung ab, ruht die Verbindung sichtbar und meldet sich, statt still nichts mehr zu tun. Das ist der Unterschied zwischen „seit drei Wochen kommt nichts an" und einer Meldung am ersten Tag.
Einstellungen & Rechte
- Kein eigenes Routen-Recht. Die Seite ist erreichbar; das Anlegen und Ändern prüft der Server.
- Zugangsdaten sind nicht wieder lesbar. Wer den Wert braucht, holt ihn beim Anbieter, nicht
hier.
- KI-Anbieter gehören nicht hierher. Deren Zugänge liegen unter
- Ein Anbieter kann mehrfach vorkommen — etwa je Marke oder je Konto.
FAQ & Fehlerbilder
Die Anbindung schlägt fehl, obwohl der Schlüssel stimmt. Prüfen Sie die Schlüsselnamen in der Konfiguration. Eine Anbieter-Vorlage benennt sie richtig; von Hand eingetragen schleichen sich hier Tippfehler ein, die nach außen wie ein falsches Passwort aussehen.
Ein Token ist abgelaufen. Erneuern Sie ihn beim Anbieter und tragen Sie den neuen Wert ein. Der alte lässt sich nicht einsehen — ein Vergleich ist also nicht möglich.
Ich sehe den hinterlegten Wert nicht mehr. So gewollt. Zugangsdaten werden verschlüsselt und maskiert dargestellt.
Die Verbindung steht auf „Fehler", obwohl gestern alles lief. Öffnen Sie das Sync-Log: die Meldung nennt den Grund — abgelaufener Zugang, abgelehnter Schlüssel, nicht erreichbare Gegenstelle. Nach dem Beheben Verbindung jetzt prüfen, statt auf die nächste stündliche Prüfung zu warten.
Wir wollen die Anbindung vorübergehend stoppen. Deaktivieren Sie sie, statt die Zugangsdaten zu löschen.