API - Anforderungen

Anforderungen in der Codenica API

Um mit Anforderungen über die Codenica API zu arbeiten, legen Sie zunächst einen API-Schlüssel in den Codenica-Einstellungen an. Wenn noch kein Schlüssel angelegt wurde, öffnen Sie in einem neuen Tab Codenica API - Einführung. Dort finden Sie die gemeinsamen Regeln zum Erstellen eines Schlüssels, zur Aufbewahrung des Secrets und zur Authentifizierung.

Die technische Bezeichnung der Sammlung in der API lautet requesteditems, der Typ eines einzelnen Objekts lautet requesteditem. Eine Anforderung hält einen Bedarf für den Kauf, die Lieferung, die Vorbereitung oder die Ausführung eines bestimmten Artikels fest. Neben der Beschreibung kann sie einen Termin, eine Menge, einen Preis, Kosten, einen Wert, eine Steuer, ein Budget, eine Priorität und einen Status enthalten.

Die Beispiele verwenden das Präfix PUBLIC-API-REQUESTEDITEM-20260906053922. Ersetzen Sie es in Ihrer Integration durch eine eigene Kennung und passen Sie Adressen, UUIDs und Feldwerte an die Daten Ihrer Datenbank an.

Anforderungen - API-Adresse und Auswahl der Installation

Alle Routen für Anforderungen beginnen mit:

{BASE_URL}/api/v1/requesteditems

BASE_URL ist die Adresse des Codenica-Servers ohne das Suffix /api/v1. Verwenden Sie in der Cloud die öffentliche Domain, die dem richtigen Unternehmen zugeordnet ist:

export BASE_URL="https://ihr-unternehmen.codenica.com"

In einer standardmäßigen On-Premise-Installation lautet die lokal von Codenica Discovery registrierte Adresse:

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

Wenn der Administrator die Installation unter einer Unternehmensdomain, hinter einem Reverse-Proxy, mit HTTPS oder auf einem anderen Port bereitgestellt hat, verwenden Sie die für diese Installation mitgeteilte genaue Adresse:

export BASE_URL="https://api.ihr-unternehmen.example"

Verwenden Sie localhost nicht, wenn die integrierende Anwendung auf einem anderen Computer als die API läuft. Die passende Datenbank wird anhand der Adresse ausgewählt, mit der sich die Integration verbindet. Übergeben Sie tenantId weder im Body noch in der Query-Zeichenfolge oder in einem zusätzlichen Header.

Anforderungen - Scopes des API-Schlüssels

Der für Anforderungen verwendete API-Schlüssel sollte nur die Scopes enthalten, die die jeweilige Integration benötigt. Der vollständige Scope-Satz für dieses Modul lautet:

requesteditems:read
requesteditems:write
requesteditems:delete
requesteditems:schema
requesteditems:stats
requesteditems:relationships:read
requesteditems:relationships:write
requesteditems:users:read
requesteditems:files:read
requesteditems:files:write
requesteditems:technical:read
requesteditems:technical:write
requesteditems:pin:write

Für das reine Lesen von Listen und Datensätzen wählen Sie requesteditems:read. Wenn Sie zusätzlich den Feldkatalog prüfen, wählen Sie auch requesteditems:schema. Zum Erstellen und Bearbeiten ist requesteditems:write erforderlich, zum Löschen requesteditems:delete. Fügen Sie Scopes für Beziehungen, Dateien, Statistiken, den Anforderer und das Anheften erst hinzu, wenn die Integration diese Vorgänge tatsächlich verwendet.

Wenn die Integration nach Beziehungszielen sucht, benötigt der Schlüssel außerdem die passenden Leserechte, zum Beispiel assets:read, clients:read, vendors:read, documents:read, tickets:read, changes:read, problems:read, releases:read, notes:read, approvals:read oder worktasks:read. Der Scope des Schlüssels ersetzt nicht die Berechtigungen des Benutzers.

Anforderungen - Authentifizierung

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

export CLIENT_ID="cna_ihr_client_id"
export CLIENT_SECRET="cns_ihr_client_secret"

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

