Subticket Manager: AJAX-API

AJAX-Schnittstelle des Subticket Managers unter scp/ajax-subticket.php: Aktionen children, link, unlink, create, batch_parent_status und version mit Parametern, Antworten, Fehlern und Rate-Limit.

English Version

Zurück zur Übersicht

Subticket Manager: AJAX-API

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.

Aktionen

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.

Antwortformat

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

children

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.

link

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.

unlink

POST /scp/ajax-subticket.php?action=unlink
child_id=123&csrf_token=...

Bei Erfolg lautet die Meldung Ticket successfully unlinked.

create

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.

batch_parent_status

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).

Rate-Limit

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.

Typische Fehlermeldungen

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