Aufgaben in der Codenica API

Bevor die erste Anfrage für eine Aufgabe gesendet wird, muss in den Codenica-Einstellungen ein API-Schlüssel erstellt werden. Falls noch kein Schlüssel vorhanden ist, öffnen Sie Codenica API - Einführung in einer neuen Registerkarte. Dort werden die gemeinsamen Regeln für Schlüsselerstellung, Authentifizierung, API-Adressen und die sichere Speicherung des Secrets erklärt.

Eine Aufgabe beschreibt eine konkrete Tätigkeit, eine Zuständigkeit oder einen Arbeitsschritt, der erledigt werden soll. Ein Datensatz kann ein Fälligkeitsdatum, Status, Priorität, Kategorie, Beschreibung, Ort, Abteilung, Link und Tags enthalten. Außerdem kann eine Aufgabe mit anderen Objekten aus Service Desk und Assetverwaltung verbunden werden.

Im API-Vertrag hat ein Datensatz den Wert itemType worktask, während die Endpoint-Sammlung worktasks heißt. Die Beispiele enthalten sichere Demonstrationswerte. Ersetzen Sie Kennungen, Adressen und Datumswerte durch Werte aus Ihrer Integration.

Aufgaben - API-Adresse und Installationswahl

Alle Routen für Aufgaben beginnen mit:

{BASE_URL}/api/v1/worktasks

BASE_URL ist die Adresse der Codenica-Anwendung ohne das Suffix /api/v1. Hängen Sie keinen Datenbanknamen und keine Firmenkennung an die Adresse.

Codenica Cloud: Verwenden Sie die der Firma zugewiesene Domain oder Subdomain:

export BASE_URL="https://{your-company-domain}"

Codenica On-Premise: Die von Codenica Discovery lokal registrierte Standardadresse lautet:

export BASE_URL="http://codenica.local:5150"

Wenn die Installation über eine Firmendomain, HTTPS, einen Reverse Proxy oder einen anderen Port erreichbar ist, verwenden Sie die genaue Adresse dieser Installation. Einzelheiten finden Sie in der Installationsanleitung für Codenica On-Premise. Verwenden Sie localhost nur in einer bewusst eingerichteten lokalen Testumgebung, in der HTTP-Client und API auf demselben Computer laufen.

Senden Sie tenantId weder im Body noch als Query-Parameter. Die richtige Datenbank wird über Anfrageadresse und Host ausgewählt.

Aufgaben - API-Schlüssel und Lizenzlimits

Erstellen Sie den Schlüssel unter Einstellungen -> API -> API-Schlüssel. Ein eigener Schlüssel für jede Anwendung und Umgebung erleichtert die Zugriffskontrolle. Geben Sie dem Schlüssel einen eindeutigen Namen und wählen Sie nur die für Aufgaben benötigten Scopes.

Lizenz
Codenica API-Zugriff
Maximale Anzahl von Schlüsseln
Starter
Nein
0
Plus
Ja
50
Enterprise
Ja
100

Beim Löschen eines Schlüssels wird sein Datensatz entfernt und ein Platz im Limit frei. Das Ablaufdatum beendet die Authentifizierung, ersetzt aber nicht die Pflege der Schlüsselliste. Ohne ausgewähltes Enddatum beträgt die Standardlaufzeit 90 Tage; die maximale Laufzeit eines Schlüssels beträgt 5 Jahre.

Aufgaben - Authentifizierung von Anfragen

Authentifizieren Sie jede Anfrage an die Codenica API mit zwei Headern:

X-Codenica-Client-Id: {CLIENT_ID}
X-Codenica-Client-Secret: {CLIENT_SECRET}
Accept: application/json

Beispiel für den ersten Lesezugriff:

export PUBLIC_API_CLIENT_ID="cna_your_client_id"
export PUBLIC_API_CLIENT_SECRET="cns_your_client_secret"

curl --fail-with-body --silent --show-error   --header "Accept: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/context"

Eine externe Integration benötigt weder eine Panelsitzung noch das Bearer-JWT des Benutzers. Speichern Sie das Secret serverseitig oder in einem Secrets-Manager. Legen Sie es nicht in Browsercode, einem Repository, einer URL, der Shell-History oder Logs ab.