Eine externe Integration benötigt weder das JWT des Administrators noch Cookies aus dem Codenica-Panel. Speichern Sie das Secret in einem serverseitigen Secret-Speicher. Legen Sie es nicht in browserseitig ausgeliefertem Code, einem Repository, einer URL, dem Befehlsverlauf oder Logs ab. Verwenden Sie außerhalb lokaler Tests HTTPS.

Speichern Sie meta.requestId aus den Antworten. Diese Kennung hilft dabei, eine bestimmte Anfrage in den Logs zu finden, ersetzt aber nicht die UUID der Anforderung und ist kein Secret.

Anforderungen - Verbindungskontext prüfen

Rufen Sie vor dem ersten Schreibvorgang den Kontext ab. So prüfen Sie, ob die Adresse zur richtigen Datenbank führt und der Schlüssel die erforderlichen Scopes und Limits besitzt:

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

Prüfen Sie in der Antwort data.apiVersion, data.contractVersion, die Daten aus data.tenant, den Wert api_key in data.caller.authentication, das Vorhandensein von requesteditems in data.capabilities.resources sowie die Scopes und Anfrage-Limits des Schlüssels.

Wenn der Kontext ein anderes Unternehmen ausweist oder der erforderliche Scope fehlt, korrigieren Sie die Adresse oder erstellen Sie einen Schlüssel mit den passenden Berechtigungen. Versuchen Sie nicht, eine Anfrage durch Übergeben einer fremden tenantId an eine andere Datenbank zu leiten.

Anforderungen - Schema und Beziehungsziele

Das Schema liefert Informationen über die aktuellen Felder, ihre Typen, ihre Schreibbarkeit und die zulässigen Beziehungsziele:

curl --request GET --url "$BASE_URL/api/v1/requesteditems/schema" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort enthält unter anderem data.itemType, data.fields und data.relationshipTargets. Für dieses Modul hat itemType den Wert requesteditem. Prüfen Sie für jedes Feld readable, writable, required, technical, unique und maxLength.

Beispiel für einen Schemaausschnitt:

{
  "data": {
    "itemType": "requesteditem",
    "fields": [
      { "name": "title", "type": "string", "writable": true },
      { "name": "dateDue", "type": "dateTime", "writable": true },
      { "name": "quantity", "type": "integer", "writable": true },
      { "name": "value", "type": "number", "writable": true },
      { "name": "pin", "type": "integer", "writable": false }
    ],
    "relationshipTargets": [
      { "targetDataSet": "assets", "targetItemType": "asset" },
      { "targetDataSet": "documents", "targetItemType": "document" },
      { "targetDataSet": "worktasks", "targetItemType": "worktask" }
    ]
  }
}

Erstellen Sie kein Mapping ausschließlich anhand dieses Beispiels. Rufen Sie vor dem Start der Integration das Schema für die richtige Datenbank ab und verwenden Sie nur die zurückgegebenen Felder und Ziele.

Anforderungen - Geschäfts- und Systemfelder

Die wichtigsten Felder einer Anforderung sind:

id, itemType, creator, updater, dateCreated, dateUpdated, importId, importSource und dateImported werden vom System festgelegt oder sind für das technische Auslesen bestimmt. Senden Sie sie nicht in attributes.

appUserRequesterId
clientRequesterId
catalogId
catalogItemId
creator
updater
dateCreated
dateUpdated
importId
importSource
dateImported

Anforderungen - verfügbare Endpoints

Die wichtigsten Routen des Moduls requesteditems sind:

