# Schritt 1: Verbindung herstellen Bevor Daten zwischen Ihrem ERP-System und Workist ausgetauscht werden können, muss eine Verbindung eingerichtet werden. Workist bietet hierfür zwei Optionen, zwischen denen Sie frei wählen können: | Option | Empfohlen für | |--------|---------------| | **[SFTP](#option-a-sftp)** | Datei-basierter Austausch (z. B. CSV/XML-Exporte aus dem ERP), keine eigene Integration nötig | | **[API](#option-b-api)** | Programmatische Integration und eigene Anwendungen; mit [Webhooks](/docs/data-exchange/webhooks.md) auch ereignisgesteuert | Beide Optionen können auch in Kombination genutzt werden — z. B. Stammdaten per SFTP, Ausgaben per API. Für beide Optionen benötigen Sie ein Workbench-Konto mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). --- ## Option A: SFTP {#option-a-sftp} Workist stellt im Standard einen SFTP-Server bereit, der mittels Public-Key-Authentifizierung gesichert ist. Detaillierte Informationen zu Verzeichnisstruktur, Dateiablage und Testbefehlen finden Sie in der [SFTP-Dokumentation](/docs/data-exchange/sftp.md). Die Einrichtung erfolgt in drei Teilschritten: 1. [SSH-Schlüsselpaar erzeugen](#a1-ssh-schluesselpaar-erzeugen) 2. [Öffentlichen Schlüssel in der Workbench hinterlegen](#a2-oeffentlichen-schluessel-hinterlegen) 3. [Verbindung testen](#a3-verbindung-testen) ### A1 — SSH-Schlüsselpaar erzeugen {#a1-ssh-schluesselpaar-erzeugen} Erzeugen Sie auf Ihrem System ein neues SSH-Schlüsselpaar. Auf macOS oder Linux genügt folgender Befehl: ```bash ssh-keygen -t rsa -b 4096 -C "ihr-team@example.com" -f ~/.ssh/workist_sftp ``` Damit entstehen zwei Dateien: - `~/.ssh/workist_sftp` — der **private** Schlüssel. Diese Datei bleibt ausschließlich auf Ihrem System und darf niemals weitergegeben werden. - `~/.ssh/workist_sftp.pub` — der **öffentliche** Schlüssel. Der Inhalt wird in Schritt A2 in die Workbench eingefügt. Weitere Plattformen (z. B. Windows mit PuTTY) sind in der [SFTP-Dokumentation](/docs/data-exchange/sftp.md#erstellen-eines-ssh-key-pairs) beschrieben. :::warning Sicherheit Geben Sie ausschließlich den **öffentlichen** Schlüssel weiter. Der private Schlüssel darf nicht an Workist oder Dritte übermittelt werden. ::: ### A2 — Öffentlichen Schlüssel in der Workbench hinterlegen {#a2-oeffentlichen-schluessel-hinterlegen} Sobald der öffentliche Schlüssel in Ihrem Workist-Konto hinterlegt ist, kann sich der dazugehörige private Schlüssel ohne Passwort am SFTP-Server anmelden. Schlüssel können **hinzugefügt** und **gelöscht**, aber nicht bearbeitet werden. **Voraussetzungen** - Ein Workbench-Konto mit der Rolle IT oder Admin. Andere Rollen sehen den Bereich **Integrationen** nicht. - Ein öffentlicher SSH-Schlüssel im OpenSSH-Format (Schlüsseltext beginnt mit `ssh-rsa`). **1. In der Workbench anmelden** Öffnen Sie die Workbench in Ihrem Browser und melden Sie sich mit Ihrem Workist-Konto an. Nach der Anmeldung landen Sie auf der Übersichtsseite für eingehende Dokumente. ![Übersichtsseite nach der Anmeldung](/img/sftp-public-key/01-dashboard.png) **2. Einstellungen öffnen** Klicken Sie in der linken Navigationsleiste unten auf **Einstellungen**. Es erscheint ein kleines Menü, z. B. mit den Bereichen *Organisation*, *Teams*, *Mitarbeiter\*innen* und *Integrationen*. Welche Einträge Sie sehen, hängt von Ihrer Rolle ab. ![Einstellungen-Menü](/img/sftp-public-key/02-einstellungen-popover.png) Wählen Sie dort **Integrationen**. **3. Bereich „Integrationen" öffnen** Sie befinden sich nun im Einstellungsbereich. Auf der linken Seite sehen Sie die Unter-Navigation mit allen Einstellungskategorien. Unter dem Abschnitt **Entwickler-Tools** finden Sie den Eintrag **Öffentliche SFTP-Schlüssel**. ![Einstellungen mit Unter-Navigation](/img/sftp-public-key/03-integrationen-seite.png) Klicken Sie auf **Öffentliche SFTP-Schlüssel**. **4. Seite „Öffentliche SFTP-Schlüssel"** Oben auf der Seite zeigt eine Karte die Verbindungsdaten des SFTP-Servers von Workist: Host, Port, RSA-Fingerprint, IP-Adressen und Ihren Benutzernamen. Über das Kopier-Symbol in jeder Zeile übernehmen Sie einen Wert in die Zwischenablage. Darunter folgt das Formular **SFTP-Öffentlichen Schlüssel hinzufügen**. Sofern bereits Schlüssel hinterlegt sind, werden diese zusätzlich in einer Tabelle oberhalb des Formulars angezeigt. Über das Mülleimer-Symbol in der jeweiligen Zeile lässt sich ein bestehender Schlüssel löschen. ![Leeres Schlüsselformular](/img/sftp-public-key/04-sftp-schluessel-seite.png) **5. Öffentlichen Schlüssel einfügen** Öffnen Sie die Datei `workist_sftp.pub` (bzw. Ihre `.pub`-Datei) in einem Texteditor und kopieren Sie den **gesamten Inhalt**. Fügen Sie den Schlüssel anschließend in das Feld **Öffentlicher Schlüssel (im OpenSSH-Format, beginnend mit 'ssh-rsa')** ein. Beispiel für einen gültigen Schlüssel: ``` ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1zFZpL9a6bVQMWS20u3y3WzVCq6tbm... ihr-team@example.com ``` ![Schlüssel im Formular eingefügt](/img/sftp-public-key/05-schluessel-eingefuegt.png) :::tip Der Schlüssel ist eine einzelne lange Zeile. Achten Sie darauf, dass beim Kopieren keine zusätzlichen Zeilenumbrüche entstehen. ::: **6. Schlüssel hinzufügen** Klicken Sie unten rechts in der Karte auf **Hinzufügen**. Bei Erfolg erscheint eine grüne Bestätigungsmeldung und der neue Schlüssel wird in der Tabelle oberhalb des Formulars mit dem Zeitstempel der Hinzufügung angezeigt. **Schlüssel wieder entfernen** Auf derselben Seite befindet sich in jeder Zeile ein Mülleimer-Symbol. Ein Klick darauf entfernt den Schlüssel **sofort** vom SFTP-Server — eine Rückfrage erscheint nicht. Prüfen Sie daher vor dem Löschen, dass Sie den richtigen Schlüssel ausgewählt haben. ### A3 — Verbindung testen {#a3-verbindung-testen} Host und Benutzername stehen in der Karte mit den Verbindungsdaten oben auf der Seite **Öffentliche SFTP-Schlüssel**. ```bash sftp -i ~/.ssh/workist_sftp @ftp.workist.com ``` Beim ersten Verbinden zeigt Ihr Client den Fingerprint des Servers. Vergleichen Sie ihn mit dem RSA-Fingerprint aus der Karte, bevor Sie bestätigen. Weitere Testbefehle und die Verzeichnisstruktur finden Sie in der [SFTP-Dokumentation](/docs/data-exchange/sftp.md#verbindung-testen). --- ## Option B: API {#option-b-api} Workist stellt eine REST-API für den Datenaustausch bereit. Über die API laden Sie Dokumente hoch, rufen verarbeitete Dokumente ab, melden das Ergebnis des Imports zurück und übertragen Stammdaten. Den API-Schlüssel erstellen Sie in der Workbench unter **Einstellungen** → **Integrationen** → **API-Integrationen**. Der [Quickstart](/docs/api-documentation/quickstart.md) führt Sie durch diesen Schritt und den ersten Aufruf. Alle Operationen beschreibt die [Dokumenten-API](/docs/api-documentation/document-api.md), die Übertragung von Stammdaten die [Stammdaten-API](/docs/api-documentation/master-data-api.md). Die API arbeitet nach dem Abrufprinzip: Ihr System fragt Workist nach neuen Ergebnissen. Soll Workist Ihr System bei Ereignissen benachrichtigen, z. B. wenn ein Dokument abgeschlossen ist, richten Sie zusätzlich [Webhooks](/docs/data-exchange/webhooks.md) ein. --- ## Hilfe und Support Wenn die Verbindung trotz hinterlegtem Schlüssel scheitert oder der API-Zugang nicht wie erwartet funktioniert, wenden Sie sich bitte an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit: - den Kurznamen Ihrer Organisation - bei SFTP: den Fingerabdruck Ihres Schlüssels (`ssh-keygen -lf ~/.ssh/workist_sftp.pub`) - den Zeitpunkt des letzten Verbindungsversuchs sowie die Fehlermeldung Ihres Clients