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 | Datei-basierter Austausch (z. B. CSV/XML-Exporte aus dem ERP), keine eigene Integration nötig |
| API | Programmatische Integration und eigene Anwendungen; mit Webhooks 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).
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.
Die Einrichtung erfolgt in drei Teilschritten:
A1 — SSH-Schlüsselpaar erzeugen
Erzeugen Sie auf Ihrem System ein neues SSH-Schlüsselpaar. Auf macOS oder Linux genügt folgender Befehl:
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 beschrieben.
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
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.
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.
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.
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.
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
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
Host und Benutzername stehen in der Karte mit den Verbindungsdaten oben auf der Seite Öffentliche SFTP-Schlüssel.
sftp -i ~/.ssh/workist_sftp <benutzername>@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.
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 führt Sie durch diesen Schritt und den ersten Aufruf. Alle Operationen beschreibt die Dokumenten-API, die Übertragung von Stammdaten die Stammdaten-API.
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 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