Bestätigungen in der Codenica API

Um mit Bestätigungen über die Codenica API zu arbeiten, erstellen Sie zuerst einen API-Schlüssel in den Codenica-Einstellungen. Wenn Sie noch keinen Schlüssel haben, öffnen Sie Codenica API - Einführung in einem neuen Tab. Dort werden die gemeinsame Schlüsselerstellung, die sichere Aufbewahrung des Secrets und die Authentifizierungsregeln erklärt.

Eine Bestätigung ist ein Prozessdatensatz, zu dem ein bestimmter Client eine Entscheidung treffen soll. Eine Integration kann die Daten vorbereiten, den Client zuweisen, Dokumente, Assets, Notizen und Dateien anhängen und anschließend die Entscheidung im passenden Client-Kontext ausführen lassen.

Der technische Name eines Datensatzes lautet confirmation, die Sammlung in der API heißt confirmations. Eine normale Bearbeitung ändert den beschreibenden Teil des Datensatzes. Schreiben Sie das Ergebnis nicht direkt in status - bestätigen oder verwerfen Sie eine Bestätigung über den eigenen Endpunkt /decision.

Die Beispiele verwenden PUBLIC-API-CONFIRMATION-20260908-0001. Ersetzen Sie diese Kennung durch eine Referenz Ihrer Integration und die Werte in geschweiften Klammern durch Daten aus Ihrer Datenbank.

Bestätigungen - API-Adresse und Installationsart

Alle Routen für Bestätigungen beginnen mit:

{BASE_URL}/api/v1/confirmations

BASE_URL ist die Adresse des Codenica-Servers ohne den Suffix /api/v1. Verwenden Sie in Codenica Cloud die Domain oder Subdomain, die dem jeweiligen Unternehmen zugewiesen ist:

export BASE_URL="https://{unternehmen-domain}"

Bei der standardmäßigen On-Premise-Installation registriert Codenica Discovery folgende lokale Adresse:

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

Wenn der Administrator die Installation unter einer Unternehmensdomain, über HTTPS, hinter einem Reverse Proxy oder an einem anderen Port bereitstellt, verwenden Sie die für diese Installation mitgeteilte genaue Adresse:

export BASE_URL="https://{tatsaechliche-installationsadresse}"

Verwenden Sie localhost nur, wenn Integration und API auf demselben Computer laufen. Das Beispiel http://localhost:5050 gehört zu einer lokalen Entwicklungsumgebung und ist nicht die Standardadresse für On-Premise. Senden Sie tenantId weder im Body noch in der Query-Zeichenfolge. Die Zieldatenbank wird anhand des Request-Hosts ausgewählt.

Bestätigungen - Berechtigungsbereiche des API-Schlüssels

Der für Bestätigungen verwendete Schlüssel sollte nur die Berechtigungsbereiche enthalten, die die Integration tatsächlich benötigt. Der vollständige Satz für dieses Modul lautet:

confirmations:read
confirmations:write
confirmations:delete
confirmations:schema
confirmations:stats
confirmations:relationships:read
confirmations:relationships:write
confirmations:users:read
confirmations:files:read
confirmations:files:write
confirmations:technical:read
confirmations:technical:write
confirmations:pin:write
confirmations:decision:write
users:read

Für Listen und Datensätze benötigen Sie confirmations:read. Das Erstellen und die normale Bearbeitung erfordern confirmations:write, das Löschen confirmations:delete. Ergänzen Sie die Bereiche für Beziehungen, Dateien, Statistiken, technische Felder, das Anheften und Entscheidungen nur, wenn die Integration diese Vorgänge ausführt.

Wenn die Integration Beziehungsziele aus einer anderen Sammlung auswählt, braucht sie außerdem den passenden Lesebereich, zum Beispiel assets:read, documents:read, clients:read oder notes:read. Die Bereiche des Schlüssels ersetzen nicht die Berechtigungen des Benutzers, dem der Schlüssel zugeordnet ist.

Bestätigungen - 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 die erste Anfrage:

export PUBLIC_API_CLIENT_ID="cna_example"
export PUBLIC_API_CLIENT_SECRET="cns_example"

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

