Zum Hauptinhalt springen
Markdown

Quickstart

In vier Schritten zum ersten Aufruf der Workist-API.

1. API-Schlüssel erstellen​

API-Schlüssel verwalten Benutzer mit der Rolle IT oder Admin (siehe Benutzer und Rollen).

  1. Klicken Sie in der Workbench in der linken Navigationsleiste auf Einstellungen und wählen Sie Integrationen. Die Seite API-Integrationen öffnet sich.
  2. Geben Sie in der Karte Schnell-API-Integration erstellen einen Integrationsname ein, z. B. den Namen des Systems, das die API nutzt, und klicken Sie auf Integration erstellen.
  3. Die neue Integration erscheint in der Tabelle. Kopieren Sie den Schlüssel aus der Spalte API-Schlüssel und bewahren Sie ihn sicher auf. Er wird nur einmal angezeigt.
  4. Optional: Klicken Sie auf Integration bearbeiten, um den Schlüssel auf einzelne Kanäle je Dokumenttyp zu beschränken (statt Zugriff auf alle Kanäle gewähren) oder ein Ablaufdatum zu setzen. Ab diesem Tag lehnt die API den Schlüssel ab.

Über Integration konfigurieren legen Sie eine Integration direkt mit Kanälen und Ablaufdatum an. Den Schlüssel zeigt die Tabelle danach nicht an. Klicken Sie in diesem Fall auf API-Schlüssel erneuern, um einen Schlüssel zu erzeugen und anzuzeigen.

Gut zu wissen:

  • Ein Schlüssel gehört zu Ihrer Organisation, nicht zu einer Person. Er funktioniert weiter, wenn der Benutzer, der ihn erstellt hat, das Unternehmen verlässt.
  • API-Schlüssel erneuern (Symbol in der Tabelle) erzeugt einen neuen Schlüssel. Der alte ist sofort ungültig.
  • Ein abgelaufener Schlüssel funktioniert wieder, sobald Sie das Ablaufdatum über Integration bearbeiten verschieben oder entfernen.

2. Ersten Aufruf senden​

Senden Sie den Schlüssel im Header Authorization mit dem Präfix Bearer:

curl -H "Authorization: Bearer <Ihr API-Schlüssel>" \
  "https://api.workist.com/v1/orders?finished=true&imported=false"

Alternativ testen Sie die API in der Swagger-Oberfläche: Klicken Sie auf Authorize, hinterlegen Sie Ihren Schlüssel und führen Sie GET /orders aus.

Kein Schrägstrich am Ende

Pfade enden ohne /. GET /orders funktioniert, GET /orders/ liefert 404.

3. Kanal auf API umstellen​

Wenn Ihr System die Ergebnisse per API abholt, stellen Sie im Kanal unter Kanal verwalten → Upload die Übertragungsart API ein. Sonst überträgt Workist die Ergebnisse zusätzlich per SFTP, und erfolgreich übertragene Dokumente erscheinen nicht mehr unter imported=false.

4. Ablauf einrichten​

  1. Dokumente gelangen per E-Mail, über die Workbench oder per POST /orders in den Kanal (siehe Dokument hochladen).
  2. Workist verarbeitet die Dokumente. Dokumente, die Workist nicht automatisch abschließen kann, bearbeiten Ihre Mitarbeitenden in der Workbench.
  3. Ihr System fragt alle abgeschlossenen, noch nicht übergebenen Bestellungen ab: 
    GET /orders?finished=true&imported=false
    Die Antwort enthält höchstens 10 Dokumente. Folgen Sie dem Link in next, bis er null ist (siehe Seiten).
  4. Für jede Bestellung:
    • a) Import in Ihr System, z. B. als Auftrag im ERP.
    • b) Ergebnis zurückmelden mit PUT /orders/{id}/mark_imported: 
      {"status": "SUCCEEDED", "external_reference": "AB-2026-0815"}
      Lehnt Ihr System die Bestellung ab, melden Sie "status": "FAILED" mit der Ursache in external_message. Die Bestellung geht dann zurück in die Workbench (siehe Was nach FAILED passiert).

Dieselben Schritte gelten für Rechnungen, Auftragsbestätigungen, Angebotsanfragen, Lieferscheine und Leistungsverzeichnisse, jeweils mit ihrer eigenen Ressource. Statt regelmäßig abzufragen, können Sie sich per Webhook benachrichtigen lassen.

Fehler​

Die API antwortet bei Fehlern mit JSON, z. B. {"detail": "Invalid token"}. Die häufigsten Ursachen:

  • 401: Schlüssel fehlt, ist falsch oder abgelaufen (Integration has expired).
  • 404: Pfad mit / am Ende, oder das Dokument gehört zu einem Kanal, den der Schlüssel nicht sieht.
  • 400 bei mark_imported: Das Dokument ist noch nicht abgeschlossen (Record not finished yet) oder wurde bereits mit SUCCEEDED gemeldet.

Alle Fehler sind in der Dokumenten-API beschrieben.

Stammdaten-API​

Für die Übertragung von Stammdaten per API siehe Benutzung der Stammdaten-API.