GET    /api/v1/requesteditems
POST   /api/v1/requesteditems
GET    /api/v1/requesteditems/{REQUESTED_ITEM_ID}
PATCH  /api/v1/requesteditems/{REQUESTED_ITEM_ID}
DELETE /api/v1/requesteditems/{REQUESTED_ITEM_ID}
GET    /api/v1/requesteditems/schema
GET    /api/v1/requesteditems/stats
GET    /api/v1/requesteditems/values
POST   /api/v1/requesteditems:batch
GET    /api/v1/requesteditems/{REQUESTED_ITEM_ID}/relationships
POST   /api/v1/requesteditems/{REQUESTED_ITEM_ID}/relationships
POST   /api/v1/requesteditems/{REQUESTED_ITEM_ID}/relationships:batch
DELETE /api/v1/requesteditems/{REQUESTED_ITEM_ID}/relationships/{DATASET}/{TARGET_ID}
GET    /api/v1/requesteditems/{REQUESTED_ITEM_ID}/user-relationships
GET    /api/v1/requesteditems/{REQUESTED_ITEM_ID}/files
POST   /api/v1/requesteditems/{REQUESTED_ITEM_ID}/files
POST   /api/v1/requesteditems/{REQUESTED_ITEM_ID}/files/{FILE_ID}
DELETE /api/v1/requesteditems/{REQUESTED_ITEM_ID}/files/{FILE_ID}
GET    /api/v1/requesteditems/{REQUESTED_ITEM_ID}/files/{FILE_ID}/content
POST   /api/v1/requesteditems/{REQUESTED_ITEM_ID}/pin

Lesevorgänge benötigen read-Scopes. Für einzelne Änderungen sind zusätzliche Scopes entsprechend der Berechtigungstabelle erforderlich. Jede Anfrage, die Daten ändert, benötigt außerdem einen Idempotency-Key.

Anforderungen - Listen und Paginierung

Rufen Sie die Liste der Anforderungen seitenweise ab. Beispiel:

curl --request GET --url "$BASE_URL/api/v1/requesteditems?itemType=requesteditem&page=1&pageSize=25" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort enthält die Sammlung data.items und Informationen zur Seite:

{
  "data": {
    "items": [
      {
        "id": "requested-item-uuid",
        "itemType": "requesteditem",
        "attributes": {
          "customId": "ERP-REQ-2026-0042",
          "title": "Drei Monitore für einen neuen Arbeitsplatz",
          "status": "Open",
          "quantity": 3,
          "value": 3136.5
        },
        "meta": {
          "etag": "\"etag-value\""
        }
      }
    ],
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false
  },
  "meta": {
    "requestId": "request-id"
  }
}

Wechseln Sie anhand von hasNextPage zur nächsten Seite. Gehen Sie nicht davon aus, dass die letzte Seite immer weniger Elemente als der gewählte pageSize enthält. Prüfen Sie die maximale Seitengröße in data.capabilities.limits oder im aktuellen Vertrag.

Anforderungen - Suche und Filter

Verwenden Sie den Parameter search für die Textsuche. Für eine Synchronisierung sind eine stabile customId, eine UUID oder ein ausdrücklicher Filter besser geeignet:

curl --silent --show-error -G \
  --data-urlencode "search=Monitore" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  "$BASE_URL/api/v1/requesteditems"

Einfache Filter können Feldnamen verwenden:

curl --silent --show-error -G \
  --data-urlencode "status=Open" \
  --data-urlencode "priority=High" \
  --data-urlencode "customId=ERP-REQ-2026-0042" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  "$BASE_URL/api/v1/requesteditems"

Ein Strukturfilter hat die Form field:operator:value:

status:eq:Open
priority:ne:Low
quantity:gte:2
price:lt:1000
title:contains:laptop
customId:startswith:ERP-
link:notempty:

Unterstützte Operatoren sind eq, ne, gt, gte, lt, lte, contains, startswith, endswith und notempty. URL-encodieren Sie den Filterwert, besonders wenn er ein Leerzeichen, einen Doppelpunkt oder ein Sonderzeichen enthält.

Anforderungen - Felder auswählen und Daten einbeziehen

Wenn Sie nur einen Teil der Antwort benötigen, verwenden Sie fields. Fügen Sie Dateien, Beziehungen und Benutzer über include hinzu:

curl --silent --show-error -G \
  --data-urlencode "fields=id,itemType,customId,title,status,priority,dateDue,quantity,value" \
  --data-urlencode "include=files,relationships,users" \
  --data-urlencode "ids=7512ef99-0010-4962-9453-99383a377e4b" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  "$BASE_URL/api/v1/requesteditems"

Mögliche Werte für include sind files, relationships und users. Jeder Wert benötigt den passenden Scope. fields=* umgeht keine Berechtigungen für technische Felder und liefert keine Systemfelder, die für den Antwortumschlag bestimmt sind.