Eine externe Integration benötigt weder das Bearer-JWT des Administrators noch Cookies aus dem Codenica-Panel. Speichern Sie das Client Secret serverseitig in einem Secrets Vault. Legen Sie es nicht in Browsercode, Repositories, URLs, der Befehlshistorie oder Logs ab. Außerhalb der lokalen Entwicklung sollten Sie HTTPS verwenden.

Speichern Sie meta.requestId aus den Antworten. Damit lässt sich eine Anfrage in den Logs finden; die ID ersetzt jedoch nicht die UUID der Bestätigung und ist kein Secret.

Bestätigungen - Verbindungskontext prüfen

Lesen Sie den Kontext, bevor Sie zum ersten Mal schreiben. So prüfen Sie, ob die Adresse zur richtigen Datenbank führt und der Schlüssel die erforderlichen Berechtigungsbereiche und Limits besitzt:

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"

Prüfen Sie unter anderem data.apiVersion, data.contractVersion, die Daten in data.tenant, den Wert api_key in data.caller.authentication, die Rolle und clientId des Aufrufers, das Vorhandensein von confirmations in data.capabilities.resources sowie die Berechtigungsbereiche und Limits.

{
  "data": {
    "caller": {
      "role": "Administrator",
      "authentication": "api_key",
      "scopes": [
        "confirmations:read",
        "confirmations:write",
        "confirmations:decision:write"
      ]
    },
    "capabilities": {
      "supportsETag": true,
      "supportsIdempotency": true,
      "supportsRelationships": true,
      "supportsFiles": true
    }
  },
  "meta": { "requestId": "{REQUEST_ID}" }
}

Wenn der Kontext das falsche Unternehmen ausweist oder ein erforderlicher Bereich fehlt, korrigieren Sie die Adresse oder den Schlüssel. Versuchen Sie nicht, durch eine fremde Kennung eine andere Datenbank auszuwählen.

Bestätigungen - Schema und Beziehungsziele

Das Schema ist die maßgebliche Quelle für die aktuellen Felder, ihre Typen, Änderbarkeit und zulässigen 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/confirmations/schema"

Die Antwort enthält unter anderem data.itemType, data.fields und data.relationshipTargets. In diesem Modul ist itemType immer confirmation. Prüfen Sie für jedes Feld readable, writable, required, technical, unique und maxLength.

{
  "data": {
    "itemType": "confirmation",
    "fields": [
      { "name": "customId", "type": "string", "writable": true },
      { "name": "status", "type": "string", "writable": false },
      { "name": "pin", "type": "integer", "writable": false }
    ],
    "relationshipTargets": [
      { "targetDataSet": "assets" },
      { "targetDataSet": "clients", "targetItemType": "client" },
      { "targetDataSet": "documents", "targetItemType": "document" },
      { "targetDataSet": "notes", "targetItemType": "note" }
    ]
  }
}

Für assets schreibt das Schema keinen einzelnen Objekttyp vor. Wenn ein Ziel itemType=computer besitzt, senden Sie in der Beziehungsanfrage computer, statt automatisch asset anzunehmen. Erstellen Sie das Mapping nicht nur anhand eines Beispiels - lesen Sie vor dem Start der Integration das aktuelle Schema.

Bestätigungen - Geschäfts- und Prozessfelder

Die wichtigsten Felder, die Sie in attributes senden können, sind:

Feld
Typ
Verwendung
customId
string
Kennung aus der Integrationsanwendung
location, department
string
Ort und Abteilung der Anfrage
tag, link
string
Kennzeichnungen und Link zur Quelle der Anfrage
info, description
string
Zusatzinformationen und Beschreibung dessen, was bestätigt werden soll
type, category
string
Prozesstyp und Kategorie
status, dateConfirmed, dateDeclined, dateEnd, remark, pin
nur lesen
Entscheidungsergebnis, Entscheidungskommentar und Anheften

Wichtige Maximallängen sind unter anderem: customId 500, location 300, department 300, tag 2000, link 2000, info 10000, type 300, category 300 und description 10000 Zeichen. Das aktuelle Schema der Datenbank hat Vorrang.

Schreiben Sie status, dateConfirmed, dateDeclined, dateEnd, remark oder pin nicht über einen normalen PATCH. Senden Sie auch keine Auditfelder:

creator
updater
dateCreated
dateUpdated
importId
importSource
dateImported

Bestätigungen - verfügbare Endpunkte

Die wichtigsten Routen des Moduls confirmations sind:

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

Lesevorgänge erfordern Lesebereiche, jede Mutation zusätzlich den für den Vorgang vorgesehenen Bereich. Jede Anfrage, die Daten ändert, benötigt Idempotency-Key; eine Operation an einem bestehenden Datensatz benötigt außerdem den aktuellen If-Match-Wert.

Bestätigungen - Listen und Paginierung

Lesen Sie Bestätigungen seitenweise. Sie können den festen Wert itemType=confirmation mitsenden, obwohl die API diesen Typ für das gesamte Modul verwendet:

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/confirmations?itemType=confirmation&page=1&pageSize=25"

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

{
  "data": {
    "items": [
      {
        "id": "{CONFIRMATION_ID}",
        "itemType": "confirmation",
        "attributes": {
          "customId": "ERP-CONFIRMATION-2026-0042",
          "category": "Beschaffung",
          "status": "Pending"
        },
        "meta": { "etag": "{ETAG}" }
      }
    ],
    "page": 1,
    "pageSize": 25,
    "totalItems": 1,
    "totalPages": 1,
    "hasNextPage": false
  },
  "meta": { "requestId": "{REQUEST_ID}" }
}

Wechseln Sie anhand von hasNextPage zur nächsten Seite. Lesen Sie die maximale Seitengröße aus data.capabilities.limits.maxPageSize, statt sie fest zu codieren.

Bestätigungen - Suche und Filter

Mit search suchen Sie Text in beschreibenden Feldern. Für die Synchronisierung sind eine stabile customId oder eine UUID in der Regel besser geeignet:

curl --silent --show-error -G \
  --data-urlencode "search=beschaffung" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=20" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/confirmations"

Feldfilter können in einer Anfrage kombiniert werden:

curl --silent --show-error -G \
  --data-urlencode "status=Pending" \
  --data-urlencode "category=Beschaffung" \
  --data-urlencode "customId=ERP-CONFIRMATION-2026-0042" \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/confirmations"

Für eine genauere Filterung verwenden Sie die strukturierte Form field:operator:value:

category:eq:Beschaffung
status:ne:Declined
description:contains:Monitor
customId:startswith:ERP-CONFIRMATION-
link:notempty:

Nützliche Operatoren sind unter anderem eq, ne, contains, startswith, endswith und notempty. URL-codieren Sie Werte mit Leerzeichen, Doppelpunkten oder Sonderzeichen.

Bestätigungen - Feldauswahl und eingeschlossene Daten

Der Parameter fields begrenzt die Attribute in der Antwort. Fordern Sie bei der Listensynchronisierung nur die Felder an, die die Integration benötigt:

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/confirmations?fields=id,customId,status,category&page=1&pageSize=20"

Wenn Dateien, Beziehungen und der erstellende Benutzer in derselben Antwort enthalten sein sollen, verwenden Sie include:

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/confirmations/{CONFIRMATION_ID}?fields=%2A&include=files%2Crelationships%2Cusers"

Das Einschließen von Dateien erfordert confirmations:files:read, von Beziehungen confirmations:relationships:read und von Benutzern confirmations:users:read. Halten Sie fields und include möglichst klein, wenn der vollständige Datensatz nicht benötigt wird.

Bestätigungen - Statistiken und Feldwerte

Der Endpunkt stats unterstützt eine Zusammenfassung der sichtbaren Bestätigungen, während values Werte für Filterfelder liefert:

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/confirmations/stats?field=category&limit=20"
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/confirmations/values?field=category&search=bes&limit=20"

Beide Endpunkte sind schreibgeschützt und erfordern confirmations:stats. Die Ergebnisse enthalten nur Datensätze, die für den dem Schlüssel zugeordneten Benutzer sichtbar sind, und benötigen keinen ETag. Prüfen Sie den maximalen Wert von limit im aktuellen API-Vertrag.

Bestätigungen - Datensatz erstellen und Client zuweisen

