Meldungen-API

Erstelle, verwalte und kommentiere Meldungen programmatisch und erfasse Zeit dafür — mit Verweis auf die interaktive API-Referenz für die vollständige Spezifikation.

Meldungen-API

Mit der Meldungen-API erstellst und verwaltest du Meldungen programmatisch — weise sie einem Benutzer zu, verknüpfe sie mit einem Gerät und einem Kunden, füge Kommentare hinzu, verfolge jede Änderung in einer integrierten Änderungshistorie und erfasse aufgewendete Zeit als Zeiteinträge.

Meldungen werden unter dem Pfad /api/tickets angesprochen — "ticket" ist der interne Name der Plattform für eine Meldung — und Zeiteinträge unter /api/time-entries.

Authentifizierung und Berechtigungen

Jede Anfrage benötigt ein gültiges Bearer-Token im Authorization-Header — siehe API-Authentifizierung. Das Lesen von Meldungen erfordert die Berechtigung tickets.view; das Erstellen, Aktualisieren, Kommentieren und Löschen erfordert tickets.manage. Für Zeiteinträge gilt eine eigene Berechtigungsaufteilung — siehe Zeiteinträge unten.

Was du tun kannst

  • Meldungen auflisten, durchsuchen und lesen, einschließlich ihrer Kommentare und Änderungshistorie.
  • Eine Meldung erstellen und einem Benutzer, Gerät oder Kunden zuweisen.
  • Eine Meldung aktualisieren — jede Änderung wird automatisch in ihrer Historie erfasst.
  • Kommentare hinzufügen.
  • Eine Meldung löschen (endgültig — die Meldung und ihre Historie können nicht wiederhergestellt werden).
  • Zeiteinträge für eine Meldung erfassen, verknüpfen, mit Anmerkungen versehen und auflisten.

Wissenswertes vor dem ersten Aufruf

  • Das verknüpfte Gerät bestimmt den Kunden. Wenn eine Meldung mit einem Gerät verknüpft ist, wird ihr Kunde immer von diesem Gerät übernommen — ein Kunde, den du in derselben Anfrage sendest, wird ignoriert.
  • Aktualisierungen kapseln jeden Wert. Jedes aktualisierbare Feld wird als { "hasValue": true, "value": … } gesendet; um ein Feld unverändert zu lassen, lässt du es ganz weg. Nur gekapselte Felder werden angewendet.
  • Status und Priorität sind feste Mengen — zum Beispiel Open, InProgress und Closed für den Status sowie Low bis Critical für die Priorität.

Sammelaktionen

Diese Endpunkte benötigen Benutzerauthentifizierung und tickets.manage:

POST /api/tickets/bulk-close
POST /api/time-entries/manual/bulk
EndpunktPflichtfelder im JSON-BodyErgebnis
bulk-closeticketIds: Array von Meldungs-UUIDsclosedCount: Anzahl neu geschlossener Meldungen; bereits geschlossene werden übersprungen
manual/bulkticketIds, startedAt, endedAtcreatedCount: Anzahl angelegter Zeiteinträge; optional ist note

Beide akzeptieren 1 bis 100 IDs pro Anfrage und verarbeiten doppelte IDs nur einmal. Ist eine Meldung nicht vorhanden oder nicht zugänglich, wird die gesamte Anfrage mit 404 abgelehnt, ohne Änderungen vorzunehmen. Eine leere oder zu große Auswahl liefert 400.

Bei Sammel-Zeiteinträgen muss endedAt nach startedAt liegen. Jeder Eintrag gehört dem aufrufenden Benutzer und dem Kunden der jeweiligen Meldung, hat Status Closed und keine Geräte- oder Standortzuordnung. Derselbe Zeitraum und dieselbe Notiz werden auf jede Meldung kopiert; die Dauer wird nicht geteilt. Ein erneuter erfolgreicher Aufruf erzeugt weitere Einträge — prüfe nach einer unklaren Antwort die vorhandenen Einträge, bevor du die Anfrage wiederholst.

Kommentare und Änderungshistorie

Das Hinzufügen eines Kommentars erfordert die Berechtigung tickets.manage. Jeder Kommentar wird an das comments-Array der Meldung angehängt und zusätzlich als Historieneintrag erfasst.

Ein Kommentar kann auch von der Person am verwalteten Gerät stammen — der octoja-Agent sendet ihn in ihrem Namen, authentifiziert als Gerät statt als Benutzer. Solche Kommentare führen createdByAssetId, createdByDeviceName und createdByDisplayName anstelle von createdByUserId.

