Tickets in der Codenica API

Um Tickets über die API zu bearbeiten, erstellen Sie zunächst einen API-Schlüssel in den Codenica-Einstellungen. Wenn Sie noch keinen Schlüssel erstellt haben, öffnen Sie den Artikel Codenica API - Einführung in einem neuen Tab. Dort werden die Schlüsselerstellung, die Lizenzgrenzen und die gemeinsamen Authentifizierungsregeln der API beschrieben.

Ein Ticket ist ein Service-Desk-Objekt. Neben Grunddaten wie Betreff, Beschreibung und Anfragendem kann es Priorität, Auswirkung, Dringlichkeit, Schweregrad, Status, SLA-Daten, Angaben zur Lösung, Beziehungen zu anderen Objekten und Dateien enthalten. Die API bietet außerdem ticketbezogene Aktionen zum Anheften, zur Spam-Markierung, zum erneuten Öffnen, zur Bewertung, zum Anfordern einer Eskalation und für eine Genehmigungsentscheidung.

In den Beispielen werden die technischen Feld- und Routennamen verwendet, da genau diese Werte in den Anfragen übergeben werden müssen. Ersetzen Sie die Beispieltexte durch die Daten Ihrer Anwendung.

Tickets - API-Adresse

Führen Sie alle Ticket-Operationen unter dieser Adresse aus:

{BASE_URL}/api/v1/tickets

Verwenden Sie für Codenica Cloud die öffentliche Adresse Ihrer Installation. Das folgende Beispiel verwendet eine frei erfundene Firmenadresse:

https://ihr-unternehmen.codenica.com/api/v1/tickets

Bei einer On-Premise-Installation lautet die von Codenica Discovery lokal registrierte Standardadresse:

http://codenica.local:5150/api/v1/tickets

Wenn der Administrator die Installation unter einer anderen Adresse veröffentlicht hat, verwenden Sie genau diese Adresse, zum Beispiel:

https://api.ihr-unternehmen.example/api/v1/tickets

Verwenden Sie localhost nur, wenn die integrierende Anwendung auf demselben Computer wie die API ausgeführt wird. Fügen Sie den Anfragen kein tenantId hinzu. Die richtige Datenbank wird anhand der Adresse ausgewählt, mit der Sie sich verbinden.

Tickets - API-Schlüssel und Lizenzgrenzen

Erstellen Sie den Schlüssel in Codenica unter Einstellungen - API - API Keys. Das Secret wird nur einmal angezeigt, unmittelbar nach der Erstellung oder Rotation des Schlüssels. Speichern Sie beide Werte sofort im sicheren Secret-Speicher der Integration.

Die Anzahl der Schlüssel hängt von der Lizenz Ihrer Installation ab:

Lizenz
Maximale Anzahl der Schlüssel
Codenica API-Zugriff
Starter
0
Nicht verfügbar
Plus
50
Verfügbar
Enterprise
100
Verfügbar

Erstellen Sie am besten einen eigenen Schlüssel für jede Integration und jede Umgebung, zum Beispiel getrennt für Produktion, Test und Automatisierung. Wählen Sie bei der Erstellung nur die Berechtigungsbereiche aus, die diese Verbindung benötigt. Der in diesem Artikel verwendete Schlüssel sollte mindestens tickets:read, tickets:write und die weiteren Bereiche für die geplanten Vorgänge enthalten.

Tickets - Authentifizierung und sichere Anfragen

Die Integration authentifiziert sich mit zwei Headern. Dafür benötigt sie weder das Administrator-JWT noch Cookies aus dem Codenica-Panel.

export BASE_URL="https://ihr-unternehmen.codenica.com"
export CLIENT_ID="cna_example"
export CLIENT_SECRET="cns_example"

curl --request GET "$BASE_URL/api/v1/tickets?page=1&pageSize=25" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Legen Sie den Schlüssel nicht in Anwendungscode, ein Repository, Protokolle oder Fehlermeldungen. Die Werte CLIENT_ID und CLIENT_SECRET in den Beispielen sind Platzhalter. Lesen Sie sie in der Produktion aus Umgebungsvariablen oder einem eigenen Secret-Speicher.

