Schnittstelle (API) und Webhooks
Eigene API-Schlüssel mit einzelnen Rechten, REST-API unter /api/v1 und signierte Webhooks bei Änderungen.
Mit der offenen Schnittstelle verbindest du AuftragsDesk mit eigenen Systemen, etwa einem ERP, einem Ticketsystem oder Werkzeugen wie n8n. Du findest sie unter Verwaltung → Integrationen → Schnittstelle und Webhooks.
API-Schlüssel anlegen
- Klicke auf Neuer API-Schlüssel und gib ihm einen Namen.
- Wähle die Rechte einzeln aus: Aufträge lesen, Aufträge anlegen und Status ändern, Kunden lesen, Kunden anlegen, Auftraggeber lesen.
- Optional: ein Ablaufdatum.
- Kopiere den Schlüssel (beginnt mit
adk_). Er wird nur einmal angezeigt.
Einen Schlüssel kannst du jederzeit widerrufen. Widerrufst du den letzten gültigen Schlüssel, pausiert AuftragsDesk auch deine Webhooks, damit keine Daten mehr an das abgeschaltete System gehen; unter Webhooks schaltest du sie bei Bedarf wieder ein.
Die REST-API
Die API liegt unter /api/v1 und wird mit dem Schlüssel im Kopf Authorization: Bearer adk_… aufgerufen.
| Endpunkt | Funktion |
|---|---|
| Aufträge | lesen (Filter nach Status, Änderungszeitpunkt, Auftraggeber, Kunde, Referenz; seitenweise), anlegen, Status ändern |
| Kunden | lesen und anlegen |
| Auftraggeber | lesen |
Statusänderungen folgen denselben Regeln wie in der Anwendung. Die vollständige Beschreibung findest du in der Swagger-Oberfläche unter /api-docs/ui.
Webhooks
Ein Webhook meldet Änderungen per HTTPS-POST an eine Adresse deiner Wahl:
auftrag.angelegt, auftrag.geaendert, auftrag.status_geaendert, auftrag.abgeschlossen, kunde.angelegt, kunde.geaendert, kunde.geloescht
- Jede Nachricht ist mit HMAC-SHA256 signiert (Kopf
AuftragsDesk-Signatur). - Schlägt die Zustellung fehl, versucht AuftragsDesk es bis zu achtmal über gut zwei Tage.
- Im Zustellprotokoll siehst du jeden Versuch. „Test senden“ und „Erneut senden“ helfen beim Einrichten.
Behandle API-Schlüssel wie Passwörter. Adressen im eigenen Netz (z. B.
localhost) sind als Webhook-Ziel gesperrt, und eine fünf Tage unerreichbare Adresse wird pausiert.
API für deine Kunden
Deine Kunden können ihr Kundenportal ebenfalls per API anbinden, mit eigenen Schlüsseln, die nur ihre Daten sehen. Wie das geht, steht unter Kundenportal-API.