Zum Filtern können Sie außerdem createdAfter, createdBefore, updatedAfter, updatedBefore, sort und direction verwenden. Prüfen Sie die Feldnamen in fields, sort und filter anhand des aktuellen Schemas.

Anforderungen - Statistiken und Feldwerte

Der Endpoint stats hilft bei der Prüfung der Datenverteilung, während values Werte für den Aufbau von Filtern zurückgibt:

curl --silent --show-error -G \
  --data-urlencode "field=status" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  "$BASE_URL/api/v1/requesteditems/stats"

curl --silent --show-error -G \
  --data-urlencode "field=category" \
  --data-urlencode "search=hard" \
  --data-urlencode "limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  "$BASE_URL/api/v1/requesteditems/values"

Beispielantwort von values:

{
  "data": {
    "field": "category",
    "values": ["Hardware", "Office"]
  },
  "meta": {
    "requestId": "request-id"
  }
}

Statistiken und Werte sind Lesevorgänge und ändern keine Anforderungen. Fragen Sie sie nicht ohne Grund in einer engen Schleife ab - Schema und Feldwerte können für einen zur Integration passenden Zeitraum zwischengespeichert werden.

Anforderungen - minimale Erstellung

Erstellen Sie einen Datensatz mit POST /api/v1/requesteditems. Geben Sie itemType im Body und die Felder in attributes an:

curl --request POST --url "$BASE_URL/api/v1/requesteditems" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: requesteditem-create-unique-001" \
  --data-raw '{
    "itemType": "requesteditem",
    "attributes": {
      "customId": "ERP-REQ-2026-0042",
      "title": "Beschaffung von Büromaterial",
      "category": "Office",
      "quantity": 10,
      "currency": "PLN",
      "status": "Open",
      "description": "Eintrag durch die Integration erstellt."
    }
  }'

Der Wert von itemType muss requesteditem sein. Richten Sie Feldnamen und Typen an der Schemaantwort aus. Senden Sie Datumswerte als ISO 8601 und Zahlen als JSON-Zahlen, nicht als formatierte Zeichenfolgen.

Eine erfolgreiche Antwort hat den Status 201 Created. Speichern Sie data.id, das ETag aus dem HTTP-Header und das ETag aus data.meta.etag.

Anforderungen - vollständige Erstellung mit Finanzfeldern

Das folgende Beispiel entspricht einem Datensatz aus dem vollständigen Demonstrationsablauf. Es zeigt einen Termin, einen Ort, einen Status, eine Priorität und Abrechnungsdaten:

curl --request POST --url "$BASE_URL/api/v1/requesteditems" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: requesteditem-create-20260906053922-source" \
  --data-raw '{
    "itemType": "requesteditem",
    "attributes": {
      "customId": "PUBLIC-API-REQUESTEDITEM-20260906053922-SOURCE",
      "dateDue": "2026-12-31T17:00:00Z",
      "dateEnd": "2027-01-15T17:00:00Z",
      "location": "Warsaw",
      "department": "IT",
      "tag": "public-api,requesteditems,demo",
      "link": "https://codenica.com",
      "title": "Vollständiger Ablauf der API für Anforderungen",
      "status": "Open",
      "priority": "High",
      "category": "Hardware",
      "budget": "IT-2026",
      "currency": "PLN",
      "tax": 23,
      "quantity": 3,
      "cost": 300,
      "price": 100,
      "value": 369,
      "description": "Demonstrative Anforderung über die Public API erstellt."
    },
    "customValues": [
      {
        "name": "description",
        "valuePattern": "[requested-item-demo] Public API"
      }
    ]
  }'

customValues ist optional. Entfernen Sie diese Eigenschaft, wenn die Integration keine zusätzlichen Wertregeln verwendet. Senden Sie keine technischen Felder nur deshalb, weil sie in einer Antwort erschienen sind.

Anforderungen - Erstellung sicher wiederholen

Wenn nach dem Senden einer Anfrage ein Timeout auftritt und Sie nicht wissen, ob der Datensatz gespeichert wurde, wiederholen Sie exakt dieselbe Operation mit demselben Idempotency-Key und einem identischen Body:

curl --request POST --url "$BASE_URL/api/v1/requesteditems" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: requesteditem-create-20260906053922-source" \
  --data-binary @requesteditem-create.json

