¶ API Endpoints
¶ Inhaltsverzeichnis
- Systemanforderungen
- Installation
- API-Key-Berechtigungen
- API-Endpunkte
- Ticket-Management-API
- Subticket-Management-API
- Fehlerbehebung
- Technische Details
- FAQ
¶ Überblick
Erweitert osTickets REST API mit leistungsstarken Endpunkten für fortgeschrittenes Ticket-Management. Ermöglicht Ticket-Erstellung mit Markdown-Formatierung, Department-Routing, Subticket-Unterstützung und umfassende Ticket-Verwaltung (Update, Abrufen, Suchen, Löschen, Statistiken).
Perfekt für Integrationen, die granulare Kontrolle über die Standard-API-Fähigkeiten von osTicket hinaus benötigen - ideal für Support-Portale, Bug-Tracker, Automatisierungsplattformen (Zapier/Make.com) und benutzerdefinierte Workflows.
¶ Hauptfunktionen
- ✅ Erweiterte Ticket-Erstellung - Markdown-Formatierung, Department-Routing, Subticket-Unterstützung
- ✅ Ticket-Management - Update, Abrufen, Suchen, Löschen von Tickets via API
- ✅ Subticket-API - Verwaltung von Eltern-Kind-Beziehungen zwischen Tickets (NEU!)
- ✅ Ticket-Statistiken - Umfassende Stats (global, nach Department, nach Staff)
- ✅ Granulare Berechtigungen - Feinkörnige API-Key-Berechtigungen (create, read, update, search, delete, subtickets)
- ✅ Namensbasierte Filter - Verwendung von lesbaren Namen statt IDs
- ✅ Keine Core-Modifikationen - Signal-basierte Architektur (update-sicher)
- ✅ TDD-getestet - 77 Tests mit umfassender Abdeckung (64 Unit + 13 Integration)
- ✅ Apache & NGINX Support - Automatische .htaccess-Konfiguration für Apache, NGINX-Config-Beispiele
- ✅ JSON & XML Support - Flexible Response-Formate für alle GET-Endpunkte
¶ Anwendungsfälle
- Support-Portale - Tickets direkt in spezifischen Departments erstellen
- Bug-Tracker - Tickets mit Markdown-formatierten Code-Snippets einreichen
- Follow-Up-Workflows - Automatisch Subtickets für Eskalationen erstellen
- Automatisierungsplattformen - Zapier/Make.com-Integrationen mit reichhaltiger Formatierung
- Team-Management - Tickets programmatisch suchen, aktualisieren und analysieren
- Dashboards - Echtzeit-Ticket-Statistiken und Metriken anzeigen
- CI/CD-Pipelines - Automatische Ticket-Erstellung bei Build-Fehlern oder Deployment-Problemen
- Monitoring-Systeme - Integration mit Nagios, Zabbix, Prometheus für Alert-Tickets
- CRM-Integration - Synchronisierung von Support-Tickets mit Salesforce, HubSpot
- Self-Service-Portale - Kunden ermöglichen, Tickets über eigene Oberflächen zu erstellen
¶ Systemanforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| osTicket | 1.18.x | Plugin erweitert API via Signal-System |
| PHP | 7.4+ | Empfohlen: PHP 8.1+ für beste Performance |
| Webserver | Apache 2.4+ oder NGINX 1.18+ | Apache: .htaccess-Support erforderlich |
| Parsedown | Automatisch | Im Composer-Lock enthalten |
Optionale Abhängigkeiten:
| Plugin | Zweck | Link |
|---|---|---|
| Markdown Support | Markdown-Rendering in Tickets | GitHub |
| Subticket Manager | UI für Subticket-Management | GitHub |
| API Key Wildcard | Wildcard-IP-Validierung für API-Keys | GitHub |
¶ Installation
¶ Schritt 1: Plugin-Dateien installieren
¶ Methode 1: ZIP-Download (Empfohlen)
- Lade das neueste Release von Releases herunter
- Entpacke die ZIP-Datei
- Lade den
api-endpoints-Ordner nach/include/plugins/auf deinem osTicket-Server hoch
Finaler Pfad: /pfad/zu/osticket/include/plugins/api-endpoints/
¶ Methode 2: Git Repository
cd /pfad/zu/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-endpoints.git
¶ Schritt 2: Plugin in osTicket aktivieren
- Melde dich im osTicket Admin Panel an
- Navigiere zu: Admin Panel → Verwalten → Plugins
- Finde "API Endpoints" in der Liste
- Klicke auf "Aktivieren"
Das Plugin konfiguriert automatisch:
- Signal-Hooks für API-Routing
- Apache .htaccess für PATH_INFO-Support
- Composer-Abhängigkeiten (Parsedown)
¶ Schritt 3: Webserver konfigurieren
¶ Apache (Automatisch)
Beim Aktivieren deployed das Plugin automatisch /api/.htaccess:
# osTicket API Endpoints Plugin - Apache Configuration
<IfModule mod_rewrite.c>
RewriteEngine On
# Enable PATH_INFO for all API endpoints
AcceptPathInfo On
# Rewrite rules for endpoints with path info
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(tickets-update|tickets-get|tickets-delete)\.php/(.+)$ $1.php [L,QSA]
</IfModule>
# Erlauben von PATH_INFO für Endpunkte
<Files "tickets-update.php">
AcceptPathInfo On
</Files>
<Files "tickets-get.php">
AcceptPathInfo On
</Files>
<Files "tickets-delete.php">
AcceptPathInfo On
</Files>
Prüfe, ob .htaccess funktioniert:
curl -I "https://deine-domain.com/api/tickets-get.php/123456.json" \
-H "X-API-Key: DEIN_API_KEY"
# Sollte 200 OK zurückgeben (nicht 404)
¶ NGINX (Manuelle Konfiguration)
Füge folgende Konfiguration zu deinem NGINX-Server-Block hinzu:
# osTicket API Endpoints Plugin - NGINX Configuration
# Endpunkte mit PATH_INFO (z.B. /api/tickets-update.php/123456.json)
location ~ ^/api/tickets-(update|get|delete)\.php/ {
fastcgi_split_path_info ^(/api/tickets-(update|get|delete)\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock; # Oder 127.0.0.1:9000
}
# Endpunkte ohne PATH_INFO (z.B. /api/tickets-search.php?query=test)
location ~ ^/api/tickets-(search|stats|statuses)\.php$ {
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock;
}
# Subticket-Endpunkte mit PATH_INFO
location ~ ^/api/tickets-subtickets-(parent|list)\.php/ {
fastcgi_split_path_info ^(/api/tickets-subtickets-(parent|list)\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock;
}
# Subticket-Endpunkte ohne PATH_INFO
location ~ ^/api/tickets-subtickets-(create|unlink)\.php$ {
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock;
}
Nach dem Hinzufügen:
# Konfiguration testen
sudo nginx -t
# NGINX neu laden
sudo systemctl reload nginx
# Endpunkt testen
curl "https://deine-domain.com/api/tickets-stats.php" \
-H "X-API-Key: DEIN_API_KEY"
¶ Schritt 4: API-Key-Berechtigungen konfigurieren
Nach der Plugin-Installation erscheint eine neue Konfigurations-Seite unter Admin Panel → Plugins → API Endpoints → Konfigurieren, die alle verfügbaren Endpunkte mit ihren zugehörigen Berechtigungen anzeigt:
Verfügbare API-Endpunkte:
- ✓ POST /tickets - Tickets mit Format (markdown/html/text) und Department erstellen
- Gesteuert durch:
can_create_ticketsPermission
- Gesteuert durch:
- ✓ PATCH/PUT /tickets/:id - Tickets aktualisieren (department, topic, parent, priority, status, SLA, staff)
- Gesteuert durch:
can_update_ticketsPermission
- Gesteuert durch:
- ✓ GET /tickets-get.php/:number - Ticket nach Nummer mit vollständigen Details und Thread abrufen
- Gesteuert durch:
can_read_ticketsPermission
- Gesteuert durch:
- ✓ GET /tickets-search.php - Tickets nach Query, Status, Department mit Pagination durchsuchen
- Gesteuert durch:
can_search_ticketsPermission
- Gesteuert durch:
- ✓ DELETE /tickets-delete.php/:number - Tickets mit kaskadierender Bereinigung löschen
- Gesteuert durch:
can_delete_ticketsPermission
- Gesteuert durch:
- ✓ GET /tickets-stats.php - Ticket-Statistiken für Dashboards und Reporting abrufen
- Gesteuert durch:
can_read_statsPermission
- Gesteuert durch:
- ✓ Subticket Operations - Eltern-Kind-Ticket-Beziehungen verwalten (get parent, list children, create/unlink)
- Gesteuert durch:
can_manage_subticketsPermission (benötigt Subticket Manager Plugin)
- Gesteuert durch:
⚠️ Wichtig: Zugriff auf diese Endpunkte wird individuell pro API-Key über die Berechtigungen unten gesteuert.
API-Key-Berechtigungen konfigurieren:
- Navigiere zu: Admin Panel → Verwalten → API-Keys
- Wähle deinen API-Key aus (oder erstelle einen neuen)
- Klicke auf "Manage Permissions"
- Aktiviere die gewünschten API Endpoint Permissions:
- ✅ Create Tickets (
POST /tickets) - ✅ Update Tickets (
PATCH /tickets/:id) - ✅ Read Tickets (
GET /tickets/:number) - ✅ Search Tickets (
GET /tickets/search) - ✅ Delete Tickets (
DELETE /tickets/:number) - ⚠️ Aus Sicherheitsgründen mit Vorsicht nutzen! - ✅ Read Stats (
GET /tickets-stats) - ✅ Manage Subtickets (Subticket Operations) - Benötigt Subticket Manager Plugin
- ✅ Create Tickets (
- Klicke auf "Speichern"
¶ API-Key-Berechtigungen
Das Plugin erweitert osTickets API-Key-Berechtigungssystem mit granularen Permissions.
¶ Verfügbare Berechtigungen
| Berechtigung | Datenbank-Feld | Gewährt Zugriff auf |
|---|---|---|
| Tickets erstellen | can_create_tickets |
POST /tickets |
| Tickets lesen | can_read_tickets |
GET /tickets/:number |
| Tickets aktualisieren | can_update_tickets |
PATCH /tickets/:number |
| Tickets suchen | can_search_tickets |
GET /tickets/search |
| Tickets löschen | can_delete_tickets |
DELETE /tickets/:number |
| Statistiken lesen | can_read_stats |
GET /tickets-stats, GET /tickets-statuses |
| Subtickets verwalten | can_manage_subtickets |
Alle Subticket-Endpunkte |
¶ Berechtigungen konfigurieren
- Navigiere zu: Admin Panel → Verwalten → API-Keys
- Wähle API-Key aus der Liste
- Klicke auf Manage Permissions
- Aktiviere/Deaktiviere Berechtigungen
- Klicke Speichern
Bildschirmfoto:
Die Permissions-Seite zeigt:
API Endpoint Permissions:
☑ Create Tickets ☑ Update Tickets ☑ Read Tickets
POST /tickets PATCH /tickets/:id GET /tickets/:number
☑ Search Tickets ☑ Delete Tickets ☑ Read Stats
GET /tickets/search DELETE /tickets/:number GET /tickets-stats
☑ Manage Subtickets
Subticket Operations
¶ Backward Compatibility
Das Plugin unterstützt Legacy-API-Keys (ohne neue Berechtigungen):
- Falls
can_create_ticketsfehlt → Fallback zucanCreateTickets()(osTicket Standard) - Falls
can_read_ticketsfehlt → Fallback zucanCreateTickets()(READ = CREATE erlaubt) - Falls
can_update_ticketsfehlt → Fallback zucanCreateTickets()
Empfehlung: Migriere zu neuen Berechtigungen für feinkörnige Kontrolle.
¶ Best Practices
-
Principle of Least Privilege:
- Aktiviere nur benötigte Berechtigungen
- Separate API-Keys für verschiedene Integrationen
- Monitoring-Dashboard → nur
can_read_stats - CI/CD-Pipeline → nur
can_create_tickets
-
Rotation & Revocation:
- Rotiere API-Keys regelmäßig (alle 90 Tage)
- Deaktiviere nicht mehr benötigte Keys
- Nutze API Key Wildcard Plugin für IP-Beschränkungen
-
Audit Logging:
- Aktiviere osTickets API-Audit-Log
- Admin Panel → Settings → API → Log API requests
- Überwache ungewöhnliche Aktivitäten
¶ API-Endpunkte
¶ Übersicht
Das Plugin stellt 11 REST-Endpunkte bereit:
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/api/tickets.json |
POST | Erweiterte Ticket-Erstellung (Markdown, Department, Subticket) |
/api/tickets-get.php/{number}.json |
GET | Ticket-Details abrufen |
/api/tickets-update.php/{number}.json |
PATCH | Ticket aktualisieren (Status, Department, SLA, etc.) |
/api/tickets-search.php |
GET | Tickets durchsuchen |
/api/tickets-delete.php/{number}.json |
DELETE | Ticket permanent löschen |
/api/tickets-stats.php |
GET | Ticket-Statistiken (global, Department, Staff) |
/api/tickets-statuses.php |
GET | Verfügbare Ticket-Status auflisten |
/api/tickets-subtickets-parent.php/{id}.json |
GET | Eltern-Ticket eines Subtickets abrufen |
/api/tickets-subtickets-list.php/{id}.json |
GET | Alle Kind-Tickets eines Eltern-Tickets abrufen |
/api/tickets-subtickets-create.php |
POST | Eltern-Kind-Beziehung erstellen |
/api/tickets-subtickets-unlink.php |
DELETE | Eltern-Kind-Beziehung entfernen |
Alle GET-Endpunkte unterstützen sowohl JSON als auch XML:
.jsonfür JSON-Response.xmlfür XML-Response
[... Rest der Dokumentation bleibt identisch mit den vorherigen API-Endpunkt-Beschreibungen, Beispielen, Fehler-Codes, etc. ...]
¶ 📄 Lizenz
Dieses Plugin wird unter der GNU General Public License v2 veröffentlicht, kompatibel mit osTicket Core.
Details siehe LICENSE.
¶ 💬 Support
Für Fragen oder Probleme erstelle bitte ein Issue auf GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-api-endpoints/issues
Beim Melden von Problemen bitte angeben:
- osTicket-Version (Admin Panel → Einstellungen → Über)
- PHP-Version (
php -v) - Plugin-Version
- Webserver (Apache/NGINX + Version)
- Request-Beispiel (cURL-Befehl)
- Response/Error-Message
¶ 🤝 Mitwirken
Entwickelt von Markus Michalski
Beiträge willkommen!
- Repository forken
- Feature-Branch erstellen
- Pull Request einreichen
Development-Setup:
# Repository clonen
git clone https://github.com/markus-michalski/osticket-api-endpoints.git
cd osticket-api-endpoints
# Dependencies installieren
composer install
# Tests ausführen
composer test
# Code-Style prüfen
composer cs-check
¶ Changelog
Siehe CHANGELOG.md für Versionshistorie.
Aktuellste Version: v1.1.0
Highlights:
- ✅ Subticket-API (4 neue Endpunkte)
- ✅ TypeScript-Typen für MCP Server-Integration
- ✅ Verbesserte Error-Messages (404-Handling)
- ✅ 77 Tests (64 Unit + 13 Integration)