# Quickstart

In vier Schritten zum ersten Aufruf der Workist-API.

## 1. API-Schlüssel erstellen {#api-schluessel}

API-Schlüssel verwalten Benutzer mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)).

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 {#erster-aufruf}

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

```bash
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](https://api.workist.com/v1/swagger/): Klicken Sie auf **Authorize**, hinterlegen Sie Ihren Schlüssel und führen Sie `GET /orders` aus.

:::warning Kein Schrägstrich am Ende
Pfade enden ohne `/`. `GET /orders` funktioniert, `GET /orders/` liefert `404`.
:::

## 3. Kanal auf API umstellen {#kanal}

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 {#ablauf}

1. Dokumente gelangen per E-Mail, über die Workbench oder per `POST /orders` in den Kanal (siehe [Dokument hochladen](/docs/api-documentation/document-api.md#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](/docs/api-documentation/document-api.md#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`:
     ```json
     {"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](/docs/api-documentation/document-api.md#failed)).

Dieselben Schritte gelten für Rechnungen, Auftragsbestätigungen, Angebotsanfragen, Lieferscheine und Leistungsverzeichnisse, jeweils mit ihrer eigenen [Ressource](/docs/api-documentation/document-api.md#ressourcen). Statt regelmäßig abzufragen, können Sie sich per [Webhook](/docs/data-exchange/webhooks.md) benachrichtigen lassen.

## Fehler {#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](/docs/api-documentation/document-api.md#fehler) beschrieben.

## Stammdaten-API {#stammdaten-api}

Für die Übertragung von Stammdaten per API siehe [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md).