Die API-Antwort enthält die Kennung der Anfrage in meta.requestId. Bewahren Sie sie in technischen Protokollen auf, weil sie bei der Diagnose eine bestimmte Anfrage auffindbar macht. Protokollieren Sie das Secret des Schlüssels nicht zusammen mit dieser Kennung.

Tickets - Verbindungskontext prüfen

Prüfen Sie vor der ersten Ticket-Operation, ob Adresse, Schlüssel und Berechtigungsbereiche korrekt eingerichtet sind. Der Kontext-Endpunkt liefert unter anderem die API-Version, die Datenbankkennung, die Identität des Aufrufers sowie die für den Schlüssel verfügbaren Bereiche und Fähigkeiten.

curl --request GET "$BASE_URL/api/v1/context" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Prüfen Sie in einer gültigen Antwort:

  • data.apiVersion - sie sollte die Version v1 anzeigen;
  • data.contractVersion - die von der Integration verwendete Vertragsversion;
  • data.tenant.id und data.tenant.resolvedDomain - Datenbank und erkannte Adresse;
  • data.caller.authentication - den Wert api_key;
  • data.caller.scopes - die dem Schlüssel zugewiesenen Bereiche;
  • data.capabilities.resources - das Vorhandensein der Ressource tickets;
  • die Grenzen für Seiten, Batch-Operationen und Anfragen pro Minute.

Wenn an dieser Stelle ein Bereich fehlt, ändern Sie die Schlüsselberechtigungen in den Einstellungen oder erstellen Sie einen neuen Schlüssel. Versuchen Sie nicht, Bereiche in der Anfrage selbst zu übergeben.

Tickets - Berechtigungsbereiche

Für die vollständige Ticketverwaltung benötigen Sie die folgenden Bereiche:

tickets:read
tickets:write
tickets:delete
tickets:schema
tickets:stats
tickets:relationships:read
tickets:relationships:write
tickets:users:read
tickets:users:write
tickets:files:read
tickets:files:write
tickets:technical:read
tickets:technical:write
tickets:pin:write
tickets:spam:write
tickets:reopen:write
tickets:rating:write
tickets:escalation:write
tickets:approval:write

Nicht jede Integration benötigt den vollständigen Satz. Eine Integration mit reinem Lesezugriff kann tickets:read verwenden. Für Schema, Statistiken und Werte aus Wörterbüchern fügen Sie je nach Bedarf tickets:schema und tickets:stats hinzu. Das Lesen von Beziehungen, Benutzern und Dateien erfordert die entsprechenden Bereiche :relationships:read, :users:read und :files:read.

Für Genehmigungsentscheidungen zu Tickets benötigen Sie tickets:approval:write. Wenn die Integration Genehmigungsobjekte zusätzlich selbst erstellt und verwaltet, braucht sie außerdem die Bereiche für approvals. Vergeben Sie keine Schreibrechte nur deshalb, weil sie beim ersten Test praktisch sind.

Tickets - Schema und Felder

Über das Schema rufen Sie die aktuelle Feldkonfiguration Ihrer Datenbank ab. Das ist besonders wichtig für Wörterbuchwerte wie Status, Priorität, Auswirkung, Dringlichkeit, Schweregrad, Typ und Kategorie.

curl --request GET "$BASE_URL/api/v1/tickets/schema" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Suchen Sie in der Antwort nach Feldern mit den Kennzeichnungen required, writable, technical und hasAutoGeneration. Zum Erstellen eines Tickets sind mindestens subject und requesterEmail erforderlich. Speichern Sie weitere Felder nur, wenn sie verfügbar und für Ihren Ablauf erforderlich sind.

Feldgruppe
Beispielfelder
Verwendung
Grunddaten
subject, requesterEmail, description, comments
Inhalt und Anfragender
Klassifikation
type, category, priority, impact, urgency, severity, status
Service-Zuordnung
Organisation
location, department, teams, services
Ort und Teams
Integration
externalNumber, referenceNumber, link, tags
Kennungen des externen Systems

Felder wie sla, rating, feedback, pin, isSpam und aktionsbezogene Datumsfelder werden vom System oder über eigene Endpunkte verwaltet. Gehen Sie nicht davon aus, dass sie mit einem normalen PATCH geändert werden können.

Tickets - grundlegende Routen