Aufgaben - Verbindungskontext prüfen

Lesen Sie den context, bevor Sie eine Liste laden oder die erste Aufgabe erstellen. So wird bestätigt, dass die Adresse zur richtigen Datenbank führt und der Schlüssel über die erforderlichen Scopes und Limits verfügt.

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/context" | jq

Prüfen Sie in der Antwort data.tenant.id, data.tenant.name, data.tenant.subdomain, data.tenant.resolvedDomain, data.caller.clientId und data.caller.scopes. Stellen Sie außerdem sicher, dass die capabilities supportsRelationships, supportsFiles, supportsETag und supportsIdempotency enthalten.

{
  "data": {
    "apiVersion": "v1",
    "caller": {
      "authentication": "api_key",
      "clientId": "{CLIENT_ID}",
      "scopes": [
        "worktasks:read",
        "worktasks:write"
      ]
    },
    "capabilities": {
      "supportsETag": true,
      "supportsIdempotency": true,
      "supportsRelationships": true,
      "supportsFiles": true
    }
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

Wenn der context auf eine andere Firma zeigt oder der erforderliche Scope fehlt, unterbrechen Sie die Integration und korrigieren Sie Adresse oder Schlüssel. Versuchen Sie nicht, die Datenbank durch eine fremde ID im Body zu ändern.

Aufgaben - Schema und unterstützte Felder

Das Schema ist die verbindliche Quelle für die aktuelle Konfiguration der Aufgaben. Es liefert Feldtypen, Pflichtangaben, Schreibbarkeit, technische Felder und die in der Installation verfügbaren Beziehungsziele.

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/schema" | jq
{
  "data": {
    "itemType": "worktask",
    "fields": [
      {
        "name": "customId",
        "type": "string",
        "readable": true,
        "writable": true,
        "required": false
      },
      {
        "name": "title",
        "type": "string",
        "readable": true,
        "writable": true,
        "required": false
      }
    ],
    "relationshipTargets": [
      {
        "targetDataSet": "assets",
        "targetItemType": "asset"
      },
      {
        "targetDataSet": "tickets",
        "targetItemType": "ticket"
      }
    ]
  }
}

Gehen Sie nicht davon aus, dass jede Datenbank gleich konfiguriert ist. Lesen Sie vor der Feldzuordnung das aktuelle Schema und beachten Sie readable, writable, required, technical und maxLength.

Aufgaben - beschreibbare und systemische Felder

Die folgenden Felder gehören in attributes. Wenn das Schema der aktuellen Installation andere Grenzen vorgibt, hat es Vorrang.

Feld
Typ
Verwendung
customId
string
Kennung, die vom integrierenden System vergeben wird.
dateDue
date-time
Fälligkeitsdatum der Aufgabe.
dateEnd
date-time
Datum, an dem die Arbeit abgeschlossen wurde.
location
string
Ort, an dem die Arbeit ausgeführt wird.
department
string
Zuständige Abteilung oder Einheit.
tag
string
Tags, maximal 2000 Zeichen.
link
string
Link zur Quelle oder zu Details in einer anderen Anwendung.
title
string
Kurzer Titel der Aufgabe.
status
string
Status im Arbeitsablauf.
priority
string
Priorität.
category
string
Kategorie der Aufgabe.
description
string
Beschreibung, maximal 10000 Zeichen.

Das Feld pin ist schreibgeschützt und wird über die eigene Route /pin geändert. Technische Felder wie authorId, agentId, workTimeId, creator, updater, dateCreated, dateUpdated, importId, importSource und dateImported werden vom System gefüllt. Senden Sie sie nicht bei einer normalen Erstellung oder in einem PATCH. Der Wert itemType muss immer worktask sein.

Aufgaben - wichtigste Endpunkte

Die folgende Übersicht zeigt die wichtigsten Operationen für das Objekt worktask. Fügen Sie nur den Scope hinzu, der für die gewünschte Operation notwendig ist.

Methode
Pfad
Verwendung
GET
/api/v1/worktasks
Liste, Paginierung und Filter.
POST
/api/v1/worktasks
Aufgabe erstellen.
GET
/api/v1/worktasks/schema
Schema für Felder und Beziehungen.
GET
/api/v1/worktasks/stats
Feldstatistiken.
GET
/api/v1/worktasks/values
Feldwerte mit Suche.
GET
/api/v1/worktasks/{id}
Eine Aufgabe lesen.
PATCH
/api/v1/worktasks/{id}
Teilaktualisierung.
DELETE
/api/v1/worktasks/{id}
Aufgabe löschen.
POST
/api/v1/worktasks:batch
Erstellen, Aktualisieren und Löschen in einer Anfrage.
GET/POST
/api/v1/worktasks/{id}/relationships
Objektbeziehungen lesen oder hinzufügen.
POST
/api/v1/worktasks/{id}/relationships:batch
Mehrere Beziehungen hinzufügen und entfernen.
GET
/api/v1/worktasks/{id}/user-relationships
Autor und Agent lesen.
GET/POST/DELETE
/api/v1/worktasks/{id}/files...
Dateien auflisten, hochladen, anhängen, lösen und Inhalt herunterladen.
POST
/api/v1/worktasks/{id}/pin
Aufgabe anheften oder lösen.

Aufgaben - Listen und Paginierung

Lesen Sie die Aufgabenliste Seite für Seite. Setzen Sie die Sortierung ausdrücklich, damit nachfolgende Lesezugriffe eine vorhersehbare Reihenfolge verwenden:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks?page=1&pageSize=25&sort=dateCreated&direction=desc" | jq

Lesen Sie in der Antwort data.items, page, pageSize, totalItems, totalPages und hasNextPage. Wenn hasNextPage den Wert true hat, fordern Sie die nächste Seite an. Prüfen Sie die maximale Seitengröße in data.capabilities.limits.maxPageSize aus dem context.

Mit ids können ausgewählte UUIDs angefordert werden. Für eine Synchronisierung ist es sinnvoll, im integrierenden System eine stabile customId zu behalten und anschließend die von der Codenica API gelieferte UUID zu speichern.

Aufgaben - Suche und Filter

Die Liste unterstützt die Textsuche, die Suche in ausgewählten Feldern und einen strukturellen Filter. Häufige Parameter sind customId, search, title, status, priority, category, location, department, tag, createdAfter, createdBefore, updatedAfter und updatedBefore.

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks?search=arbeitsplatz&filter=status%3Aeq%3AOpen&sort=dateDue&direction=asc&page=1&pageSize=25" | jq

Ein Filter hat die Form field:operator:value. Beispiele für Operatoren:

status:eq:Open
priority:ne:Low
title:startswith:Arbeitsplatz
description:contains:Netzwerk
dateDue:gte:2026-09-01T00:00:00Z

Die Kurzformen =, !=, ge, le, sw und ew entsprechen Gleichheit, Ungleichheit, größer oder gleich, kleiner oder gleich, startswith und endswith. URL-enkodieren Sie Werte mit Sonderzeichen.

Aufgaben - Feldauswahl und eingeschlossene Daten

Mit fields begrenzen Sie die Felder, die in einem Datensatz zurückgegeben werden. Dadurch wird die Antwort kleiner und leichter zu verarbeiten:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks?fields=customId,title,status,priority,dateDue&page=1&pageSize=25" | jq

Verwenden Sie include, wenn verbundene Daten benötigt werden:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/{WORKTASK_ID}?fields=%2A&include=files%2Crelationships%2Cusers" | jq

Eingeschlossene Daten erweitern die Berechtigungen des Schlüssels nicht. Für Dateien, Beziehungen oder Benutzer benötigt der Schlüssel worktasks:files:read, worktasks:relationships:read und worktasks:users:read. Verwenden Sie fields=* nur, wenn technische Felder tatsächlich benötigt werden.

Aufgaben - Statistiken und Feldwerte

Statistiken helfen beim Erstellen von Übersichten, ohne die gesamte Sammlung herunterzuladen. Beispiel: Aufgaben nach Status zählen:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/stats?field=status&limit=20" | jq
{
  "data": {
    "total": 42,
    "field": "status",
    "values": [
      { "value": "Open", "count": 12 },
      { "value": "In progress", "count": 18 },
      { "value": "Closed", "count": 12 }
    ]
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

Der Endpunkt values liefert Feldwerte, die einer Suche entsprechen. Das eignet sich zum Beispiel für Vorschläge in einem Formular:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/values?field=category&search=ein&limit=20" | jq

Beide Routen sind schreibgeschützt und erfordern den Scope worktasks:stats.

Aufgaben - minimale Erstellung

Eine minimale Schreibanfrage muss itemType und ein Objekt attributes enthalten. In der Praxis sollten Sie sofort eine eigene customId und einen Titel setzen:

{
  "itemType": "worktask",
  "attributes": {
    "customId": "ERP-WORKTASK-2026-0042",
    "title": "Arbeitsplatz vorbereiten",
    "status": "Open",
    "priority": "High",
    "category": "IT"
  }
}

Anfrage zum Erstellen des Datensatzes:

curl --fail-with-body --silent --show-error   --request POST   --header "Accept: application/json, application/problem+json"   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "Idempotency-Key: erp-worktask-create-2026-0042"   --data-raw '{
    "itemType": "worktask",
    "attributes": {
      "customId": "ERP-WORKTASK-2026-0042",
      "title": "Arbeitsplatz vorbereiten",
      "status": "Open",
      "priority": "High",
      "category": "IT"
    }
  }'   "$BASE_URL/api/v1/worktasks" | jq

Eine erfolgreiche Antwort hat den Status 201 Created. Speichern Sie data.id und das ETag des Datensatzes für die weitere Arbeit.

Aufgaben - vollständige Erstellung

Das folgende Beispiel enthält die Daten, die ein Planungssystem normalerweise an eine Aufgabe übergibt:

{
  "itemType": "worktask",
  "attributes": {
    "customId": "ERP-WORKTASK-2026-0042",
    "title": "Arbeitsplatz für eine neue Person vorbereiten",
    "description": "Installieren Sie den Computer, konfigurieren Sie den Netzwerkzugang und bestätigen Sie die Einsatzbereitschaft des Arbeitsplatzes.",
    "status": "Open",
    "priority": "High",
    "category": "Einarbeitung",
    "dateDue": "2026-09-30T12:00:00Z",
    "location": "Krakau",
    "department": "IT",
    "tag": "einarbeitung,arbeitsplatz",
    "link": "https://portal.example.com/tasks/ERP-WORKTASK-2026-0042"
  }
}

Die Werte für Status, Priorität und Kategorie müssen der Konfiguration Ihrer Datenbank entsprechen. Die API legt kein neues Wörterbuch an, nur weil eine Integration einen neuen Namen sendet.

curl --fail-with-body --silent --show-error   --request POST   --header "Accept: application/json, application/problem+json"   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "Idempotency-Key: erp-worktask-create-2026-0042"   --data-binary @worktask.json   "$BASE_URL/api/v1/worktasks" | jq

Aufgaben - Idempotency-Key und sichere Wiederholungen

Jede Änderung mit einem API-Schlüssel benötigt den Header Idempotency-Key. Der Wert kennzeichnet eine geschäftliche Absicht. Bei einer Wiederholung derselben Anfrage behalten Sie denselben Schlüssel und ändern den Body nicht. Für eine neue Aufgabe oder eine andere Operation erzeugen Sie einen anderen Wert.

--header "Idempotency-Key: erp-worktask-create-2026-0042"

Wenn die Verbindung abbricht, nachdem die Anfrage gesendet wurde, wiederholen Sie zuerst exakt dieselbe Anfrage mit demselben Schlüssel. Erzeugen Sie nicht sofort einen neuen Schlüssel, da dadurch ein Duplikat entstehen kann. Ohne den Header endet die Änderung mit 428 und dem Code idempotency_key_required.

Aufgaben - einen Datensatz lesen

Lesen Sie den Datensatz nach der Erstellung mit der in data.id zurückgegebenen UUID:

export WORKTASK_ID="{UUID_FROM_CREATE_RESPONSE}"

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID?fields=customId,title,status,priority,category,dateDue,description" | jq

Ein einzelner Datensatz enthält id, itemType, attributes und meta. Lesen Sie das ETag aus meta; sie wird für die nächste Änderung benötigt.

{
  "data": {
    "id": "{WORKTASK_ID}",
    "itemType": "worktask",
    "attributes": {
      "customId": "ERP-WORKTASK-2026-0042",
      "title": "Arbeitsplatz für eine neue Person vorbereiten",
      "status": "Open"
    },
    "meta": {
      "customId": "ERP-WORKTASK-2026-0042",
      "etag": "{CURRENT_ETAG}"
    }
  },
  "meta": {
    "requestId": "{REQUEST_ID}",
    "etag": "{CURRENT_ETAG}"
  }
}

Aufgaben - Aktualisierung mit ETag und If-Match

Lesen Sie vor jeder Änderung die aktuelle Version des Datensatzes und bewahren Sie den exakten ETag-Wert auf, einschließlich der Anführungszeichen, sofern sie dazugehören:

ETAG=$(curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID?fields=customId,title,status,priority,description"   | jq -r '.data.meta.etag // .meta.etag')

PATCH ändert nur die ausgewählten Attribute. Speichern Sie nach dem Erfolg die neue ETag:

curl --fail-with-body --silent --show-error   --request PATCH   --header "Accept: application/json, application/problem+json"   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $ETAG"   --header "Idempotency-Key: erp-worktask-update-2026-0042"   --data-raw '{
    "attributes": {
      "title": "Arbeitsplatz für eine neue Person konfigurieren",
      "status": "In progress",
      "priority": "Normal",
      "description": "Computer und Netzwerkzugang werden eingerichtet."
    }
  }'   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID" | jq

Verwenden Sie kein ETag, die vor einer weiteren Änderung gespeichert wurde. Jede erfolgreiche Änderung kann die Version des Datensatzes verändern.

Aufgaben - veraltete oder fehlende ETag

Wenn eine andere Person oder Integration die Aufgabe geändert hat, führt eine alte ETag zu 412 Precondition Failed und dem Code if_match_failed. Die abgelehnte Änderung darf nicht angewendet werden.

{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "Die angegebene ETag ist nicht die aktuelle Version der Aufgabe.",
  "code": "if_match_failed",
  "requestId": "{REQUEST_ID}"
}

PATCH, DELETE, Beziehungen, Dateien und das Anheften ohne erforderlichen If-Match liefern 428 Precondition Required mit dem Code if_match_required. Nach 412 lesen Sie den Datensatz erneut, entscheiden Sie, ob die lokale Änderung beibehalten werden soll, und senden Sie erst danach eine neue Anfrage.

Aufgaben - anheften und lösen

Das Feld pin ist innerhalb von attributes schreibgeschützt. Ändern Sie es über den eigenen Endpunkt:

POST /api/v1/worktasks/{WORKTASK_ID}/pin

Auf Ebene 3 anheften:

curl --fail-with-body --silent --show-error   --request POST   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $ETAG"   --header "Idempotency-Key: erp-worktask-pin-2026-0042"   --data '{"pin":3}'   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/pin" | jq

Der Wert null löst die Aufgabe:

curl --fail-with-body --silent --show-error   --request POST   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $NEW_ETAG"   --header "Idempotency-Key: erp-worktask-unpin-2026-0042"   --data '{"pin":null}'   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/pin" | jq

Lesen Sie die Aufgabe nach beiden Operationen erneut, da sich ihre ETag ändern kann.

Aufgaben - Beziehungen zu Autor und Agent

Die Benutzerbeziehung hat eine eigene Route und dient zum Lesen des Autors und des zugewiesenen Agents:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/user-relationships?page=1&pageSize=20" | jq

Die Sammlung enthält nur Beziehungen mit dem Typ author oder agent. Beispiel für ein Element:

{
  "targetId": "{USER_ID}",
  "targetDataSet": "users",
  "relationshipType": "agent",
  "displayName": "Anna Schmidt",
  "email": "[email protected]",
  "role": "Agent"
}

authorId und agentId sind technische Felder. Versuchen Sie nicht, sie über einen normalen PATCH attributes zu ändern. Wenn die API-Version eine eigene Zuweisungsoperation bereitstellt, folgen Sie ihrem Schema und dem erforderlichen Scope.

Aufgaben - zulässige Objektbeziehungen

Das Aufgaben-Schema stellt elf Objektgruppen als Beziehungsziele bereit:

Zieldatensatz
Beispiel itemType
Zweck
assets
computer
Asset, zum Beispiel ein Computer oder Gerät.
clients
client
Client.
vendors
vendor
Lieferant.
documents
document
Dokument.
tickets
ticket
Ticket.
changes
change
Änderung.
problems
problem
Problem.
releases
release
Release.
notes
note
Notiz.
approvals
approval
Genehmigung.
requesteditems
requesteditem
Angefordertes Element.

Bei assets hängt der Typ vom konkreten Asset ab. Die Tabelle verwendet computer als Beispiel. Lesen Sie vor dem Speichern der Beziehung den tatsächlichen itemType des ausgewählten Objekts.

Aufgaben - targetItemType und Beziehungsformat auswählen

targetItemType muss dem tatsächlichen Typ des Zielobjekts entsprechen. Die sicherste Reihenfolge ist: Zielliste oder Schema lesen, den itemType lesen und erst danach den Relationship-Body erstellen.

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/assets?page=1&pageSize=10&sort=dateCreated&direction=desc" | jq '.data.items[0] | {id, itemType}'

Objektbeziehungen von Aufgaben akzeptieren kein relationshipType. Senden Sie nur Kennung, Sammlungsnamen und Objekttyp:

{
  "targetId": "{ASSET_ID}",
  "targetDataSet": "assets",
  "targetItemType": "computer"
}

Kopieren Sie nicht einfach asset, document oder task, ohne das konkrete Ziel zu prüfen. Ein falscher Typ führt zu einem Validierungsfehler.

Aufgaben - Beziehung hinzufügen, lesen und entfernen

Das Hinzufügen einer Asset-Beziehung benötigt die aktuelle ETag der Aufgabe und einen eigenen Idempotency-Key:

curl --fail-with-body --silent --show-error   --request POST   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $ETAG"   --header "Idempotency-Key: erp-worktask-relation-assets-2026-0042"   --data '{
    "targetId": "{ASSET_ID}",
    "targetDataSet": "assets",
    "targetItemType": "computer"
  }'   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships" | jq

Lesen Sie die Beziehung mit einem Filter für den Zieldatensatz:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships?targetDataSet=assets&page=1&pageSize=100" | jq

Eine einzelne Beziehung entfernen:

curl --fail-with-body --silent --show-error   --request DELETE   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $ETAG"   --header "Idempotency-Key: erp-worktask-relation-delete-assets-2026-0042"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships/assets/{ASSET_ID}" | jq

Nach dem Entfernen sollte die Antwort data=true enthalten. Das Hinzufügen einer neuen Beziehung liefert 201 Created; in manchen Situationen kann eine bereits vorhandene Beziehung erneut mit 200 OK beantwortet werden.

Aufgaben - Relationship-Batch

Mehrere Beziehungen lassen sich in einer Anfrage hinzufügen oder entfernen:

{
  "add": [
    {
      "targetId": "{DOCUMENT_ID}",
      "targetDataSet": "documents",
      "targetItemType": "document"
    }
  ],
  "remove": [
    {
      "targetId": "{ASSET_ID}",
      "targetDataSet": "assets",
      "targetItemType": "computer"
    }
  ]
}
curl --fail-with-body --silent --show-error   --request POST   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $ETAG"   --header "Idempotency-Key: erp-worktask-relationships-batch-2026-0042"   --data-binary @worktask-relationships.json   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/relationships:batch" | jq
{
  "data": {
    "added": 1,
    "removed": 1,
    "skipped": 0
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

Relationship-Batches akzeptieren ebenfalls kein relationshipType. Verwenden Sie die aktuelle ETag der Aufgabe und lesen Sie das Elementlimit aus dem context. Speichern Sie die neue ETag, falls sie zurückgegeben wird, und lesen Sie danach die Sammlung, um das Ergebnis zu prüfen.

Aufgaben - Dateiliste und Upload

Dateien einer Aufgabe verwenden eine eigene Endpunktgruppe. Beginnen Sie mit dem Lesen der Liste:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files?page=1&pageSize=100" | jq

Ein Listenelement enthält id, fileName, contentType, size, relationshipType, isMain und downloadUrl. Laden Sie eine neue Datei als multipart/form-data hoch:

curl --fail-with-body --silent --show-error   --request POST   --header "Accept: application/json, application/problem+json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $ETAG"   --header "Idempotency-Key: erp-worktask-file-upload-2026-0042"   --form "file=@./workstation-instructions.pdf;type=application/pdf"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files?relationshipType=instruction" | jq

Für den Upload sind worktasks:files:write, die aktuelle ETag und das aus dem context gelesene Dateilimit erforderlich. Bei Aufgaben setzt die API isMain=false; gehen Sie nicht von einer eigenen Operation für eine Hauptdatei aus.

Aufgaben - Datei herunterladen und anhängen

Laden Sie den Dateiinhalt über die Route content herunter und speichern Sie ihn im Binärmodus:

curl --fail-with-body --silent --show-error   --output ./workstation-instructions-downloaded.pdf   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files/{FILE_ID}/content"

Wenn eine Datei bereits im System gespeichert ist, können Sie sie an eine zweite Aufgabe anhängen, ohne den Inhalt erneut hochzuladen. Lesen Sie zuerst das ETag der zweiten Aufgabe:

curl --fail-with-body --silent --show-error   --request POST   --header "Accept: application/json, application/problem+json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $SECOND_WORKTASK_ETAG"   --header "Idempotency-Key: erp-worktask-file-attach-2026-0042"   "$BASE_URL/api/v1/worktasks/$SECOND_WORKTASK_ID/files/{FILE_ID}?relationshipType=reference" | jq

Attach legt eine Dateibeziehung zur zweiten Aufgabe an. Dieselbe Datei kann in beiden Datensätzen sichtbar sein; reference ist der Dateibeziehungstyp und kein Typ einer Objektbeziehung.

Aufgaben - Datei lösen und löschen

Lösen Sie die Datei mit ihrer aktuellen ETag von der zweiten Aufgabe:

curl --fail-with-body --silent --show-error   --request DELETE   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $SECOND_WORKTASK_ETAG"   --header "Idempotency-Key: erp-worktask-file-detach-2026-0042"   "$BASE_URL/api/v1/worktasks/$SECOND_WORKTASK_ID/files/{FILE_ID}" | jq

Das Lösen sollte data=true liefern und die Dateibeziehung zur ursprünglichen Aufgabe nicht entfernen. Um die Datei von der ursprünglichen Aufgabe zu löschen, lesen Sie deren neue ETag und führen Sie Folgendes aus:

curl --fail-with-body --silent --show-error   --request DELETE   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $SOURCE_WORKTASK_ETAG"   --header "Idempotency-Key: erp-worktask-file-delete-2026-0042"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID/files/{FILE_ID}" | jq

Prüfen Sie die Dateiliste nach dem Löschen. Für Aufgaben gibt es keinen eigenen Endpunkt zum Festlegen einer Hauptdatei.

Aufgaben - Batch-Vorgänge für Datensätze

Der Endpunkt /api/v1/worktasks:batch kombiniert die Erstellung, Aktualisierung und Löschung von Aufgaben. Jedes Update- oder Delete-Element hat eine eigene ETag:

{
  "items": [
    {
      "operation": "create",
      "create": {
        "itemType": "worktask",
        "attributes": {
          "customId": "ERP-WORKTASK-BATCH-A",
          "title": "Zugriff vorbereiten",
          "status": "Open",
          "priority": "Normal",
          "category": "IT"
        }
      }
    },
    {
      "operation": "update",
      "id": "{WORKTASK_ID}",
      "ifMatch": "{CURRENT_ETAG}",
      "update": {
        "attributes": {
          "title": "Zugriff vorbereiten - zweite Stufe",
          "status": "In progress"
        }
      }
    },
    {
      "operation": "delete",
      "id": "{OTHER_WORKTASK_ID}",
      "ifMatch": "{OTHER_CURRENT_ETAG}"
    }
  ]
}
curl --fail-with-body --silent --show-error   --request POST   --header "Content-Type: application/json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "Idempotency-Key: erp-worktasks-batch-2026-0042"   --data-binary @worktasks-batch.json   "$BASE_URL/api/v1/worktasks:batch" | jq
{
  "data": {
    "items": [
      {
        "index": 0,
        "operation": "create",
        "status": 201,
        "id": "{CREATED_WORKTASK_ID}",
        "data": {
          "meta": {
            "etag": "{CREATED_ETAG}"
          }
        }
      }
    ],
    "succeeded": 1,
    "failed": 0
  },
  "meta": {
    "requestId": "{REQUEST_ID}"
  }
}

Bei einem Teilergebnis kann die API 207 Multi-Status zurückgeben. Gehen Sie data.items durch, prüfen Sie jedes Element und wiederholen Sie nur Operationen, die tatsächlich einen weiteren Versuch benötigen.

Aufgaben - einen Datensatz löschen

Lesen Sie den Datensatz vor dem Löschen erneut, prüfen Sie UUID und aktuelle ETag und verwenden Sie einen neuen Idempotency-Key:

curl --fail-with-body --silent --show-error   --request DELETE   --header "Accept: application/json, application/problem+json"   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   --header "If-Match: $CURRENT_ETAG"   --header "Idempotency-Key: erp-worktask-delete-2026-0042"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID" | jq

Eine erfolgreiche Antwort enthält 200 OK und data=true. Prüfen Sie nach dem Löschen, dass der Datensatz nicht mehr verfügbar ist:

curl --fail-with-body --silent --show-error   --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID"   --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET"   "$BASE_URL/api/v1/worktasks/$WORKTASK_ID"

Erwartet wird 404 Not Found. Sie können die Liste außerdem mit customId=ERP-WORKTASK-2026-0042 filtern und totalItems=0 bestätigen.

Aufgaben - Fehler, Limits und sichere Reihenfolge

Fehlerantworten verwenden das Format Problem Details. Verwenden Sie code in der Integrationslogik und bewahren Sie bei einer Meldung auch requestId auf. Schreiben Sie weder das Secret noch vollständige Header in Logs.

HTTP
Code oder Situation
Antwort
400
validation_failed
Body, Feld, Filter oder Ziel korrigieren. Nicht wiederholen, ohne die Daten zu ändern.
401
authentication_required
Beide Header, Schlüsselstatus und Installationsadresse prüfen.
403
Fehlender Scope oder fehlender Zugriff
Den minimal erforderlichen Scope ergänzen oder die Operation ändern.
404
worktask_not_found
UUID, Datenbankadresse und Sichtbarkeit prüfen.
404
file_not_found
Die aktuelle Dateiliste lesen.
409
Konflikt
Den aktuellen Zustand lesen und entscheiden, ob die Operation sicher wiederholt werden kann.
412
if_match_failed
Die aktuelle ETag lesen und Änderungen nicht automatisch überschreiben.
413
file_too_large
Das Limit aus dem context prüfen und die Datei verkleinern.
428
if_match_required
Bei einer Änderung eines vorhandenen Datensatzes den aktuellen If-Match senden.
428
idempotency_key_required
Eine eindeutige Idempotency-Key zur Änderung hinzufügen.
429
Rate-Limit überschritten
Retry-After lesen und Backoff anwenden.
500
internal_error
requestId aufbewahren, Wiederholungen begrenzen und das Problem melden.
207
Teilweise Batch-Antwort
Jedes Element einzeln prüfen.

Lesen Sie die Header X-RateLimit-Limit und X-RateLimit-Remaining. Bei 429 lesen Sie Retry-After und verwenden Sie Backoff mit zunehmenden Wartezeiten und Jitter. Begrenzen Sie die Anzahl der Versuche und wiederholen Sie niemals endlos bei 400, 401, 403, 404 oder 412.

Sichere Reihenfolge der Operationen

  1. BASE_URL für die richtige Installation setzen und den context lesen.
  2. Scopes, Limits, Schema und den tatsächlichen itemType der Beziehungsziele prüfen.
  3. Eine Aufgabe mit eigenem Idempotency-Key erstellen und UUID sowie ETag speichern.
  4. Vor jeder Änderung, Beziehung, Dateioperation oder Pin-Aktion die aktuelle ETag lesen.
  5. Nach einer erfolgreichen Änderung die neue ETag speichern und das Ergebnis durch einen Lesezugriff prüfen.
  6. Nach der Synchronisierung den Datensatz mit customId prüfen und Demonstrationsdaten mit einer eigenen Anfrage löschen.
  7. In n8n den Knoten HTTP Request verwenden. Client ID und Client Secret in den Zugangsdaten speichern und UUID, ETag sowie Idempotency-Key zwischen den Knoten weitergeben.