Die Datei requesteditem-create.json muss exakt den Body der ersten Anfrage enthalten. Die Wiederholung gibt denselben Datensatz zurück, statt ein Duplikat zu erstellen. Eine neue Geschäftsabsicht, ein geänderter Body oder eine andere Route erfordern einen neuen Schlüssel. Eine Wiederholung mit einem anderen Body liefert 422 idempotency_key_reused.

Speichern Sie den Idempotenzschlüssel zusammen mit dem Operationsstatus auf der Seite der Integration. Verwenden Sie dafür nicht das Client Secret.

Anforderungen - Datensatz und ETag lesen

Rufen Sie eine Anforderung nach der Erstellung oder Suche per UUID ab:

export REQUESTED_ITEM_ID="7512ef99-0010-4962-9453-99383a377e4b"

curl --request GET --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID?include=files,relationships,users" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Das aktuelle ETag finden Sie im HTTP-Header und normalerweise auch in data.meta.etag sowie im übergeordneten Antwortumschlag meta.etag:

ETag: "etag-value"

Ein ETag ist eine undurchsichtige Version eines bestimmten Datensatzes. Entfernen Sie die im Header zurückgegebenen Anführungszeichen nicht und berechnen Sie diesen Wert nicht selbst. Rufen Sie vor jeder Änderung am Datensatz, an einer Beziehung oder an einer Datei ein frisches ETag ab, wenn eine andere Person oder Integration den Datensatz geändert haben könnte.

Anforderungen - Teilaktualisierung mit If-Match

PATCH ändert nur die im Body gesendeten Felder. Dafür sind das aktuelle ETag und ein neuer Idempotenzschlüssel erforderlich:

export REQUESTED_ITEM_ETAG='"etag-value-from-get"'

curl --request PATCH --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-update-20260906-0001" \
  --data-raw '{
    "attributes": {
      "dateDue": "2027-01-31T17:00:00Z",
      "title": "Requested Item API - vollständiger Ablauf - aktualisiert",
      "status": "In progress",
      "priority": "Normal",
      "quantity": 4,
      "price": 125,
      "value": 615
    }
  }'

Sie müssen nicht das vollständige Objekt senden. Nicht im Body enthaltene Felder bleiben unverändert. Ersetzen Sie nach einer Antwort 200 OK das gespeicherte ETag durch den von der API zurückgegebenen Wert. Jede folgende Änderung muss die neueste Version verwenden.

Anforderungen - veraltetes ETag und fehlendes If-Match

Ein fehlender If-Match-Header wird abgelehnt, damit eine Integration keine Änderungen überschreibt, die von einer anderen Person vorgenommen wurden:

curl --request PATCH --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: requesteditem-update-without-etag-0001" \
  --data-raw '{"attributes":{"status":"Approved"}}'

Erwartet wird 428 Precondition Required mit dem Code if_match_required. Wenn Sie ein altes ETag senden, erhalten Sie 412 Precondition Failed mit dem Code if_match_failed:

HTTP 412 Precondition Failed
code: if_match_failed

Rufen Sie den Datensatz nach einem 412-Fehler erneut ab, vergleichen Sie Ihre Änderung mit den aktuellen Daten und senden Sie erst dann einen weiteren PATCH. Starten Sie keine blinde Schleife, die Änderungen eines Benutzers überschreibt.

Anforderungen - Anheften und Lösen

pin ist ein schreibgeschütztes Feld in attributes. Setzen Sie es über einen eigenen Endpoint mit dem aktuellen ETag:

curl --request POST --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/pin" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-pin-0001" \
  --data '{"pin":3}'

Zulässig sind Werte von 0 bis 3. Um die Markierung zu entfernen, verwenden Sie null:

curl --request POST --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/pin" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-unpin-0001" \
  --data '{"pin":null}'

Speichern Sie nach jedem Vorgang das neue ETag. Versuchen Sie nicht, pin über einen normalen PATCH zu ändern.

Anforderungen - Beziehung zum Anforderer

Jede Anforderung kann eine Systembeziehung requester besitzen. Lesen Sie sie über:

