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.

Geschrieben von Erdinc Akay

Zuletzt aktualisiert Vor 26 Tagen

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.

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.

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 und das Auflisten der Einträge einer Meldung erfordern beide tickets.manage. 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 Aufrufer 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.
  • 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.
  • Die Liste für eine Meldung liefert Summen — POST /api/time-entries/for-ticket gibt { items, total, totalDurationSeconds } zurück, wobei total die Anzahl der Einträge und totalDurationSeconds die summierte Dauer aller Einträge ist.

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 — true, wenn die Meldung automatisch von octoja statt von einem Benutzer eröffnet wurde.
  • 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