English Version

Zurück zur Übersicht

API Endpoints: Fehlerbehebung

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Fehlerbehebung

Symptom: 404 Not Found bei Endpunkten mit Pfadparameter, zum Beispiel /api/tickets-get.php/123456.json.

Prüfen: Enthält /api/.htaccess den Block, der mit API Endpoints Plugin - Apache Rewrite Rules beginnt? Liegen die Endpunkt-Dateien tickets-*.php in /api/? Bei NGINX: Gibt es einen location-Block mit PATH_INFO für den Endpunkt?

Lösung: Bei Apache das Plugin deaktivieren und wieder aktivieren, dabei werden Dateien und Regeln neu ausgerollt. Fehlt /api/.htaccess, ergänze die Regeln aus htaccess.template selbst und stelle sicher, dass .htaccess-Overrides erlaubt sind. Bei NGINX die Konfiguration aus Installation verwenden. Beachte, dass auch alle vier Subticket-Endpunkte PATH_INFO brauchen.

Symptom: 500 mit der Meldung API Endpoints Plugin not properly installed.

Prüfen: Heißt der Plugin-Ordner genau api-endpoints und liegt er in /include/plugins/?

Lösung: Benenne den Ordner um. Ein Klon des Repositories heißt standardmäßig osticket-api-endpoints, das ist falsch.

Symptom: 401 mit API key not authorized to read tickets oder einer ähnlichen Meldung.

Prüfen: Die Meldung nennt die fehlende Berechtigung. Ist die Berechtigung genau für diesen API-Key unter Verwalten → Plugins → API Endpoints → Configure → API Key Permissions aktiviert?

Lösung: Aktiviere die Berechtigung, siehe Konfiguration. Erscheinen die Berechtigungs-Checkboxen gar nicht, deaktiviere das Plugin und aktiviere es einmal erneut, dabei werden fehlende Spalten angelegt.

Symptom: 403 mit API key not authorized for subticket operations.

Prüfen: Ist can_manage_subtickets für diesen API-Key aktiviert? Die Meldung Access denied to ... department tritt nur auf, wenn das API-Key-Objekt Abteilungsbeschränkungen liefert. Standard-API-Keys von osTicket haben keine.

Lösung: Aktiviere can_manage_subtickets für den Key.

Symptom: 501 mit Subticket plugin not available.

Prüfen: Ist das Plugin Subticket Manager installiert und aktiviert?

Lösung: Installiere und aktiviere es. Erstellen und Aktualisieren mit parentTicketNumber funktionieren auch ohne, nur die vier Subticket-Endpunkte brauchen es.

Symptom: 403 mit Attachment not accessible.

Prüfen: Stammt die file_id aus den Anhang-Metadaten eines Thread-Eintrags, siehe GET Ticket abrufen?

Lösung: Nutze eine file_id aus einem Ticket-Thread. Der Endpunkt antwortet mit 403, wenn in der Anhang-Tabelle kein Eintrag mit dieser file_id existiert.

Symptom: 400 mit Markdown Support plugin is required but not active beim Erstellen eines Tickets.

Prüfen: Ist Require Markdown Plugin in den Plugin-Einstellungen aktiv, und das Plugin Markdown Support nicht?

Lösung: Aktiviere das Plugin Markdown Support oder schalte Require Markdown Plugin aus.

Symptom: 405 mit Method Not Allowed. Use GET.

Prüfen: Passt die HTTP-Methode zum Endpunkt? Suche, Abrufen, Statistik, Statusliste, Elternticket, Kindliste und Attachment-Download nutzen GET, Löschen und Verknüpfung lösen nutzen DELETE, das Aktualisieren nutzt PATCH oder PUT, das Verknüpfen von Subtickets nutzt POST.

Symptom: 400 mit Invalid URL format. Expected: ....

Prüfen: Der Pfad muss auf .json oder .xml enden und die Nummer enthalten, zum Beispiel /api/tickets-get.php/781258.json. Ticketnummern dürfen keinen Punkt enthalten.

Symptom: Ein Ticket-Update hat nur einen Teil der Felder geändert.

Prüfen: Die Felder werden nacheinander angewendet, nicht als Transaktion. Die Antwort nennt den ersten fehlerhaften Wert, die Felder davor sind schon gespeichert. Das Feld priority unterstützt das Update nicht.

Bekannte Einschränkungen

• Suche, Statistik und Statusliste haben keinen Pfadparameter. Ihre Pfadinfo hinter dem Skriptnamen ist optional und darf .json oder .xml sein, ohne sie ist die Antwort JSON.
• Der Statistik-Endpunkt iteriert bei jedem Aufruf über alle Tickets und ist auf großen Installationen langsam.
• Anhänge eines Updates werden nur zusammen mit einer note gespeichert, sonst werden sie ohne Fehler ignoriert.
• Das Plugin implementiert kein Rate Limiting.
• Das Speichern der Berechtigungen auf der Plugin-Seite übernimmt die Checkboxen aller Keys. Ist keine Berechtigungs-Checkbox irgendeines Keys angehakt (die Checkbox Read Stats allein zählt nicht), wird das Formular nicht verarbeitet, man kann also nicht in einem Speichervorgang allen Keys alle Berechtigungen entziehen.

FAQ

Welche Formate liefern die Endpunkte? Endpunkte mit {number}.{format} liefern je nach Endung JSON oder XML, Erstellen, Aktualisieren und Löschen liefern die Ticketnummer als Klartext.

Kann ich Namen statt IDs verwenden? Ja, für Abteilung, Status, Hilfethema und SLA per Name. Mitarbeiter werden über ID, Benutzername oder E-Mail-Adresse gefunden. Siehe API-Dokumentation.

Brauche ich das Plugin Subticket Manager? Nur für die vier Subticket-Endpunkte.

Funktioniert das Plugin zusammen mit API Key Wildcard? Ja. Ist dieses Plugin installiert, nutzen die eigenständigen Endpunkte und die Update-Route dessen Key-Prüfung. Die Create-Route POST /api/tickets.json ruft sie nicht auf.