curl --request GET --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/user-relationships" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Der Anforderer wird durch einen bestehenden Systemablauf festgelegt und kann auf appUserRequesterId oder clientRequesterId verweisen. Die Public API ermöglicht das Lesen, bietet aber keinen separaten POST- oder DELETE-Vorgang zum Ändern dieser Beziehung. Versuchen Sie nicht, den Anforderer über ein undokumentiertes Feld in attributes zu setzen. Zum Lesen sind requesteditems:users:read und die passenden Datenberechtigungen erforderlich.

Anforderungen - zulässige Objektbeziehungen

Der aktuelle Katalog der Beziehungsziele für Anforderungen umfasst:

Nie ma relacji z samą kolekcją requesteditems ani z confirmations. Cel musi być widoczny dla użytkownika przypisanego do klucza i zgodny z listą relationshipTargets zwróconą przez schemat.

Anforderungen - Beziehungen hinzufügen, lesen und entfernen

Eine Objektbeziehung speichert kein relationshipType. Senden Sie im Payload targetId, targetDataSet und einen passenden targetItemType:

{
  "targetId": "5ddc5b5a-5bdc-46f9-ab7e-5ad8f6775b3a",
  "targetDataSet": "assets",
  "targetItemType": "asset"
}

Zum Hinzufügen einer Beziehung benötigen Sie das aktuelle ETag der Quelle, den Scope requesteditems:relationships:write und einen eigenen Idempotenzschlüssel:

curl --request POST --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-relationship-asset-0001" \
  --data '{
    "targetId": "5ddc5b5a-5bdc-46f9-ab7e-5ad8f6775b3a",
    "targetDataSet": "assets",
    "targetItemType": "asset"
  }'

Lesen Sie die Beziehungsliste über:

curl --request GET --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/relationships?page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Entfernen Sie eine einzelne Beziehung über Sammlung und UUID des Ziels:

curl --request DELETE --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/relationships/assets/5ddc5b5a-5bdc-46f9-ab7e-5ad8f6775b3a" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-relationship-asset-delete-0001"

Lesen Sie nach dem Hinzufügen oder Entfernen einer Beziehung die Quelldaten erneut und speichern Sie das neue ETag. Wenn das Schema ein Ziel nicht zurückgibt, verwenden Sie es nicht in der Integration.

Anforderungen - Beziehungen gesammelt ändern

Für mehrere Änderungen in einer Anfrage verwenden Sie relationships:batch. Lassen Sie bei Beziehungen von Anforderungen weiterhin relationshipType weg:

curl --request POST --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-relationship-batch-0001" \
  --data-raw '{
    "add": [
      {
        "targetId": "5ddc5b5a-5bdc-46f9-ab7e-5ad8f6775b3a",
        "targetDataSet": "assets",
        "targetItemType": "asset"
      },
      {
        "targetId": "88b93fb8-8848-4669-9d87-ed4795e13bcc",
        "targetDataSet": "documents",
        "targetItemType": "document"
      }
    ],
    "remove": [
      {
        "targetId": "8f42dc16-167b-4e4a-983f-862ae85f3c7a",
        "targetDataSet": "worktasks",
        "targetItemType": "worktask"
      }
    ]
  }'

Die Antwort enthält Zähler:

{
  "data": {
    "added": 2,
    "removed": 1,
    "skipped": 0
  },
  "meta": {
    "requestId": "request-id"
  }
}

Behandeln Sie skipped nicht automatisch als geschäftlichen Erfolg. Lesen Sie nach dem Batch die Beziehungssammlung und prüfen Sie das Ergebnis jeder Änderung.

Anforderungen - Dateien auflisten und hochladen

Dateien werden getrennt von den Feldern der Anforderung verarbeitet. Lesen Sie zuerst die aktuelle Liste:

curl --request GET --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/files?page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Senden Sie die Datei als multipart/form-data. Die Dateifunktion wird in der Query-Zeichenfolge übergeben:

curl --request POST --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/files?relationshipType=request-form" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-file-upload-0001" \
  --form "[email protected];type=application/pdf"

Ein Dateielement enthält unter anderem id, fileName, contentType, size, relationshipType, isMain und downloadUrl. Prüfen Sie die Größe vor dem Senden und legen Sie den MIME-Typ bewusst fest.