Eine Bestätigung, zu der eine Entscheidung erforderlich ist, sollte auf einen geschäftlichen Client verweisen. Gemeint ist der Client-Datensatz in der Datenbank, nicht die technische AppUser-Identität für die Anmeldung:

{
  "targetId": "{CLIENT_ID}",
  "targetDataSet": "clients",
  "targetItemType": "client"
}

Der minimale Payload enthält den festen Wert itemType, die beschreibenden attributes und die Beziehung zum Client:

{
  "itemType": "confirmation",
  "attributes": {
    "customId": "ERP-CONFIRMATION-2026-0042",
    "category": "Beschaffung",
    "description": "Bestätigung eines Workstation-Kaufs."
  },
  "relationships": [
    {
      "targetId": "{CLIENT_ID}",
      "targetDataSet": "clients",
      "targetItemType": "client"
    }
  ]
}

Die Zuweisung kann bereits beim Erstellen mitgesendet werden. Fügen Sie dieser Beziehung kein relationshipType hinzu.

Bestätigungen - vollständiges Beispiel für die Erstellung

Speichern Sie den Body bei einer größeren Integration in einer Datei. So können Sie die identische Anfrage nach einem vorübergehenden Verbindungsfehler sicher wiederholen:

{
  "itemType": "confirmation",
  "attributes": {
    "customId": "PUBLIC-API-CONFIRMATION-20260908-0001",
    "location": "Berlin",
    "department": "IT",
    "tag": "integration,beschaffung,bestaetigung",
    "link": "https://erp.example.com/requests/0001",
    "info": "Anfrage aus dem Beschaffungssystem erhalten.",
    "type": "Hardwarekauf",
    "category": "Beschaffung",
    "description": "Bestätigung des Kaufs einer neuen Workstation für die IT-Abteilung."
  },
  "relationships": [
    {
      "targetId": "{CLIENT_ID}",
      "targetDataSet": "clients",
      "targetItemType": "client"
    }
  ]
}
curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: erp-confirmation-create-0001" \
  --data-binary @confirmation-create.json \
  "$BASE_URL/api/v1/confirmations"

Eine erfolgreiche Erstellung liefert 201 Created. Die Antwort enthält die UUID, itemType, Attribute, Datumsmetadaten, ETag und requestId. Speichern Sie UUID und ETag, weil die folgenden Schritte sie benötigen.

Bestätigungen - Idempotency-Key und sichere Wiederholungen

Jede Anfrage, die über einen API-Schlüssel Daten ändert, benötigt einen eigenen Idempotency-Key. Wenn die Verbindung nach dem Senden abbricht, wiederholen Sie exakt dieselbe Anfrage mit demselben Schlüssel:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: erp-confirmation-create-0001" \
  --data-binary @confirmation-create.json \
  "$BASE_URL/api/v1/confirmations"

Die Wiederholung einer identischen Anfrage mit demselben Schlüssel darf keine zweite Bestätigung erzeugen. Verwenden Sie einen Schlüssel nicht für unterschiedliche Bodies oder Vorgänge. Ein Idempotenzschlüssel steht für genau einen Geschäftsvorgang.

Erstellung:  Idempotency-Key = erp-confirmation-create-0001
Wiederholung: Idempotency-Key = erp-confirmation-create-0001
Neue Bearbeitung: Idempotency-Key = erp-confirmation-update-0001

Verwenden Sie eigene Schlüssel für PATCH, Anheften, Entscheidungen, Beziehungen, Dateien und das Löschen. Speichern Sie nach jeder erfolgreichen Änderung den vom Vorgang zurückgegebenen ETag.

Bestätigungen - einen Datensatz lesen

Nach der Erstellung oder sobald Sie die UUID erhalten haben, können Sie den vollständigen Datensatz abrufen:

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/confirmations/{CONFIRMATION_ID}?fields=%2A"

Speichern Sie den ETag aus dem HTTP-Header ETag oder aus data.meta.etag. Bewahren Sie für die Diagnose außerdem meta.requestId auf.

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/confirmations/{CONFIRMATION_ID}?fields=%2A&include=files%2Crelationships%2Cusers"

