Das Plugin liefert eine Schnittstelle für das eigene Frontend. Sie läuft über die Datei scp/ajax-subticket.php, die das Plugin beim Aktivieren dorthin kopiert. Alle Aktionen verlangen eine Staff-Anmeldung (Session-Cookie des Staff-Bereichs). Es gibt keinen API-Key-Zugang. Für Zugriffe von außen nutzt du das Plugin API Endpoints.
Die Schnittstelle ist für die JavaScript-Dateien des Plugins gebaut. Die Parameternamen und Antworten sind nicht als stabile öffentliche API gedacht.
Die Aktion wird über den Parameter action gewählt.
| Aktion | Methode | Parameter | CSRF | Zugriffsprüfung | Zweck |
|---|---|---|---|---|---|
children |
GET | tid (Ticket-ID) |
nein | Staff-Login | Children eines Tickets |
link |
POST | child_id (Ticket-ID), parent_id (Ticketnummer des Parents) |
ja | Abteilung des Child-Tickets | Child mit Parent verknüpfen |
unlink |
POST | child_id (Ticket-ID) |
ja | Abteilung des Child-Tickets | Verknüpfung lösen |
create |
POST | parent_id (Ticket-ID), subject, dept_id, message |
ja | Abteilung des Parent-Tickets | Neues Ticket anlegen und verknüpfen |
batch_parent_status |
GET | ticket_ids (kommagetrennt, höchstens 100) |
nein | Staff-Login | Parent-Status für mehrere Tickets |
version |
GET | keine | nein | Staff-Login | Diagnose: Plugin-Version, Pfade, Dateigrößen, PHP-Version |
Das CSRF-Token übergibst du als __CSRFToken__ oder csrf_token. Das Plugin-JavaScript sendet csrf_token.
Die Aktionen children, link, unlink, create und batch_parent_status antworten mit JSON im Format:
{
"success": true,
"message": "Found 2 children",
"data": []
}
Fachliche Fehler kommen mit HTTP 200 und "success": false zurück. Technische Fehler nutzen HTTP-Statuscodes:
| Status | Auslöser |
|---|---|
| 403 | Nicht als Staff angemeldet (Access denied) |
| 400 | Aktion fehlt oder ist unbekannt (Invalid action), bei children fehlt tid (Missing ticket ID) |
| 500 | Plugin-Ordner nicht gefunden, mehrfach vorhanden oder Controller fehlt, oder eine Ausnahme im Handler |
GET /scp/ajax-subticket.php?action=children&tid=15
data ist eine Liste der Children, sortiert nach Erstellungsdatum:
{
"success": true,
"message": "Found 1 children",
"data": [
{ "id": 123, "number": "181752", "subject": "DNS umstellen", "status": "Open", "created": "2026-01-15 10:30:00" }
]
}
Hat das Ticket keine Children, lautet die Meldung No children found und data ist leer.
POST /scp/ajax-subticket.php?action=link
child_id=123&parent_id=181752&csrf_token=...
parent_id ist die Ticketnummer des Parents, nicht die interne ID, und muss numerisch sein. Bei Erfolg lautet die Meldung Tickets successfully linked, sonst Failed to link tickets. Die Verknüpfung scheitert bei unbekannter Nummer, Selbst-Verknüpfung und Schleifen. Das Plugin prüft nicht, ob der Agent Zugriff auf die Abteilung des Parents hat und ob der Parent geschlossen ist.
POST /scp/ajax-subticket.php?action=unlink
child_id=123&csrf_token=...
Bei Erfolg lautet die Meldung Ticket successfully unlinked.
POST /scp/ajax-subticket.php?action=create
parent_id=15&subject=DNS umstellen&dept_id=2&message=Bitte ...&csrf_token=...
Das Plugin legt über Ticket::create() ein neues Ticket an und verknüpft es mit dem Parent. Die Oberfläche des Plugins benutzt diese Aktion nicht, der Button Create Subticket öffnet stattdessen das normale Ticket-Formular.
| Feld | Regel |
|---|---|
subject |
Pflicht, höchstens 50 Bytes (Umlaute zählen doppelt), HTML-Tags werden entfernt |
message |
Pflicht |
dept_id |
Pflicht, positive Zahl |
| Name, E-Mail | Vom Parent-Ticket übernommen |
| Hilfethema | Das des Parents. Hat der Parent keines, das erste aktive Hilfethema der Abteilung, sonst das erste aktive überhaupt, zuletzt die Hilfethema-ID 1 |
| Priorität, SLA, Fälligkeit | Vom Parent-Ticket übernommen |
| Quelle | Staff, Autoantwort und Staff-Benachrichtigung sind aus |
| Interne Notiz | Created as subticket of #<Nummer des Parents> |
Bei Erfolg enthält data die neue Ticketnummer: {"ticket_number": "181800"}. Scheitert nur das Verknüpfen, lautet die Meldung Ticket created but linking failed, und das Ticket existiert trotzdem.
GET /scp/ajax-subticket.php?action=batch_parent_status&ticket_ids=15,16,17
{
"success": true,
"message": "Parent status retrieved",
"data": {
"15": { "is_parent": true, "child_count": 3 },
"16": { "is_parent": false, "child_count": 0 }
}
}
Unbekannte IDs erscheinen mit is_parent: false. Mehr als 100 IDs ergeben den Fehler Too many ticket IDs (max 100).
Für children, link, unlink und create gilt ein Limit pro Session: höchstens 100 Anfragen innerhalb von 60 Sekunden. Wird es überschritten, sperrt das Plugin die Session für 60 Sekunden und antwortet mit Too many requests. batch_parent_status und version zählen nicht mit.
| Meldung | Bedeutung |
|---|---|
Invalid ticket ID |
Bei children: die tid ist nicht numerisch oder kleiner als 1 |
Invalid child ticket ID / Invalid parent ticket ID/number / Invalid parent ticket ID |
Der Wert ist nicht numerisch oder kleiner als 1 |
Invalid subject |
Betreff fehlt oder ist leer |
Subject too long (max 50 characters) |
Betreff länger als 50 Bytes (die Meldung nennt „characters“, gezählt wird in Bytes) |
Invalid department ID |
dept_id ist nicht numerisch oder kleiner als 1 |
Invalid message |
Nachricht fehlt oder ist leer |
Failed to create ticket |
Ticket::create() hat kein Ticket geliefert |
Failed to unlink ticket |
Der UPDATE beim Trennen ist fehlgeschlagen |
No valid ticket IDs provided |
Bei batch_parent_status enthält ticket_ids keine gültige ID |
Missing CSRF token / Invalid CSRF token |
Token fehlt oder wurde von osTicket abgelehnt |
Permission denied |
Kein Staff-Objekt in der Session |
You do not have access to this ticket |
Kein Zugriff auf die Abteilung des Tickets |
Ticket not found |
Die Ticket-ID existiert nicht |