Die am häufigsten verwendeten Routen sind:

  • GET /api/v1/tickets - Ticketliste;
  • GET /api/v1/tickets/{id} - einzelnes Ticket;
  • POST /api/v1/tickets - Ticket erstellen;
  • PATCH /api/v1/tickets/{id} - teilweise Aktualisierung;
  • DELETE /api/v1/tickets/{id} - löschen;
  • GET /api/v1/tickets/schema - Feldschema;
  • GET /api/v1/tickets/stats - Statistiken;
  • GET /api/v1/tickets/values - für Filter verwendete Werte;
  • POST /api/v1/tickets:batch - mehrere Vorgänge in einer Anfrage.

Für Beziehungen, Benutzer, Dateien und Aktionen gibt es eigene Routen, die weiter unten beschrieben werden. Durch diese Trennung lassen sich einer Integration genau die benötigten Berechtigungen geben.

Tickets - Listen und Seitennavigation

Lesen Sie die Liste mit GET. Geben Sie am besten immer Seitennummer und Seitengröße an, auch wenn Sie zunächst nur wenige Datensätze erwarten.

curl --request GET "$BASE_URL/api/v1/tickets?page=1&pageSize=25" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort enthält ein data-Objekt mit items, page, pageSize, totalItems, totalPages und hasNextPage. Wenn hasNextPage den Wert true hat, rufen Sie die nächste Seite ab.

curl --request GET "$BASE_URL/api/v1/tickets?page=2&pageSize=25&sort=dateUpdated&direction=desc" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Sortierung hängt vom von der API unterstützten Feld ab. Für eine Synchronisierung sortieren Sie nach dateUpdated auf- oder absteigend und merken sich den zuletzt verarbeiteten Datensatz.

Tickets - Suche und Filter

Die API kann die Textsuche mit Feldfiltern kombinieren. Verwenden Sie search für eine allgemeine Suche und filter, um Operator und Wert festzulegen.

curl --get "$BASE_URL/api/v1/tickets" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=25" \
  --data-urlencode "search=VPN" \
  --data-urlencode "filter=status:eq:Open" \
  --data-urlencode "filter=priority:eq:High" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Beispiele für nützliche Ticketfilter:

  • filter=status:eq:Closed - geschlossene Tickets;
  • filter=priority:eq:High - hohe Priorität;
  • filter=subject:contains:VPN - Betreff mit dem angegebenen Text;
  • filter=description:notEmpty: - Tickets mit Beschreibung;
  • filter=isSpam:eq:false - nicht als Spam markierte Tickets.

Lesen Sie Status, Priorität und andere Wörterbuchwerte über den values-Endpunkt aus der Konfiguration Ihrer Datenbank. Gehen Sie nicht davon aus, dass in jeder Installation dieselben Namen verwendet werden.

Tickets - Antwortfelder und Erweiterungen

Für eine einfache Liste können Sie die Standardfelder verwenden. Fordern Sie zusätzliche Felder mit fields und verknüpfte Daten mit include an.

curl --get "$BASE_URL/api/v1/tickets" \
  --data-urlencode "fields=id,itemType,subject,status,priority,requesterEmail,dateUpdated" \
  --data-urlencode "include=relationships,users,files" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=10" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Mit fields=* fordern Sie das vollständige Modell an. Erweiterungen können zusätzliche Bereiche erfordern. Wenn die Integration keinen Zugriff auf Benutzer, Beziehungen oder Dateien hat, entfernen Sie das entsprechende Element aus include oder vergeben Sie die passende Berechtigung.

Achten Sie bei der Synchronisierung auf id, itemType, attributes und meta. Die Objektkennung bleibt stabil, während meta.etag für sichere Aktualisierungen verwendet wird.

Tickets - Statistiken und Feldwerte

Statistiken sind beispielsweise nützlich, um Tickets nach Priorität zu zählen. Sie verändern keine Daten.

curl --get "$BASE_URL/api/v1/tickets/stats" \
  --data-urlencode "field=priority" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Fordern Sie Feldwerte optional mit einer Suche an:

curl --get "$BASE_URL/api/v1/tickets/values" \
  --data-urlencode "field=priority" \
  --data-urlencode "search=High" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Rufen Sie vor dem Senden eines neuen Tickets die verfügbaren Werte aus derselben Datenbank ab. So verhindert die Integration, dass sie einen Wert sendet, den die lokale Konfiguration nicht kennt.