Mit include sehen Sie den zugewiesenen Client, Objektbeziehungen, den Requester und Dateien in einem Lesevorgang. Wenn Sie nur Synchronisierungsdaten benötigen, begrenzen Sie die Antwort mit fields.

Bestätigungen - mit dem aktuellen ETag bearbeiten

Eine sichere Bearbeitung folgt immer dieser Reihenfolge: Datensatz lesen, aktuellen ETag übernehmen, einen kleinen PATCH vorbereiten, If-Match und einen neuen Idempotency-Key senden und anschließend den neuen ETag speichern:

{
  "attributes": {
    "info": "Nach der Prüfung im Beschaffungssystem ergänzte Informationen.",
    "category": "IT-Beschaffung",
    "description": "Durch die Integration aktualisierte Bestätigung."
  }
}
curl --fail-with-body --silent --show-error \
  --request PATCH \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {CURRENT_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-update-0001" \
  --data-binary @confirmation-update.json \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}"

Bei Erfolg erhalten Sie 200 OK und einen neuen ETag. Ein normaler PATCH darf beschreibende Felder ändern, aber nicht status, Entscheidungsdaten, dateEnd, remark oder pin.

Bestätigungen - Schutz vor gleichzeitigen Änderungen

Wenn Sie If-Match weglassen, lehnt die API die Änderung ab:

HTTP 428 Precondition Required
code: if_match_required

Wenn Sie einen älteren ETag als die aktuelle Datensatzversion senden, erhalten Sie:

HTTP 412 Precondition Failed
code: if_match_failed

Lesen Sie den Datensatz nach einem 412 erneut, vergleichen Sie seine Werte mit der geplanten Änderung und senden Sie erst dann einen neuen PATCH. Wiederholen Sie nicht in einer Schleife dieselbe Anfrage mit einem alten ETag.

Versuchen Sie nicht, die Versionsprüfung zu umgehen, indem Sie Prozessfelder im Body senden:

{
  "attributes": {
    "status": "Confirmed",
    "dateConfirmed": "2026-09-08T10:30:00Z"
  }
}

Verwenden Sie den eigenen Endpunkt /decision. So kann das System den richtigen Client, den aktuellen Prozessstatus und die gleichzeitige Bearbeitung prüfen.

Bestätigungen - Anheften und Loslösen

Das Anheften ist ein eigener Vorgang und gehört nicht zu einem normalen PATCH. Zulässig sind null oder eine Zahl von 0 bis 3:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {CURRENT_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-pin-0001" \
  --data '{"pin":3}' \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/pin"

Zum Loslösen senden Sie null:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {PINNED_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-unpin-0001" \
  --data '{"pin":null}' \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/pin"

Beide Vorgänge erfordern confirmations:pin:write. Lesen Sie nach jedem Vorgang den neuen ETag und prüfen Sie den Wert von pin.

Bestätigungen - Entscheidung des Client

Eine Entscheidung ist eine geschäftliche Aktion und keine gewöhnliche Bearbeitung des Datensatzes. Vor der Entscheidung muss die Bestätigung einem Client zugewiesen sein. Die Anfrage muss von einem Schlüssel kommen, der diesen Client repräsentiert, und confirmations:decision:write enthalten. Die API prüft außerdem den aktuellen ETag.

Für eine Bestätigung senden Sie diesen Payload:

{
  "confirmed": true,
  "remark": "Ich bestätige, dass die Anfrage ausgeführt werden kann."
}
curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_DECISION_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_DECISION_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {DECISION_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-decision-0001" \
  --data '{"confirmed":true,"remark":"Ich bestätige, dass die Anfrage ausgeführt werden kann."}' \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/decision"

Zum Ablehnen verwenden Sie dieselbe Route mit false:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_DECISION_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_DECISION_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {DECISION_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-decision-0002" \
  --data '{"confirmed":false,"remark":"Ich lehne die Anfrage ab."}' \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/decision"

Nach einer positiven Entscheidung wird der Status Confirmed gesetzt und das System schreibt dateConfirmed, dateEnd und den Kommentar. Nach einer negativen Entscheidung lautet der Status Declined; geschrieben werden dateDeclined, dateEnd und der Kommentar. Setzen Sie diese Felder nicht manuell.

Bestätigungen - Client und requester

Die Client-Beziehung bezeichnet den geschäftlichen Client, der die Entscheidung treffen soll. Sie ist nicht die technische AppUser-Kennung. Lesen Sie die Zuweisung zusammen mit den Objektbeziehungen oder über einen einzelnen Datensatz mit include=relationships.

Die API stellt außerdem eine eigene, schreibgeschützte Benutzersammlung bereit. Sie enthält den automatischen Requester, also den Benutzer, der die Bestätigung erstellt hat:

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/confirmations/{CONFIRMATION_ID}/user-relationships?relationshipType=requester&page=1&pageSize=20"
{
  "targetId": "{REQUESTER_USER_ID}",
  "targetDataSet": "users",
  "relationshipType": "requester",
  "displayName": "{REQUESTER_NAME}",
  "email": "{REQUESTER_EMAIL}",
  "role": "{REQUESTER_ROLE}"
}

Der Requester wird vom System festgelegt. Setzen Sie diese Beziehung nicht in attributes und ändern Sie sie nicht über die Endpunkte für Objektbeziehungen. Zum Lesen benötigen Sie confirmations:users:read.

Bestätigungen - zulässige Objektbeziehungen

Der aktuelle Katalog der Beziehungsziele für Bestätigungen umfasst vier Sammlungen:

Sammlung
itemType
Bedeutung
assets
dynamisch, zum Beispiel computer
verknüpftes Asset
clients
client
Client, der die Entscheidung trifft
documents
document oder der vom Ziel gelieferte Typ
Dokument zur Anfrage
notes
note
Notiz zur Entscheidung

Jedes Ziel muss existieren, für den dem Schlüssel zugeordneten Benutzer sichtbar sein und mit der vom Schema gelieferten Liste relationshipTargets übereinstimmen. Bestätigungen unterstützen aus diesem Katalog keine beliebigen weiteren Sammlungen.

Bestätigungen - Format normaler Beziehungen und Client-Zuweisung

Eine Beziehung zu einem Asset, Dokument oder einer Notiz enthält relationshipType. Beispiel für ein Dokument:

{
  "targetId": "{DOCUMENT_ID}",
  "targetDataSet": "documents",
  "targetItemType": "invoice",
  "relationshipType": "related"
}

Die Client-Zuweisung ist die Ausnahme. Sie enthält targetDataSet=clients und targetItemType=client, aber kein relationshipType:

{
  "targetId": "{CLIENT_ID}",
  "targetDataSet": "clients",
  "targetItemType": "client"
}

Lesen Sie bei Assets den tatsächlichen Objekttyp und senden Sie ihn genau in targetItemType:

assets     - targetItemType: computer
documents  - targetItemType: invoice
notes      - targetItemType: note

Die genannten Werte sind Beispiele. Der richtige Typ kann in Ihrer Datenbank anders lauten.

Bestätigungen - Beziehung hinzufügen, lesen und entfernen

Fügen Sie eine einzelne Beziehung mit einem POST hinzu, der das Beziehungsobjekt ohne zusätzliche Hülle enthält:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {CURRENT_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-relation-add-0001" \
  --data '{"targetId":"{DOCUMENT_ID}","targetDataSet":"documents","targetItemType":"invoice","relationshipType":"related"}' \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/relationships"

Lesen Sie die Beziehungen als Sammlung:

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/confirmations/{CONFIRMATION_ID}/relationships?targetDataSet=documents&relationshipType=related&page=1&pageSize=50"

Zum Entfernen einer Beziehung benötigen Sie den aktuellen ETag der Bestätigung. Setzen Sie Sammlung und Ziel-UUID in den Pfad und den Beziehungstyp in die Query:

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: {CURRENT_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-relation-delete-0001" \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/relationships/documents/{DOCUMENT_ID}?relationshipType=related"

Hinzufügen und Entfernen liefern eine neue Datensatzversion oder data=true. Lesen Sie nach jeder erfolgreichen Änderung den neuen ETag.

Bestätigungen - mehrere Beziehungen ändern

Um mehrere Beziehungen in einer Anfrage hinzuzufügen oder zu entfernen, verwenden Sie relationships:batch. Der Body enthält die Arrays add und remove:

{
  "add": [
    {
      "targetId": "{ASSET_ID}",
      "targetDataSet": "assets",
      "targetItemType": "computer",
      "relationshipType": "related"
    }
  ],
  "remove": [
    {
      "targetId": "{NOTE_ID}",
      "targetDataSet": "notes",
      "targetItemType": "note",
      "relationshipType": "related"
    }
  ]
}
curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "If-Match: {CURRENT_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-relationships-batch-0001" \
  --data-binary @confirmation-relationships-batch.json \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/relationships:batch"

Die Antwort enthält die Zähler added, removed und skipped. Das Limit des Beziehungs-Batches kommt aus dem Kontext, der aktuelle ETag ist erforderlich und die Version der Bestätigung ändert sich. Für die Client-Zuweisung verwenden Sie das Format ohne relationshipType.

Bestätigungen - Dateiliste und Upload

Lesen Sie zunächst die Dateien, die der Bestätigung aktuell zugeordnet sind:

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/confirmations/{CONFIRMATION_ID}/files?page=1&pageSize=50"

Ein Listenelement enthält unter anderem id, fileName, contentType, size, relationshipType, isMain und downloadUrl. Fügen Sie eine neue Datei als multipart/form-data hinzu:

curl --fail-with-body --silent --show-error \
  --request POST \
  --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-confirmation-file-upload-0001" \
  --form "[email protected];type=application/pdf" \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/files?relationshipType=decision-form"
{
  "data": {
    "id": "{FILE_ID}",
    "fileName": "entscheidungsformular.pdf",
    "contentType": "application/pdf",
    "size": 48231,
    "relationshipType": "decision-form",
    "isMain": false,
    "downloadUrl": "/api/v1/confirmations/{CONFIRMATION_ID}/files/{FILE_ID}/content"
  }
}

Der Upload erfordert confirmations:files:write, den aktuellen ETag und einen neuen Idempotenzschlüssel. Lesen Sie das Größenlimit aus data.capabilities.limits.maxUploadBytes. Die API für Bestätigungen bietet keine Funktion zur Auswahl einer Hauptdatei - bauen Sie keine Integration, die einen /main-Endpunkt erwartet.

Bestätigungen - Dateien herunterladen, verknüpfen und entfernen

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

curl --fail-with-body --silent --show-error \
  --output heruntergeladenes-entscheidungsformular.pdf \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/files/{FILE_ID}/content"

Wenn die Datei bereits in Codenica gespeichert ist, können Sie sie einer zweiten Bestätigung zuordnen, ohne den Inhalt erneut hochzuladen:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "If-Match: {SECOND_CONFIRMATION_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-file-attach-0001" \
  "$BASE_URL/api/v1/confirmations/{SECOND_CONFIRMATION_ID}/files/{FILE_ID}?relationshipType=reference"

Zum Lösen einer Datei von einer Bestätigung oder zum Entfernen ihrer letzten Beziehung verwenden Sie dieselbe DELETE-Route:

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: {CONFIRMATION_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-file-delete-0001" \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}/files/{FILE_ID}"

Attach erstellt eine Beziehung zu einer vorhandenen Datei. Wenn die Datei noch der Quellbestätigung zugeordnet ist, darf das Lösen von einem zweiten Datensatz die Quellbeziehung nicht entfernen. Lesen Sie vor dem Löschen der letzten Beziehung die Dateiliste und prüfen Sie das ausgewählte Element.

Bestätigungen - Batch-Vorgänge

Der Endpunkt /api/v1/confirmations:batch verbindet das Erstellen, Bearbeiten und Löschen von Datensätzen. Das Format verwendet ein Array items sowie getrennte Objekte create und update:

{
  "items": [
    {
      "operation": "create",
      "create": {
        "itemType": "confirmation",
        "attributes": {
          "customId": "ERP-BATCH-CONFIRMATION-A",
          "category": "Zugriffe",
          "description": "Erste Bestätigung, die in einem Batch erstellt wird."
        },
        "relationships": [
          {
            "targetId": "{CLIENT_ID}",
            "targetDataSet": "clients",
            "targetItemType": "client"
          }
        ]
      }
    },
    {
      "operation": "update",
      "id": "{EXISTING_ID}",
      "ifMatch": "{EXISTING_ETAG}",
      "update": {
        "attributes": {
          "description": "Beschreibung in einem Batch-Vorgang aktualisiert."
        }
      }
    },
    {
      "operation": "delete",
      "id": "{RECORD_TO_DELETE_ID}",
      "ifMatch": "{RECORD_TO_DELETE_ETAG}"
    }
  ]
}
curl --fail-with-body --silent --show-error \
  --request POST \
  --header "X-Codenica-Client-Id: $PUBLIC_API_CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $PUBLIC_API_CLIENT_SECRET" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: erp-confirmations-batch-0001" \
  --data-binary @confirmations-batch.json \
  "$BASE_URL/api/v1/confirmations:batch"
{
  "data": {
    "items": [
      {
        "index": 0,
        "operation": "create",
        "status": 201,
        "id": "{CREATED_ID}",
        "data": { "meta": { "etag": "{CREATED_ETAG}" } }
      }
    ],
    "succeeded": 1,
    "failed": 0
  }
}

Jedes Update- und Delete-Element benötigt seinen eigenen aktuellen ifMatch-Wert. Ein Batch ist keine Alles-oder-nichts-Transaktion. Bei einem Teilergebnis kann die API 207 Multi-Status zurückgeben. Prüfen Sie daher jedes Element einzeln und wiederholen Sie keine Vorgänge, die bereits erfolgreich waren.

Bestätigungen - einen Datensatz löschen

Lesen Sie den Datensatz vor dem Löschen erneut, prüfen Sie UUID und aktuellen ETag und senden Sie die Anfrage anschließend mit einem eigenen Idempotenzschlüssel:

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: {CURRENT_ETAG}" \
  --header "Idempotency-Key: erp-confirmation-delete-0001" \
  "$BASE_URL/api/v1/confirmations/{CONFIRMATION_ID}"

Eine erfolgreiche Antwort liefert 200 OK und data=true. Prüfen Sie nach dem Löschen, dass die UUID 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/confirmations/{CONFIRMATION_ID}"

Das erwartete Ergebnis ist 404 Not Found mit dem Code confirmation_not_found. Das Löschen einer Bestätigung löscht zugehörige Dokumente, Assets oder Notizen nicht automatisch.

Bestätigungen - Fehler, Limits und sicherer Ablauf

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

HTTP
Code
Reaktion
400
validation_failed
Korrigieren Sie Body, Parameter oder Feldwert.
401
authentication_required oder authentication_failed
Prüfen Sie Adresse und beide Header.
403
confirmation_client_required
Die Entscheidung muss vom Client getroffen werden, der der Bestätigung zugewiesen ist.
404
confirmation_not_found
Der Datensatz existiert nicht oder ist nicht sichtbar.
409
confirmation_unique_constraint oder confirmation_concurrency_conflict
Lesen Sie den Datensatz erneut, prüfen Sie den ETag oder entfernen Sie das Duplikat.
412 / 428
if_match_failed, if_match_required
Lesen Sie den aktuellen ETag und wiederholen Sie den Vorgang kontrolliert.
422
confirmation_decision_rejected, confirmation_pin_rejected
Prüfen Sie Prozessstatus, Client-Schlüssel und Operationsregeln.
429
rate_limit_exceeded
Verwenden Sie einen ansteigenden Backoff und lesen Sie Retry-After.

Lesen Sie X-RateLimit-Limit und X-RateLimit-Remaining. Cachen Sie Schema und Feldwerte, begrenzen Sie die Parallelität und verwenden Sie nach 429 einen Backoff.

Ein sicherer Ablauf ist: context, schema, Client auswählen, Liste oder Datensatz lesen, mit Idempotency-Key erstellen, UUID und ETag speichern, Beziehungen oder Dateien hinzufügen, mit If-Match bearbeiten, anheften, über /decision entscheiden, durch erneutes Lesen prüfen und erst danach löschen. Dasselbe lässt sich in n8n abbilden, indem UUID, ETag und Idempotenzschlüssel zwischen den Schritten weitergegeben werden.