Anforderungen - Dateien herunterladen, verknüpfen und löschen

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

curl --request GET --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output heruntergeladene-anforderung.pdf

Wenn die Datei bereits im System vorhanden ist, können Sie sie ohne erneuten Upload verknüpfen:

curl --request POST --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/files/$FILE_ID?relationshipType=quotation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-file-attach-0001"

Eine Datei aus einer Anforderung entfernen:

curl --request DELETE --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID/files/$FILE_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-file-delete-0001"

Attach erstellt eine Beziehung zu einer vorhandenen Datei, lädt aber keine neue Kopie hoch. Das aktuelle Modell der Anforderungen besitzt keinen Endpoint für eine Hauptdatei: Jedes Element hat isMain=false. Verwenden Sie für dieses Objekt weder /files/{FILE_ID}/main noch makeMain.

Anforderungen - Batch-Operationen

Der Endpoint /api/v1/requesteditems:batch kann mehrere Datensätze erstellen, bearbeiten und löschen. Er ersetzt weder Dateioperationen noch das Anheften oder Beziehungs-Batches:

curl --request POST --url "$BASE_URL/api/v1/requesteditems:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: requesteditems-batch-20260906-0001" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "requesteditem",
          "attributes": {
            "customId": "ERP-REQ-BATCH-001",
            "title": "Maus und Tastatur für das Team",
            "category": "Hardware",
            "quantity": 5,
            "price": 150,
            "currency": "PLN",
            "status": "Open"
          }
        }
      },
      {
        "operation": "update",
        "id": "7dc877ec-4766-42cc-a34a-900e55ab3f46",
        "ifMatch": "\"etag-from-get\"",
        "update": {
          "attributes": {
            "status": "Approved",
            "quantity": 6
          }
        }
      },
      {
        "operation": "delete",
        "id": "476b8c2e-6da9-409d-bb35-98039619ccfe",
        "ifMatch": "\"etag-after-update\""
      }
    ]
  }'

Jedes Element für update und delete besitzt ein eigenes ETag. Ein Batch ist keine Alles-oder-nichts-Transaktion. Gehen Sie die items der Antwort durch und speichern Sie Status, UUID und Fehler für jedes Element. Ein Teilergebnis kann 207 Multi-Status zurückgeben.

Anforderungen - Datensatz löschen

Rufen Sie den Datensatz vor dem Löschen erneut ab, prüfen Sie UUID und aktuelles ETag und stellen Sie sicher, dass der Geschäftsprozess das Löschen erlaubt:

curl --request DELETE --url "$BASE_URL/api/v1/requesteditems/$REQUESTED_ITEM_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $REQUESTED_ITEM_ETAG" \
  --header "Idempotency-Key: requesteditem-delete-20260906-0001"

Eine erfolgreiche Antwort liefert 200 OK und data=true. Nach dem Löschen sollte das erneute Lesen der UUID 404 Not Found mit dem Code requestedItem_not_found liefern. Sie können auch eine abschließende Prüfung über eine nach customId gefilterte Liste durchführen und totalItems=0 erwarten.

Das Löschen eines Datensatzes bewahrt die Prozesshistorie nicht. Wenn die Daten für ein Audit wichtig sind, speichern Sie die erforderlichen Informationen vor dem DELETE im Quellsystem.

Anforderungen - Fehler, Limits und sichere Reihenfolge

Fehler verwenden das Format Problem Details. Speichern Sie status, code und requestId in Logs, aber niemals das Client Secret oder vollständige Header:

Lesen Sie X-RateLimit-Limit und X-RateLimit-Remaining. Begrenzen Sie die Parallelität, cachen Sie Schema und Werte und verwenden Sie nach 429 einen Backoff. Eine sichere Reihenfolge ist: context, schema, Liste oder UUID-Abfrage, Erstellung mit Idempotency-Key, Speichern von UUID und ETag, Dateien oder Beziehungen, Änderung mit If-Match, Prüflesung und erst am Ende die Löschung. Das gleiche Muster kann in n8n verwendet werden, wenn die Zugangsdaten als Credential gespeichert und UUIDs, ETags und Idempotenzschlüssel zwischen den Nodes weitergegeben werden.