Tickets - ein Ticket erstellen

Erstellen Sie ein neues Ticket mit der Methode POST. Die kleinste sinnvolle Auswahl umfasst itemType, einen Betreff und die E-Mail-Adresse des Anfragenden. Wählen Sie die übrigen Daten passend zu Ihrem Supportprozess.

curl --request POST "$BASE_URL/api/v1/tickets" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ticket-create-ERP-2026-001" \
  --data '{
    "itemType": "ticket",
    "attributes": {
      "customId": "ERP-TICKET-2026-001",
      "subject": "VPN für die Finanzabteilung nicht verfügbar",
      "requesterEmail": "[email protected]",
      "description": "Die VPN-Verbindung wird nach einigen Minuten unterbrochen.",
      "comments": "Ticket aus dem ERP-System erstellt.",
      "source": "ERP",
      "type": "Incident",
      "category": "Network",
      "status": "Open",
      "priority": "High",
      "impact": "Department",
      "urgency": "High",
      "severity": "Major",
      "services": "VPN",
      "tags": "vpn;finance;integration",
      "externalNumber": "ERP-4581",
      "referenceNumber": "INC-2026-001",
      "currency": "PLN",
      "estimatedCost": 150.00
    }
  }'

Die Wörterbuchwerte in diesem Beispiel dienen nur zur Veranschaulichung. Ersetzen Sie sie durch die Werte, die das Schema und der values-Endpunkt Ihrer Datenbank zurückgeben. Eine erfolgreiche Erstellung liefert 201 Created, data.id und das aktuelle ETag im Header sowie in data.meta.etag. Speichern Sie diese Werte für die folgenden Vorgänge.

Tickets - Idempotenz bei Schreibvorgängen

Jede Anfrage, die Daten erstellt, ändert oder löscht, sollte einen eindeutigen Header Idempotency-Key enthalten. So wird verhindert, dass ein Ticket doppelt erstellt wird, wenn die Anwendung eine Anfrage nach einer Verbindungsunterbrechung wiederholt.

curl --request POST "$BASE_URL/api/v1/tickets" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ticket-create-ERP-2026-001" \
  --data '{
    "itemType": "ticket",
    "attributes": {
      "subject": "VPN für die Finanzabteilung nicht verfügbar",
      "requesterEmail": "[email protected]"
    }
  }'

Die Wiederholung derselben Anfrage mit derselben Methode, Route, demselben Inhalt und demselben Idempotenzschlüssel sollte denselben Datensatz zurückgeben. Ein neuer Vorgang benötigt einen neuen Schlüssel. Verwenden Sie keinen dauerhaft gleichen Schlüssel für alle Tickets.

Speichern Sie den Idempotenzschlüssel in der Integration zusammen mit dem Verarbeitungsstatus. Wenn Sie den Inhalt der Anfrage ändern, verwenden Sie einen neuen Schlüssel, auch wenn es um dasselbe Ticket geht.

Tickets - einen Datensatz lesen

Nachdem Sie die Ticketkennung erstellt oder gefunden haben, lesen Sie das Ticket über seine UUID:

export TICKET_ID="TICKET_UUID"

curl --get "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  --data-urlencode "fields=*" \
  --data-urlencode "include=relationships,users,files" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Lesen Sie data.attributes und data.meta.etag aus der Antwort. Das ETag kann sich nach Änderungen an Daten, Beziehungen, Benutzern oder Dateien sowie nach einer Aktion ändern. Verwenden Sie vor einem Schreibvorgang das aktuelle ETag und keinen Wert aus einem früheren Lesevorgang.

Tickets - bearbeiten und mit ETag schützen

Verwenden Sie für Aktualisierungen PATCH. Senden Sie nur die Felder, die geändert werden sollen, sowie das ETag der aktuellen Ticketversion.

curl --request PATCH "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-update-ERP-2026-001" \
  --data '{
    "attributes": {
      "status": "In Progress",
      "priority": "High",
      "comments": "Das Netzwerkteam untersucht die unterbrochene VPN-Sitzung.",
      "resolutionSummary": ""
    }
  }'

Eine erfolgreiche Aktualisierung liefert 200 OK und ein neues ETag. Ändern Sie aktionsverwaltete Felder wie isSpam, pin und rating über die zugehörigen Endpunkte. Versuchen Sie nicht, diese Trennung mit einem normalen PATCH zu umgehen.

