¶ API Endpoints
¶ Inhaltsverzeichnis
- Systemanforderungen
- Installation
- API-Key-Berechtigungen
- API-Endpunkte
- Ticket-Management-API
- Dateianhänge (Attachments)
- Attachment-Download
- 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
- ✅ Fälligkeitsdatum-Verwaltung - Setzen/Ändern/Löschen von Due Dates mit automatischem Overdue-Flag-Reset
- ✅ Dateianhänge - Dateien an Tickets und Notes anhängen (Base64 data-URI, max. 5 Dateien, je 10 MB)
- ✅ Attachment-Download - Ticket-Anhänge über die API herunterladen (Base64-Response mit Metadaten)
- ✅ Attachment-Metadaten - Thread-Entries enthalten automatisch Attachment-Infos (file_id, filename, size, mime_type)
- ✅ Subticket-API - Verwaltung von Eltern-Kind-Beziehungen zwischen Tickets
- ✅ 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 - 196 Tests mit umfassender Abdeckung
- ✅ 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
- Dokumentenarchivierung - Ticket-Anhänge programmatisch herunterladen und archivieren
¶ Systemanforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| osTicket | 1.18.x | Plugin erweitert API via Signal-System |
| PHP | 8.1+ | Verwendet moderne PHP-Features: Enums, Union Types, Named Arguments |
| 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
}
# Attachment-Download-Endpunkt
location ~ ^/api/tickets-attachment-download\\.php/ {
fastcgi_split_path_info ^(/api/tickets-attachment-download\\.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;
}
# 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, dueDate)
- 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-attachment-download.php/:file_id - Ticket-Anhang herunterladen (Base64)
- 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 - Ticket permanent 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:
¶ 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, GET /tickets-attachment-download/:file_id |
| 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
¶ 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 12 REST-Endpunkte bereit:
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/api/tickets.json |
POST | Erweiterte Ticket-Erstellung (Markdown, Department, Subticket, Anhänge) |
/api/tickets-get.php/{number}.json |
GET | Ticket-Details abrufen (inkl. Attachment-Metadaten) |
/api/tickets-update.php/{number}.json |
PATCH | Ticket aktualisieren (Status, Department, SLA, dueDate, Anhänge, etc.) |
/api/tickets-search.php |
GET | Tickets durchsuchen |
/api/tickets-delete.php/{number}.json |
DELETE | Ticket permanent löschen |
/api/tickets-attachment-download.php/{file_id}.json |
GET | Ticket-Anhang herunterladen (Base64) |
/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
¶ Ticket Update - Fälligkeitsdatum (dueDate)
Der PATCH /tickets-update.php/{number}.json Endpunkt unterstützt das Setzen, Ändern und Löschen von Fälligkeitsdaten.
¶ Parameter
| Parameter | Typ | Beschreibung | Beispiel |
|---|---|---|---|
dueDate |
string/null | Fälligkeitsdatum im ISO 8601 Format. null zum Löschen. |
"2026-01-31" oder "2026-01-31T17:30:00" |
¶ Verhalten
- Setzen: Übergib ein Datum im ISO 8601 Format
- Ändern: Übergib ein neues Datum (überschreibt das bestehende)
- Löschen: Übergib
nullum das Fälligkeitsdatum zu entfernen - Overdue-Flag: Wenn ein zukünftiges Datum gesetzt wird, wird das
isOverdue-Flag automatisch zurückgesetzt
¶ Beispiele
Fälligkeitsdatum setzen:
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dueDate": "2026-01-31"
}'
Fälligkeitsdatum löschen:
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dueDate": null
}'
¶ Dateianhänge (Attachments)
Die API unterstützt das Anhängen von Dateien an Tickets - sowohl bei der Erstellung als auch bei Updates (über interne Notes).
¶ Attachment-Format
Anhänge werden als JSON-Array im Base64 data-URI Format übergeben. Jedes Element ist ein Objekt mit dem Dateinamen als Key und dem data-URI als Value:
{
"attachments": [
{"screenshot.png": "data:image/png;base64,iVBORw0KGgo..."},
{"report.pdf": "data:application/pdf;base64,JVBERi0xLjQ..."}
]
}
¶ Beschränkungen
| Limit | Wert |
|---|---|
| Max. Dateien pro Request | 5 |
| Max. Dateigröße pro Datei | 10 MB |
| Max. Gesamtgröße | 50 MB |
¶ Unterstützte Dateitypen
| Kategorie | Dateitypen |
|---|---|
| Bilder | PNG, JPG/JPEG, GIF, SVG, WebP, BMP, ICO |
| Dokumente | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, ODT, ODS |
| Text | TXT, MD, CSV, JSON, XML, YAML, LOG, HTML, CSS, JS |
| Archive | ZIP, TAR, GZ, 7Z, RAR |
¶ Ticket-Erstellung mit Anhängen
FILE_B64=$(base64 -w 0 /pfad/zu/screenshot.png)
curl -X POST "https://osticket.local/api/tickets.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"email": "john@example.com",
"subject": "Bug Report mit Screenshot",
"message": "Siehe angehängten Screenshot für Details zum Fehler.",
"format": "markdown",
"attachments": [
{"screenshot.png": "data:image/png;base64,'"$FILE_B64"'"}
]
}'
¶ Note mit Anhängen (Ticket-Update)
Dateianhänge bei Updates erfordern zwingend eine
note. Ohne Note können keine Anhänge an bestehende Tickets angehängt werden.
FILE_B64=$(base64 -w 0 /pfad/zu/audit-report.pdf)
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"note": "Security-Audit abgeschlossen, Bericht angehängt.",
"noteTitle": "Audit-Ergebnis",
"attachments": [
{"SECURITY-AUDIT.pdf": "data:application/pdf;base64,'"$FILE_B64"'"}
]
}'
Tipp: Bei Verwendung über den MCP Server (Claude Code) werden Dateien automatisch Base64-kodiert. Einfach den absoluten Dateipfad angeben.
¶ Attachment-Download
Ab Version 2.3.0 können Ticket-Anhänge über die API heruntergeladen werden. Der Workflow besteht aus zwei Schritten: Zuerst die file_id aus den Attachment-Metadaten im Thread-Entry ermitteln, dann den Inhalt herunterladen.
¶ Attachment-Metadaten in Thread-Entries
Beim Abrufen eines Tickets (GET /tickets-get.php/{number}.json) enthalten Thread-Entries automatisch Attachment-Metadaten, sofern Anhänge vorhanden sind:
{
"ticket": {
"thread": [
{
"id": 540,
"type": "N",
"poster": "API",
"body": { "body": "Security Audit Datei angehängt.", "type": "markdown" },
"attachments": [
{
"id": 35,
"file_id": 28,
"filename": "SECURITY.md",
"size": 12882,
"mime_type": "text/markdown",
"inline": false
}
],
"attachment_count": 1
}
]
}
}
Attachment-Metadaten-Felder:
| Feld | Typ | Beschreibung |
|---|---|---|
id |
int | Attachment-ID (interner Verweis) |
file_id |
int | Datei-ID - wird für den Download benötigt |
filename |
string | Dateiname |
size |
int | Dateigröße in Bytes |
mime_type |
string | MIME-Typ (z.B. application/pdf, image/png) |
inline |
boolean | true = eingebettetes Bild im Text, false = eigenständiger Anhang |
Thread-Entries ohne Anhänge enthalten keine
attachments- undattachment_count-Felder. Prüfe auf Existenz, bevor du darauf zugreifst.
¶ Download-Endpunkt
URL: GET /api/tickets-attachment-download.php/{file_id}.json
Berechtigung: can_read_tickets
Parameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
file_id |
int | Die file_id aus den Attachment-Metadaten |
Response:
{
"file_id": 28,
"filename": "SECURITY.md",
"mime_type": "text/markdown",
"size": 12882,
"content": "IyBTZWN1cml0eSBBdWRpdCBSZXBvcnQK..."
}
| Feld | Typ | Beschreibung |
|---|---|---|
file_id |
int | Datei-ID |
filename |
string | Original-Dateiname |
mime_type |
string | MIME-Typ |
size |
int | Dateigröße in Bytes |
content |
string | Base64-kodierter Dateiinhalt |
¶ Workflow: Anhang herunterladen
sequenceDiagram
participant C as Client
participant A as API
participant DB as Database
C->>A: GET /tickets-get.php/123456.json
A->>DB: Ticket + Thread laden
DB-->>A: Ticket mit Attachment-Metadaten
A-->>C: JSON mit file_id in thread[].attachments
C->>A: GET /tickets-attachment-download.php/28.json
A->>A: Security-Check (file gehoert zu Ticket?)
A->>DB: Dateiinhalt laden
DB-->>A: Binärdaten
A-->>C: JSON mit Base64-Content
¶ Beispiel: Anhang herunterladen und speichern
Schritt 1 - file_id ermitteln:
# Ticket abrufen und file_id aus der Response extrahieren
curl -s "https://osticket.local/api/tickets-get.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
| jq '.ticket.thread[].attachments[]? | {file_id, filename, size}'
Ausgabe:
{"file_id": 28, "filename": "SECURITY.md", "size": 12882}
{"file_id": 29, "filename": "screenshot.png", "size": 45312}
Schritt 2 - Datei herunterladen:
# Datei herunterladen und Base64 dekodieren
curl -s "https://osticket.local/api/tickets-attachment-download.php/28.json" \
-H "X-API-Key: YOUR_API_KEY" \
| jq -r '.content' \
| base64 -d > SECURITY.md
¶ Fehler-Responses
| HTTP-Code | Ursache | Beispiel |
|---|---|---|
| 400 | Ungültige file_id | {"error": "Invalid file ID"} |
| 403 | Datei gehört nicht zu einem Ticket-Anhang | {"error": "Attachment not accessible"} |
| 404 | Datei nicht gefunden | {"error": "File not found"} |
Sicherheit: Der Download-Endpunkt prüft, ob die
file_idtatsächlich zu einem Ticket-Anhang gehört. Beliebige Datei-IDs aus derost_file-Tabelle (z.B. Logos, Backdrops) werden mit HTTP 403 abgelehnt.
Für vollständige API-Dokumentation mit Request/Response-Beispielen siehe die englische Version.
¶ 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.