Agent-API und externe Dienste

Authentifizierung

Öffnen Sie Einstellungen → Team und Zugriff → KI-Agenten, um einen verwalteten KI-Agenten anzulegen, oder Einstellungen → API und Agenten, um einen bereichsbezogenen Schlüssel für einen bestehenden Benutzer zu erstellen. Kopieren Sie das Token nur einmal, speichern Sie es außerhalb des Quellcode-Repositorys und senden Sie Anfragen ausschließlich über HTTPS.

Die API prüft sowohl die ausgewählten Token-Bereiche als auch die Berechtigungen des Benutzers, dem das Token gehört. Ein Token kann keine Tickets lesen oder ändern, auf die sein Besitzer keinen Zugriff hat.

Start jeder Integrationssitzung

GET index.php?page=api&action=agent-docs: lädt die aktuellen, versionspassenden Anweisungen und Anfrageverträge.
GET index.php?page=api&action=agent-me: prüft Identität, Berechtigungen und Bereiche des Tokens.

Verwenden Sie das Token nicht auf der Browser-Anmeldeseite. Agent-Anfragen verwenden die kanonische Route index.php?page=api&action=agent-*.

Häufige Endpunkte

GET agent-list-tickets: sichtbare Tickets auflisten und durchsuchen.
GET agent-get-ticket: ein sichtbares Ticket und seinen Verlauf laden.
POST agent-create-ticket: ein Ticket erstellen.
POST agent-add-update: einen öffentlichen Kommentar oder eine interne Notiz ohne Zeit buchen.
POST agent-add-work-entry: einen Kommentar und Zeiteintrag atomar verknüpft anlegen.
POST agent-plan-work-log und agent-apply-work-log-plan: strukturierte Arbeitsprotokolle prüfen und bestätigen.
POST agent-update-status: den Ticketstatus ändern.
POST agent-log-time: einen eigenständigen Zeiteintrag anlegen.

Die vollständige Liste, Felder und aktuellen Einschränkungen liefert agent-docs; kopieren Sie kein veraltetes Anfrageformat in eine Integration.

Beispielanfrage

FOXDESK_BASE_URL=https://helpdesk.example.com
FOXDESK_API_TOKEN=fdx_replace_with_token_from_settings

curl -fsS -X POST \
  "$FOXDESK_BASE_URL/index.php?page=api&action=agent-add-update" \
  -H "Authorization: Bearer $FOXDESK_API_TOKEN" \
  -H "Idempotency-Key: comment-ticket-542-20260729-01" \
  -H "Content-Type: application/json" \
  --data '{
    "ticket_id": 542,
    "content": "The nightly backup completed successfully.",
    "is_internal": true
  }'

Verwenden Sie für jede Schreibanfrage einen eindeutigen Idempotency-Key. Beginnen Sie mit Nur-Lese-Bereichen, fügen Sie Schreibbereiche nur für den vorgesehenen Ablauf hinzu und verwenden Sie den Plan-/Anwenden-Ablauf für strukturierte Arbeitsprotokolle.