Wenn Sie einen Termin, Kosten oder Integrationsdaten aktualisieren, behalten Sie die vom Schema vorgegebene Typcodierung bei. Senden Sie Datumswerte im ISO-8601-Format und Dezimalwerte als JSON-Zahlen.

Tickets - veraltetes oder fehlendes ETag

Die API blockiert einen Schreibvorgang, wenn er auf einer veralteten Version des Datensatzes basiert. Wenn zwei Prozesse gleichzeitig arbeiten, kann der zweite die Änderungen des ersten nicht ohne einen bewusst ausgelösten neuen Versuch überschreiben.

Ein veraltetes ETag liefert 412 Precondition Failed mit dem Code if_match_failed. Ein fehlender Header If-Match liefert 428 Precondition Required mit dem Code if_match_required.

curl --request PATCH "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-update-retry-ERP-2026-001" \
  --data '{
    "attributes": {
      "comments": "Neuer Versuch nach dem Lesen der aktuellen Version."
    }
  }'

Lesen Sie das Ticket nach einem dieser Fehler erneut, prüfen Sie, ob die Änderung noch erforderlich ist, und senden Sie sie mit einem neuen ETag und einem neuen Idempotenzschlüssel. Deaktivieren Sie den ETag-Schutz nicht in der Integration.

Tickets - Beziehungen zu Objekten

Ein Ticket kann mit den im Beziehungsschema sichtbaren Objekten verknüpft werden, darunter IT-Assets, Dokumente, andere Tickets, Changes, Probleme, Releases, Notizen, Genehmigungen, Work Tasks und angeforderte Elemente. Der verfügbare Katalog kann von der Konfiguration und den Schlüsselbereichen abhängen. Prüfen Sie daher vor dem Speichern einer Beziehung relationshipTargets im Schema.

Beziehungen lesen:

curl --request GET "$BASE_URL/api/v1/tickets/$TICKET_ID/relationships?page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Eine Beziehung zu einem Asset kann so hinzugefügt werden:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-relation-asset-ERP-2026-001" \
  --data '{
    "targetId": "ASSET_UUID",
    "targetDataSet": "assets",
    "targetItemType": "computer",
    "relationshipType": "related"
  }'

Um mehrere Beziehungen in einer Anfrage hinzuzufügen, verwenden Sie die Batch-Operation:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/relationships:batch" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-relationship-batch-ERP-2026-001" \
  --data '{
    "add": [
      {
        "targetId": "OTHER_TICKET_UUID",
        "targetDataSet": "tickets",
        "targetItemType": "ticket",
        "relationshipType": "related"
      },
      {
        "targetId": "DOCUMENT_UUID",
        "targetDataSet": "documents",
        "targetItemType": "document",
        "relationshipType": "related"
      }
    ],
    "remove": []
  }'

Der Wert von targetItemType muss dem tatsächlichen Typ des angegebenen Objekts entsprechen. Das ETag des Tickets ändert sich nach dem Hinzufügen oder Entfernen einer Beziehung. Entfernen Sie eine Beziehung über den Sammlungsnamen und die Objektkennung, normalerweise mit dem Abfrageparameter relationshipType:

curl --request DELETE "$BASE_URL/api/v1/tickets/assets/$ASSET_ID?relationshipType=related" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-relation-remove-ERP-2026-001"

Tickets - Beziehungen zu Benutzern und Kunden

Benutzerbeziehungen sind von Objektbeziehungen getrennt. Sie können unter anderem einen Mitarbeiter als agent zuweisen, einen Beobachter mit dem Typ watcher hinzufügen, den anfragenden Anwendungsbenutzer mit appUserRequester angeben oder einen Kunden mit clientRequester hinterlegen.

Liste der Benutzerbeziehungen:

curl --get "$BASE_URL/api/v1/tickets/$TICKET_ID/user-relationships" \
  --data-urlencode "relationshipType=agent" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Einen Mitarbeiter zuweisen:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/user-relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-agent-ERP-2026-001" \
  --data '{
    "targetId": "USER_UUID",
    "targetDataSet": "users",
    "relationshipType": "agent"
  }'