Jede Meldung führt ein history-Array (nur in der vollständigen Meldungsform), dessen changeType angibt, was geschehen ist: Created, wenn die Meldung eröffnet wurde, FieldChanged für ein geändertes Feld (mit gesetztem fieldName, oldValue und newValue), StatusChanged für einen Statuswechsel und Comment für einen hinzugefügten Kommentar.

Zeiteinträge

Zeiteinträge erfassen die für eine Meldung aufgewendete Arbeit. Sie liegen unter /api/time-entries, und eine Meldung führt ihre erfasste Zeit als separate Sammlung von Einträgen, nicht als Feld am Meldungs-Objekt. Ein Eintrag kann mit einem Gerät, mit einer Meldung oder mit beidem verknüpft sein. Ein mit einer Meldung verknüpfter Eintrag ohne Gerät ist ein Eintrag nur für die Meldung. Einige Verhaltensweisen und Validierungen sind im Schema nicht sichtbar:

  • Aufgeteilte Berechtigungen — Das Erstellen eines manuellen Eintrags erfordert tickets.manage. Zum Auflisten benötigst du eine Benutzerauthentifizierung und erhältst nur Einträge innerhalb deines Zugriffsbereichs. Das Verknüpfen, das Aktualisieren der Notiz und das Löschen eines Eintrags sind auf den Benutzer beschränkt, dem der Eintrag gehört: Der aufrufende Benutzer muss als dieser Benutzer authentifiziert sein.
  • Manuelle Einträge werden als Closed erstellt — und das Ende (endedAt) muss nach dem Start (startedAt) liegen. Lässt du assetId weg (oder sendest es als null), entsteht ein Eintrag nur für die Meldung.
  • Notiz-Updates brauchen einen offenen Eintrag — PUT /api/time-entries/{id}/note gibt 410 Gone zurück, wenn der Eintrag bereits geschlossen ist.
  • Löschen braucht einen offenen Eintrag — DELETE /api/time-entries/{id} gibt 400 Bad Request zurück, wenn der Eintrag nicht mehr Open ist. Manuelle Einträge werden als Closed erstellt; das Löschen betrifft also einen Eintrag, dessen Zeitmessung noch läuft.
  • Das Lösen erhält den Eintrag — Sendest du null an PUT /api/time-entries/{id}/ticket, bleibt der Eintrag auf seinem Gerät, zählt aber zu keiner Meldung mehr.
  • Einträge einer Meldung über den allgemeinen Endpunkt abrufen — verwende GET /api/time-entries?ticketId=<case-id>. Die Antwort enthält { items, total, totalDurationSeconds }. Unter Zeiteinträge abrufen findest du Filter, Seitennavigation und den Umfang der Zeitsumme.

Wichtige Felder

Das vollständige Meldungs-, Kommentar- und Zeiteintrags-Objekt ist Feld für Feld in Swagger dokumentiert. Einige Felder haben eine Bedeutung, die leicht übersehen wird:

  • status — eine Meldung ist Open, InProgress oder Closed; ein Zeiteintrag ist Open, Closed oder AutoClosed.
  • priority — einer von Low, Medium, High oder Critical.
  • displayId vs. ticketNumber — ticketNumber ist die rohe fortlaufende Nummer; displayId ist ihre benutzerfreundliche Form, etwa #42.
  • createdBySystem und die Ersteller-Felder — createdBySystem ist true, wenn octoja die Meldung automatisch eröffnet hat. Andernfalls hat sie entweder ein Benutzer eröffnet (createdByUserId und createdByUserName sind gesetzt) oder die Person am verwalteten Gerät; dann ist createdByUserId null, und createdByAssetId, createdByDeviceName sowie createdByDisplayName benennen Gerät und Person. Diese drei Ersteller-Felder erscheinen in der vollständigen Meldungsform und an jedem Kommentar.
  • Listenform vs. vollständige Form — der Listen-Endpoint lässt description, comments und history weg und ergänzt commentCount und lastCommentAt (die Anzahl der Kommentare und den Zeitstempel des jüngsten Kommentars). Rufe GET /api/tickets/{id} für die vollständige Meldung auf.

Vollständige Endpoint-Referenz

Für die genauen Endpoints, Query-Parameter, Request-Bodies und Response-Felder — generiert aus der laufenden Plattform, sodass sie nie veraltet — nutze die interaktive API-Referenz von octoja. Siehe API-Designprinzipien, um zu erfahren, wie du sie öffnest.

Verwandte Artikel