Mehrere Benutzerbeziehungen können Sie in einer Anfrage ändern:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/user-relationships:batch" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-user-relationship-batch-ERP-2026-001" \
  --data '{
    "add": [
      {
        "targetId": "WATCHER_USER_UUID",
        "targetDataSet": "users",
        "relationshipType": "watcher"
      }
    ],
    "remove": []
  }'

Ein Beobachter wird im gleichen Format hinzugefügt, verwendet aber den Typ watcher. Eine Kundenbeziehung speichern Sie mit targetDataSet gleich clients und dem Typ clientRequester. Der Bereich tickets:users:write gewährt keinen Zugriff auf jeden Benutzer und umgeht nicht dessen Berechtigungen.

Zum Entfernen einer Zuweisung muss der Beziehungstyp als Abfrageparameter angegeben werden:

curl --request DELETE "$BASE_URL/api/v1/tickets/$TICKET_ID/user-relationships/users/$USER_ID?relationshipType=agent" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-agent-remove-ERP-2026-001"

Tickets - Dateien

Dateien haben eigene Routen. Für den Upload benötigen Sie das aktuelle Ticket-ETag, einen Idempotenz-Header und eine Multipart-Anfrage.

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/files?relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-file-ERP-2026-001" \
  --form "[email protected];type=text/plain"

Ein erfolgreicher Upload liefert 201 Created und die Dateidaten, einschließlich Kennung und downloadUrl-Pfad. Die Dateiliste lesen Sie so:

curl --request GET "$BASE_URL/api/v1/tickets/$TICKET_ID/files?page=1&pageSize=50" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Dateiinhalte sind binär. Speichern Sie die Antwort deshalb in einer Datei:

curl --request GET "$BASE_URL/api/v1/tickets/$TICKET_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output heruntergeladene-datei.txt

Eine vorhandene Datei können Sie mit POST /api/v1/tickets/{id}/files/{fileId} an ein anderes Ticket anhängen. Prüfen Sie vor dem Löschen die Dateikennung und verwenden Sie das Ticket-ETag. Löschen Sie eine Datei mit DELETE /api/v1/tickets/{id}/files/{fileId}. Für Tickets gibt es keine eigene Aktion zur Auswahl einer Hauptdatei.

Eine vorhandene Datei an ein anderes Ticket anhängen:

curl --request POST "$BASE_URL/api/v1/tickets/$OTHER_TICKET_ID/files/$FILE_ID?relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $OTHER_TICKET_ETAG" \
  --header "Idempotency-Key: ticket-file-attach-ERP-2026-001"

Eine Datei aus dem aktuellen Ticket löschen:

curl --request DELETE "$BASE_URL/api/v1/tickets/$TICKET_ID/files/$FILE_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-file-delete-ERP-2026-001"

Tickets - anheften, Spam und erneut öffnen

Einige Ticket-Eigenschaften werden über eigene Aktionen geändert. Jede Aktion erfordert das aktuelle ETag und einen eigenen Idempotenzschlüssel.

Ein Ticket anheften:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/pin" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-pin-ERP-2026-001" \
  --data '{"pin":2}'

Die Markierung entfernen Sie, indem Sie null senden:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/pin" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-unpin-ERP-2026-001" \
  --data '{"pin":null}'

Ein Ticket als Spam markieren:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/spam" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-spam-ERP-2026-001" \
  --data '{"isSpam":true}'

Heben Sie die Markierung über dieselbe Route mit dem Inhalt {"isSpam":false} auf. Ein geschlossenes Ticket öffnen Sie erneut mit:

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/reopen" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-reopen-ERP-2026-001"

Für diese Vorgänge benötigen Sie je nach Aktion tickets:pin:write, tickets:spam:write oder tickets:reopen:write. Speichern Sie nach jeder erfolgreichen Aktion das von der API zurückgegebene neue ETag.

Tickets - Bewertung und Eskalationsanfrage

Nach der Bearbeitung eines Tickets können Sie eine Bewertung und den Kommentar des Bewertenden speichern. Die Bewertung liegt zwischen 0 und 5.

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/rating" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-rating-ERP-2026-001" \
  --data '{
    "rating": 4,
    "feedback": "Das Problem wurde gelöst und die Abstimmung mit dem Team verlief reibungslos.",
    "isEscalationRequested": true,
    "escalationRequestReason": "Bitte prüfen Sie zusätzlich die Stabilität der VPN-Verbindung."
  }'

Wenn Sie nur eine Bewertung speichern, lassen Sie die Eskalationsfelder weg. Für eine Eskalationsanfrage benötigen Sie zusätzlich tickets:escalation:write. Eine Bewertung allein erfordert tickets:rating:write. Nach dem Speichern erscheinen die Werte als schreibgeschützte Felder, darunter rating, feedback, dateRating, dateFeedback, dateEscalationRequest und escalationRequestReason.

Tickets - Genehmigungsentscheidung

Wenn einem Ticket eine Genehmigung zugeordnet ist, kann der bestimmte Genehmiger die Entscheidung direkt über die Ticket-Route treffen. Er benötigt tickets:approval:write und muss dieser Genehmigung zugewiesen sein.

export APPROVAL_ID="APPROVAL_UUID"

curl --request POST "$BASE_URL/api/v1/tickets/$TICKET_ID/approvals/$APPROVAL_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-approval-ERP-2026-001" \
  --data '{
    "approve": true,
    "remark": "Die Änderung wurde geprüft und kann bereitgestellt werden."
  }'

Lehnen Sie die Anfrage mit approve gleich false und einem eigenen Kommentar ab. APPROVAL_ID ist die Kennung der Genehmigung, nicht die eines Benutzers. Wenn die Integration Genehmigungen selbst erstellt, verwendet sie die separate Ressource approvals, gibt den Genehmiger an und verknüpft die Genehmigung mit dem Ticket. Lesen Sie das Ticket nach der Entscheidung erneut und speichern Sie das neue ETag.

Tickets - Batch-Operationen, Löschen und Fehler

Senden Sie mehrere Vorgänge über POST /api/v1/tickets:batch. Jedes Element beschreibt eine create-, update- oder delete-Operation. Eine Aktualisierung und eine Löschung benötigen jeweils ihr eigenes ifMatch, weil jeder Datensatz eine andere Version haben kann.

curl --request POST "$BASE_URL/api/v1/tickets:batch" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: tickets-batch-ERP-2026-001" \
  --data '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "ticket",
          "attributes": {
            "subject": "Kein Zugriff auf den Drucker",
            "requesterEmail": "[email protected]",
            "description": "Der Drucker reagiert nicht auf Druckaufträge.",
            "source": "ERP"
          }
        }
      },
      {
        "operation": "update",
        "id": "TICKET_UUID",
        "ifMatch": "\"CURRENT_ETAG\"",
        "update": {
          "attributes": {
            "priority": "Normal"
          }
        }
      }
    ]
  }'

Die Antwort kann den Status 200 oder 207 Multi-Status haben, wenn einzelne Elemente fehlschlagen. Verarbeiten Sie jedes Antwortobjekt anhand seines Index, Vorgangs, Status und error-Felds. Gehen Sie nicht davon aus, dass ein fehlgeschlagenes Element alle anderen zurücksetzt.

Zum Löschen eines einzelnen Tickets müssen Sie zunächst das aktuelle ETag lesen:

curl --request DELETE "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TICKET_ETAG" \
  --header "Idempotency-Key: ticket-delete-ERP-2026-001"

Prüfen Sie nach 200 OK mit einem weiteren Lesevorgang, dass das Ticket 404 mit dem Code ticket_not_found zurückgibt. Häufige Fehlerantworten sind: 400 für ungültige Daten, 401 für fehlende Authentifizierung, 403 für einen fehlenden Bereich, 404 für einen nicht vorhandenen Datensatz, 409 für einen Konflikt, 412 für ein veraltetes ETag, 428 für ein fehlendes ETag oder einen fehlenden Idempotenzschlüssel und 429 nach Überschreitung des Limits. Eine Problemantwort enthält unter anderem title, detail, code und requestId. Bewahren Sie diese Angaben in den Protokollen auf und wiederholen Sie nur Vorgänge, die sicher wiederholt werden können.

Eine praktische Reihenfolge ist: Kontext prüfen, Schema und Werte lesen, ein Ticket lesen oder erstellen, sein ETag speichern, Änderungen mit Idempotenz und aktuellem ETag durchführen und nach jeder Aktion den neuen Zustand lesen. Prüfen Sie am Ende die Synchronisierung mit einer nach customId oder externalNumber gefilterten Liste.