Kunden und Mitarbeiter in der Codenica API

Der technische Name dieser Ressource in der Public API ist clients, der von der API zurückgegebene Typ lautet client. In dieser Sammlung können Sie Kundendaten und Mitarbeiterdaten verwalten - abhängig von Rolle, Typ und den Informationen in Ihrer Datenbank. Die Anfragen verwenden eine gemeinsame Ressource; die Unterscheidung ergibt sich aus den Feldwerten des Datensatzes.

Erstellen Sie vor Ihrer ersten Anfrage den Schlüssel aus dem Artikel Codenica API - Einführung. Die folgenden Abschnitte zeigen den vollständigen Ablauf: Schema und Listen prüfen, Datensätze erstellen und aktualisieren sowie Beziehungen, Dateien, Batch-Operationen und das Löschen eines Datensatzes verwalten.

  • Kunden- und Mitarbeiterlisten mit Seitennavigation, Sortierung und Filtern lesen;
  • nur die für die Integration benötigten Felder abrufen;
  • Datensätze erstellen und Kontakt- oder Organisationsdaten teilweise aktualisieren;
  • Änderungen mit ETag und If-Match schützen;
  • Operationen mit Idempotency-Key sicher wiederholen;
  • Datensätze mit Assets, Dokumenten, Tickets und anderen unterstützten Objekten verknüpfen;
  • Dateien hochladen, herunterladen, anhängen und löschen;
  • Statistiken und Feldwerte lesen und Batch-Operationen verwenden.

Pflichtfelder und verfügbare Werte können von der Konfiguration Ihrer Datenbank abhängen. Lesen Sie vor dem Schreiben das aktuelle Schema des verwendeten Datentyps.

Kunden und Mitarbeiter - API-Adresse und Installationsauswahl

Senden Sie Anfragen an die öffentliche Adresse, unter der Ihre Codenica-Installation erreichbar ist. Verwenden Sie nicht die Adresse der Datenbank selbst, eines Containers oder eines Ports, der nur innerhalb des Servers erreichbar ist. Die Pfade für Kunden und Mitarbeiter beginnen mit:

{BASE_URL}/api/v1/clients

Verwenden Sie in Codenica Cloud die Ihrer Installation zugewiesene Domain:

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

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

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

Wenn der Administrator die On-Premise-Installation über eine Unternehmensdomain, einen Reverse Proxy, HTTPS oder einen anderen externen Port veröffentlicht hat, verwenden Sie die für diese Installation mitgeteilte genaue Adresse:

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

Die richtige Datenbank wird anhand der Hostadresse ausgewählt. Versuchen Sie nicht, sie mit tenantId, einem zusätzlichen Query-String-Feld oder einem Wert im Body auszuwählen. Verwenden Sie localhost nicht, wenn das Integrationsprogramm auf einem anderen Computer als die API ausgeführt wird. Verwenden Sie in der Produktion HTTPS, wenn die Installation mit einem Zertifikat veröffentlicht ist.

BASE_URL darf das abschließende /api/v1 nicht enthalten:

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

# Standardmäßiges On-Premise mit Codenica Discovery:
# export BASE_URL="http://codenica.local:5150"

# On-Premise mit eigener Domain oder Reverse Proxy:
# export BASE_URL="https://api.ihr-unternehmen.example"

Kunden und Mitarbeiter - API-Schlüssel und Zugriffs-Scopes

Erstellen Sie den Schlüssel für eine externe Integration in Codenica unter Einstellungen - API - API Keys. Verwenden Sie einen Namen, der Anwendung, Umgebung und Zweck erkennen lässt, zum Beispiel CRM Produktion - Kunden. Wählen Sie anschließend nur die für diese Integration erforderlichen Scopes aus und speichern Sie die angezeigte Client ID sowie das Client Secret einmalig in einem sicheren Secret-Speicher.

Der vollständige Ablauf für Kunden und Mitarbeiter in diesem Artikel benötigt die folgenden Scopes:

  • clients:read, clients:write und clients:delete - Datensätze lesen, erstellen, aktualisieren und löschen;
  • clients:schema - Feldschema und Beziehungsziele;
  • clients:stats - Statistiken und Feldwerte;
  • clients:relationships:read und clients:relationships:write - Beziehungen lesen und ändern;
  • clients:files:read und clients:files:write - Dateien verwalten.

Wenn die Integration Datensätze mit einem anderen Objekt verknüpft, benötigt sie zusätzlich den Lesebereich für dieses Ziel, zum Beispiel assets:read für vorhandene Assets. Der Scope für Kundenbeziehungen ersetzt nicht die Berechtigung zum Lesen des Zielobjekts.

Für eine reine Leseintegration reichen normalerweise:

clients:read
clients:schema

Die Limits für aktive Schlüssel hängen von der Lizenz ab:

Lizenz
Public API
Aktive Schlüssel
Starter
nicht verfügbar
0
Plus
verfügbar
50
Enterprise
verfügbar
100

Im API-Bereich werden erstellte Schlüssel angezeigt und können rotiert oder gelöscht werden. Ein gelöschter Schlüssel kann keine Anfragen mehr authentifizieren und wird nicht als aktiv gezählt. Das Client Secret wird nur bei der Erstellung oder Rotation angezeigt. Speichern Sie es nicht in einem Repository, einer URL, Protokollen, der Befehlshistorie oder in Code, der im Browser ausgeführt wird.

Kunden und Mitarbeiter - Authentifizierungsheader

Die externe Anwendung sendet Server-zu-Server-Anfragen mit zwei Headern:

export CLIENT_ID="cna_ihre_client_id"
export CLIENT_SECRET="cns_ihr_client_secret"

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

Verwenden Sie in der Integration weder das Bearer-JWT des Administrators noch eine Panel-Sitzung. Das JWT dient zur Anmeldung eines Benutzers an Codenica, während der API-Schlüssel eine externe Anwendung mit der ausgewählten Datenbank verbindet. Verwenden Sie außerhalb einer Testumgebung HTTPS.

Anfragen, die Daten ändern, benötigen zusätzlich einen eindeutigen Header:

Idempotency-Key: public-api-clients-create-20260905104704

Fügen Sie nach dem Lesen eines Datensatzes dessen aktuellen ETag an eine Anfrage an, die Daten ändert:

If-Match: "aktueller-kunden-etag"

Erzeugen Sie beim Wiederholen derselben Anfrage keinen neuen Idempotency-Key. Mit demselben Schlüssel und einem identischen Body lässt sich das Ergebnis einer möglicherweise mit Timeout beendeten Operation sicher erneut abrufen.

Kunden und Mitarbeiter - Installationskontext prüfen

Lesen Sie vor dem Start der Synchronisierung den Kontext:

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 apiVersion, contractVersion, die Datenbankkennung, tenant.resolvedDomain, caller.authentication mit dem Wert api_key, die erforderlichen Scopes und clients in capabilities.resources. Lesen Sie außerdem die Limits für Seiten, Uploads und Anfragen.

Im abgeschlossenen Testlauf bestätigte der Kontext unter anderem clients:read, clients:write, clients:delete, clients:schema, clients:stats, die Beziehungs- und Dateiscopes sowie die Unterstützung für Batch-Operationen, Beziehungen, Dateien, ETags und Idempotenz.

Bewahren Sie meta.requestId auf. Wenn der Kontext auf die falsche Installation verweist oder ein Scope fehlt, stoppen Sie die Synchronisierung und korrigieren Sie Adresse oder Schlüssel. Versuchen Sie nicht, die Datenbank im Body der Anfrage zu wechseln.

Kunden und Mitarbeiter - Feldschema und Datentypen

Das Schema zeigt, welche Felder gelesen und geschrieben werden können und welche Werte in Ihrer Datenbank akzeptiert werden:

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

In der Antwort hat data.itemType den Wert client. Im aktuellen Schema sind die folgenden Felder erforderlich; die E-Mail-Adresse ist eindeutig:

Feld
Typ
Erforderlich
Eindeutig
Beispielbedeutung
firstName
string
ja
nein
Vorname oder erster Namensteil
lastName
string
ja
nein
Nachname oder zweiter Namensteil
email
string
ja
ja
Kontaktadresse

Häufig verwendete optionale Felder sind:

customId, displayName, gender, position, category, contractType,
type, role, status, phone, phoneWork, phoneMobile, address, country,
city, state, zipCode, location, department, section, roomNumber, tag,
link, number, value, isLicensed, isVerified, comments, description,
notification, preferredLanguage

Prüfen Sie vor der Verwendung eines zusätzlichen Feldes im Schema dessen Eigenschaften readable, writable, Typ und Längenlimit. Gehen Sie nicht davon aus, dass die Werte von status, type, category oder role in jeder Installation identisch sind. Für die Erstellung eines Clients ist itemType im Body nicht erforderlich - die API gibt client zurück.

Das Schema bestätigt außerdem die folgenden Beziehungsziele: assets, documents, tickets, notes, worktasks, confirmations und requesteditems. Im aktuellen Schema ist clients kein Ziel einer Client-zu-Client-Beziehung.

Kunden und Mitarbeiter - Endpoint-Übersicht

Die folgende Übersicht enthält die wichtigsten Operationen. Ersetzen Sie die Werte in geschweiften Klammern durch die in den API-Antworten erhaltenen Identifikatoren.

  • GET /api/v1/clients - Liste;
  • GET /api/v1/clients/schema - Feld- und Beziehungsschema;
  • GET /api/v1/clients/stats - Statistiken;
  • GET /api/v1/clients/values - Feldwerte;
  • GET /api/v1/clients/{id} - einzelner Datensatz;
  • POST /api/v1/clients - Erstellung;
  • PATCH /api/v1/clients/{id} - teilweise Aktualisierung;
  • DELETE /api/v1/clients/{id} - Löschung;
  • POST /api/v1/clients:batch - Erstellungs-, Aktualisierungs- und Löschoperationen;
  • GET /api/v1/clients/{id}/relationships - Beziehungsliste;
  • POST /api/v1/clients/{id}/relationships - Beziehung hinzufügen;
  • POST /api/v1/clients/{id}/relationships:batch - Beziehungen gesammelt ändern;
  • DELETE /api/v1/clients/{id}/relationships/{targetDataSet}/{targetId} - Beziehung löschen;
  • GET /api/v1/clients/{id}/files - Dateiliste;
  • POST /api/v1/clients/{id}/files - Upload;
  • POST /api/v1/clients/{id}/files/{fileId} - vorhandene Datei anhängen;
  • PUT /api/v1/clients/{id}/files/{fileId}/main - Hauptdatei festlegen;
  • DELETE /api/v1/clients/{id}/files/{fileId} - Datei löschen oder Zuordnung entfernen;
  • GET /api/v1/clients/{id}/files/{fileId}/content - Dateiinhalt herunterladen.

Eine Antwort 403 bedeutet normalerweise, dass dem Schlüssel ein Scope fehlt oder der dem Schlüssel zugeordnete Benutzer nicht über die erforderliche Berechtigung verfügt.

Kunden und Mitarbeiter - Listen und Seitennavigation

Lesen Sie die Liste seitenweise. Dieses Beispiel gibt die ersten zwanzig Datensätze zurück:

curl --request GET --url "$BASE_URL/api/v1/clients?page=1&pageSize=20&sort=displayName&direction=asc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort der Sammlung enthält items, page, pageSize, totalItems, totalPages und hasNextPage. Fahren Sie fort, solange hasNextPage den Wert true hat. Wenn die Reihenfolge für die Synchronisierung wichtig ist, legen Sie die Sortierung immer ausdrücklich fest.

Lesen Sie das Limit für pageSize aus dem Kontext. Gehen Sie nicht davon aus, dass die erste Seite alle Datensätze enthält oder die Standardsortierung unverändert bleibt.

Kunden und Mitarbeiter - Suche und Filter

Das Testbeispiel sucht einen Datensatz nach eigener Kennung, Status und Datentyp:

curl --request GET --url "$BASE_URL/api/v1/clients?customId=PUBLIC-API-CLI-20260905104704-SOURCE&status=Active&sort=customId&direction=asc&page=1&pageSize=10" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Abhängig vom Schema können Sie unter anderem die Parameter ids, search, firstName, lastName, displayName, email, status, category, type, role, location, department, customId, tag, createdAfter, createdBefore, updatedAfter und updatedBefore verwenden.

Für genaue Bedingungen verwenden Sie filter:

filter=status:eq:Active
filter=displayName:contains:Public
filter=category:in:Customer,Employee
filter=description:notEmpty:

Zu den Operatoren gehören eq, ne, in, contains, startsWith, endsWith, empty, notEmpty, gt, gte, lt und lte. Codieren Sie Werte mit Leerzeichen oder Sonderzeichen entsprechend den URL-Regeln.

Kunden und Mitarbeiter - Felder auswählen und Daten einschließen

Der Parameter fields begrenzt die Antwort auf die benötigten Felder:

curl --request GET --url "$BASE_URL/api/v1/clients?fields=id,itemType,customId,displayName,email,status,department" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Verwenden Sie include, um Dateien und Beziehungen zusammen mit dem Datensatz zu lesen:

curl --request GET --url "$BASE_URL/api/v1/clients/$CLIENT_RECORD_ID?fields=customId,displayName,email,status,description&include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Im Test enthielt die Antwort die angeforderten Felder sowie die Sammlungen files und relationships. Der Lesezugriff auf eingeschlossene Daten muss separat gewährt werden. Das Fehlen von clients:files:read oder clients:relationships:read kann nicht mit fields=* umgangen werden.

Kunden und Mitarbeiter - Datensatz erstellen

Verwenden Sie POST /api/v1/clients, um einen Datensatz zu erstellen. Schreiben Sie die beschreibbaren Felder in attributes. Das folgende Beispiel zeigt ein vollständiges Kunden- oder Mitarbeiterprofil aus einem CRM-System:

export IDEMPOTENCY_KEY="public-api-clients-create-source-20260905104704"

curl --request POST --url "$BASE_URL/api/v1/clients" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-raw '{
    "attributes": {
      "customId": "PUBLIC-API-CLI-20260905104704-SOURCE",
      "firstName": "Public API",
      "lastName": "Client source 20260905104704",
      "displayName": "Public API client source 20260905104704",
      "email": "[email protected]",
      "category": "Customer",
      "type": "External",
      "role": "Customer",
      "status": "Active",
      "preferredLanguage": "de",
      "phone": "+49 600 000 001",
      "department": "Customer Service",
      "description": "Source client used by the complete Public API Clients flow."
    }
  }'

Für diese Ressource ist itemType im Body nicht erforderlich. Die API gibt itemType: client selbst zurück. Im getesteten Schema waren firstName, lastName und eine eindeutige email erforderlich. Ihre Datenbank kann zusätzliche Felder oder andere Werte verlangen.

Eine erfolgreiche Antwort hat den Status 201 Created. Speichern Sie data.id, den ETag aus dem HTTP-Header und data.meta.etag. Mit customId lässt sich der Datensatz später im externen System leichter wiederfinden.

Kunden und Mitarbeiter - Erstellung sicher wiederholen

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

curl --request POST --url "$BASE_URL/api/v1/clients" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-clients-create-source-20260905104704" \
  --data-raw '{
    "attributes": {
      "customId": "PUBLIC-API-CLI-20260905104704-SOURCE",
      "firstName": "Public API",
      "lastName": "Client source 20260905104704",
      "displayName": "Public API client source 20260905104704",
      "email": "[email protected]",
      "category": "Customer",
      "type": "External",
      "role": "Customer",
      "status": "Active",
      "preferredLanguage": "de",
      "phone": "+49 600 000 001",
      "department": "Customer Service",
      "description": "Source client used by the complete Public API Clients flow."
    }
  }'

Im abgeschlossenen Test gab die zweite identische Anfrage dieselbe Datensatzkennung und denselben ETag zurück. Es wurde kein zweiter Client erstellt. Eine Änderung des Bodys oder die Verwendung desselben Schlüssels für eine andere Operation ist keine Wiederholung - erstellen Sie für eine neue Operation einen neuen Schlüssel.

Kunden und Mitarbeiter - Datensatz lesen und teilweise aktualisieren

Bewahren Sie die UUID des Datensatzes nach der Erstellung auf. Ein einzelnes Profil lesen Sie so:

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

PATCH ändert nur die gesendeten Felder. Dieses Beispiel aktualisiert den Anzeigenamen und die Beschreibung:

curl --request PATCH --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-update-source-20260905104704" \
  --data-raw '{
    "attributes": {
      "displayName": "Public API client source updated",
      "description": "Updated through the Codenica Public API Clients flow."
    }
  }'

Eine erfolgreiche Aktualisierung gibt 200 OK und einen neuen ETag zurück. Ersetzen Sie den alten ETag nach jeder Änderung durch den neuen. Auch Beziehungs- und Dateioperationen können die Version des Datensatzes ändern. Lesen Sie deshalb vor der nächsten Mutation den aktuellen ETag erneut.

Kunden und Mitarbeiter - Änderungen vor dem Überschreiben schützen

Wenn eine andere Operation den Datensatz ändert, nachdem die Integration seinen ETag gelesen hat, wird der alte Wert von If-Match abgelehnt:

HTTP/1.1 412 Precondition Failed
{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "The supplied ETag is not the current client version.",
  "instance": "/api/v1/clients/{clientId}",
  "code": "if_match_failed",
  "requestId": "request-id-from-response"
}

Überschreiben Sie den Datensatz nach diesem Fehler nicht ohne Prüfung. Lesen Sie den Client erneut, vergleichen Sie die Änderungen und erstellen Sie erst dann einen neuen PATCH mit dem aktuellen ETag. Wenn If-Match bei einer Operation zur Versionskontrolle fehlt, wird Folgendes zurückgegeben:

HTTP/1.1 428 Precondition Required

{
  "code": "if_match_required",
  "status": 428,
  "detail": "Send the ETag returned by GET in the If-Match header."
}

Kunden und Mitarbeiter - verfügbare Beziehungsziele

Das aktuelle Schema nennt die folgenden Ziel-Datensätze:

  • assets - Assets, zum Beispiel computer;
  • documents - der vom Schema zurückgegebene Dokumenttyp;
  • tickets - der vom Schema zurückgegebene Tickettyp;
  • notes - der vom Schema zurückgegebene Notiztyp;
  • worktasks - der vom Schema zurückgegebene Aufgabentyp;
  • confirmations - der vom Schema zurückgegebene Bestätigungstyp;
  • requesteditems - der vom Schema zurückgegebene Anforderungstyp.

targetItemType muss dem tatsächlichen Typ des Ziels entsprechen. Im abgeschlossenen Test wurden zwei vorhandene Assets vom Typ computer dynamisch ausgewählt. Wenn die Beziehung auf Assets verweist, muss der Schlüssel außerdem assets:read enthalten. Für andere Ziele verwenden Sie den entsprechenden Lesescope.

Im aktuellen Schema ist clients kein Ziel einer Client-zu-Client-Beziehung. Erstellen Sie Beziehungen nur zu Objekten, die in der aktuellen Schemaantwort aufgeführt sind.

Kunden und Mitarbeiter - Beziehungen hinzufügen und lesen

Dieses Beispiel verknüpft den Datensatz mit einem vorhandenen Asset. Der Beziehungs-Body enthält die Zielkennung, den Zieldatensatz, den Typ und die Beziehungsart:

{
  "targetId": "635d6518-1ac0-496a-abb7-95636b1b19b9",
  "targetDataSet": "assets",
  "targetItemType": "computer",
  "relationshipType": "related"
}
curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/relationships" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-relationship-add-20260905104704" \
  --data @client-relationship.json

Ein erfolgreicher Add-Vorgang gibt 201 Created und Zieldetails zurück, darunter targetId, targetDataSet, targetItemType, relationshipType, customId und name. Die Beziehungssammlung lesen Sie so:

curl --request GET --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/relationships?targetDataSet=assets&targetItemType=computer&relationshipType=related&page=1&pageSize=50" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort verwendet dasselbe Seitenmodell wie die Kundenliste. Nach einer im Test hinzugefügten Beziehung betrug totalItems den Wert 1.

Kunden und Mitarbeiter - Batch-Beziehungen und einzelnes Entfernen

Verwenden Sie relationships:batch, um mehrere Änderungen in einer Operation auszuführen:

{
  "add": [
    {
      "targetId": "5ddc5b5a-5bdc-46f9-ab7e-5ad8f6775b3a",
      "targetDataSet": "assets",
      "targetItemType": "computer",
      "relationshipType": "related"
    }
  ],
  "remove": []
}
curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/relationships:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-relationship-batch-20260905104704" \
  --data @client-relationship-batch.json

Die Antwort enthält die Zähler added, removed und skipped. Lesen Sie nach dem Batch den neuen ETag des Clients.

Entfernen Sie eine einzelne Beziehung mit:

curl --request DELETE --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/relationships/assets/635d6518-1ac0-496a-abb7-95636b1b19b9?relationshipType=related" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-relationship-remove-20260905104704"

Bei Erfolg kommt 200 OK mit data: true. Nach dem Entfernen der letzten Beziehung sollte die Sammlung totalItems: 0 zurückgeben.

Kunden und Mitarbeiter - Dateiliste und Upload

Dateien werden getrennt von den Feldern des Datensatzes verwaltet. Ein neuer Client hat zunächst eine leere Sammlung:

curl --request GET --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/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. Das folgende Beispiel erstellt eine primäre Dokumentationsdatei:

curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files?makeMain=true&relationshipType=documentation" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-upload-primary-20260905104704" \
  --form "[email protected];type=text/plain"

Die Antwort enthält unter anderem id, fileName, contentType, size, relationshipType, isMain und eine relative downloadUrl. Die Testdatei clients-primary.txt war 62 Byte groß. Prüfen Sie nach dem Upload die Dateiliste, da sie den endgültigen Status von isMain zeigt.

Kunden und Mitarbeiter - Datei herunterladen und Hauptdatei wechseln

Laden Sie den Dateiinhalt über den Endpoint content herunter. Verwenden Sie eine binäre Ausgabe:

curl --request GET --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output clients-primary.downloaded.txt

Eine zweite Datei können Sie mit makeMain=false hochladen:

curl --request POST --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files?makeMain=false&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-upload-secondary-20260905104704" \
  --form "[email protected];type=text/plain"

Um sie zur Hauptdatei zu machen:

curl --request PUT --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files/$SECONDARY_FILE_ID/main" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-set-main-20260905104704"

Die Operation gibt data: true zurück. Danach hat die erste Datei isMain: false und die zweite isMain: true. Der ETag des Datensatzes ändert sich. Lesen Sie ihn daher vor der nächsten Mutation erneut.

Kunden und Mitarbeiter - vorhandene Datei anhängen

Wenn eine Datei bereits bei einem Client gespeichert ist, können Sie sie ohne erneuten Upload an einen anderen Datensatz anhängen:

owner client: 8844622a-f948-4f2a-a718-81f61fa5ab21
target client: 3569dead-82b1-439e-8ecd-e4ee6b5f886b
file: cd60b8ce-1a97-47a9-b9fc-b1abe8b4dee4
curl --request POST --url "$BASE_URL/api/v1/clients/3569dead-82b1-439e-8ecd-e4ee6b5f886b/files/cd60b8ce-1a97-47a9-b9fc-b1abe8b4dee4?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-attach-existing-20260905104704"

Prüfen Sie isMain in der Dateiliste des Ziel-Clients, nicht nur in der direkten Attach-Antwort. Entfernen Sie die Zuordnung mit:

curl --request DELETE --url "$BASE_URL/api/v1/clients/3569dead-82b1-439e-8ecd-e4ee6b5f886b/files/cd60b8ce-1a97-47a9-b9fc-b1abe8b4dee4" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-detach-20260905104704"

Das Entfernen der Zuordnung nimmt die Datei beim Ziel-Client weg, löscht sie aber nicht beim Besitzer-Client.

Kunden und Mitarbeiter - Datei löschen

Lesen Sie vor dem Löschen einer Datei eine aktuelle Liste und den ETag des Datensatzes. Wenn Sie die aktuelle Hauptdatei löschen, kann das System automatisch eine andere Datei als Hauptdatei auswählen:

curl --request DELETE --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE/files/$FILE_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-file-delete-20260905104704"

Aktualisieren Sie nach der Antwort 200 den ETag und prüfen Sie die Liste. Das Löschen der letzten Datei löscht nicht den Kunden- oder Mitarbeiterdatensatz, sondern hinterlässt eine leere Dateisammlung. Wenn die Datei nur an den Datensatz angehängt war, entfernen Sie die Zuordnung und erwägen Sie erst danach, die Datei am Speicherort zu löschen.

Kunden und Mitarbeiter - Statistiken und Feldwerte

Statistiken zeigen die Verteilung der Daten. Der Endpoint values liefert Werte, die für den Aufbau von Filtern nützlich sind:

curl --request GET --url "$BASE_URL/api/v1/clients/stats?field=status&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

curl --request GET --url "$BASE_URL/api/v1/clients/values?field=status&search=Act&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Statistik im Test enthielt unter anderem die Statuswerte aktywny, Active, w magazynie und Urlop płatny. Ein gemischtes Ergebnis ist möglich, wenn die Daten aus unterschiedlichen Quellen stammen. Gehen Sie nicht davon aus, dass Statuswerte nur auf Deutsch oder nur in einer Sprache vorliegen.

Beispielantwort von values:

{
  "data": {
    "field": "status",
    "values": ["Active"]
  },
  "meta": {
    "requestId": "request-id-from-response"
  }
}

Statistiken und Werte ändern keine Daten. Verwenden Sie values, um Filter und Vorschläge aufzubauen, statt Wertelisten fest im Integrationscode zu hinterlegen.

Kunden und Mitarbeiter - Batch-Erstellung

Mit einem Batch können Sie mehrere Datensätze in einer Anfrage erstellen. Ein Erstellungselement enthält operation: create sowie ein create-Objekt mit attributes:

{
  "items": [
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "PUBLIC-API-CLI-20260905104704-BATCH-A",
          "firstName": "Public API",
          "lastName": "Clients batch A 20260905104704",
          "displayName": "Public API clients batch A 20260905104704",
          "email": "[email protected]",
          "category": "Customer",
          "role": "Customer",
          "status": "Active",
          "description": "Client created by the Public API batch flow."
        }
      }
    },
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "PUBLIC-API-CLI-20260905104704-BATCH-B",
          "firstName": "Public API",
          "lastName": "Clients batch B 20260905104704",
          "displayName": "Public API clients batch B 20260905104704",
          "email": "[email protected]",
          "category": "Employee",
          "role": "Employee",
          "status": "Active"
        }
      }
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/clients:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-clients-batch-create-20260905104704" \
  --data @clients-batch-create.json

Im abgeschlossenen Test hatte die Antwort 200 OK, succeeded: 2, failed: 0 und zwei Elemente mit dem Operationsstatus 201. Speichern Sie jede neue UUID und jeden ETag getrennt.

Kunden und Mitarbeiter - Batch-Aktualisierung und Teilerfolg

Eine Aktualisierung benötigt id, den aktuellen Wert ifMatch und ein update-Objekt. Das folgende Beispiel enthält auch ein ungültiges Element, um eine teilweise Antwort zu erklären:

{
  "items": [
    {
      "operation": "update",
      "id": "942f8323-bb7b-4915-80a9-81eaae657cb8",
      "ifMatch": "\"3drgMRaLiRYP6p6nCd6JDh_UHVRhYIAwWFDO4YLOUvc\"",
      "update": {
        "attributes": {
          "displayName": "Public API client batch A updated",
          "description": "Updated inside a partial Clients batch."
        }
      }
    },
    {
      "operation": "invalid"
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/clients:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-clients-batch-partial-20260905104704" \
  --data @clients-batch-partial.json

Im Test war die Antwort 207 Multi-Status:

{
  "data": {
    "succeeded": 1,
    "failed": 1,
    "items": [
      {"operation": "update", "status": 200},
      {
        "operation": "invalid",
        "status": 400,
        "error": {"code": "invalid_batch_item"}
      }
    ]
  }
}

207 bedeutet keinen vollständigen Fehlschlag. Prüfen Sie das Ergebnis jeder Operation einzeln und denken Sie bei einer delete-Operation an ein eigenes ifMatch:

{
  "operation": "delete",
  "id": "4db45845-ddec-4740-bb4b-f3c57836d3b5",
  "ifMatch": "\"NAHxuB2XecVkevWAbNdCeT6aQkwyyYHc_TDtgLvfI_U\""
}

Kunden und Mitarbeiter - Datensatz löschen

Das Löschen eines Profils ist über die API nicht rückgängig zu machen. Lesen Sie zuerst den aktuellen ETag:

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

Senden Sie anschließend DELETE:

curl --request DELETE --url "$BASE_URL/api/v1/clients/$CLIENT_ID_VALUE" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-clients-delete-source-20260905104704"

Bei Erfolg kommen 200 OK und data: true. Ein späterer Leseversuch gibt 404 Not Found mit dem Code client_not_found zurück. Eine Filterung nach dem Präfix PUBLIC-API-CLI-20260905104704 sollte totalItems: 0 ergeben.

Kunden und Mitarbeiter - Fehler, Limits und Sicherheit

Fehler werden im Format Problem Details zurückgegeben. Die wichtigsten Felder sind status, code, detail und requestId. Richten Sie die Anwendungslogik am stabilen Feld code aus.

  • 400 - ungültige Felder, ungültiger Zieltyp oder ungültiges Batch-Element;
  • 401 - fehlende oder ungültige Zugangsdaten;
  • 403 - fehlender Scope oder fehlende Berechtigung;
  • 404 - Datensatz, Datei oder Ziel nicht vorhanden oder nicht sichtbar;
  • 409 - Datenkonflikt, zum Beispiel eine bereits verwendete eindeutige E-Mail-Adresse;
  • 412 - veralteter ETag;
  • 413 - Datei überschreitet das Limit;
  • 422 - fachlicher Validierungsfehler;
  • 428 - If-Match oder Idempotency-Key fehlt;
  • 429 - Anfrage-Limit überschritten;
  • 503 - Dienst vorübergehend nicht verfügbar;
  • 207 - Batch teilweise ausgeführt.

Lesen Sie X-RateLimit-Limit und X-RateLimit-Remaining. Verwenden Sie bei 429 den zurückgegebenen Wert Retry-After und erhöhen Sie die Wartezeit bei weiteren Versuchen. Protokollieren Sie weder X-Codenica-Client-Secret noch Secrets oder vertrauliche Dateiinhalte.

Kunden und Mitarbeiter - vollständiger Integrationsablauf

  1. Setzen Sie BASE_URL auf die tatsächliche Codenica-Cloud- oder On-Premise-Adresse.
  2. Erstellen Sie unter Einstellungen - API - API Keys einen Schlüssel, wählen Sie die minimalen Scopes und speichern Sie das Secret in einem Zugangsdaten-Speicher.
  3. Lesen Sie /api/v1/context und bestätigen Sie die richtige Datenbank, den Caller, die Scopes und die Limits.
  4. Lesen Sie /api/v1/clients/schema und prüfen Sie Pflichtfelder, Werte und Beziehungsziele.
  5. Senden Sie einen gefilterten GET mit einer eindeutigen customId, um ein Duplikat auszuschließen.
  6. Erstellen Sie den Kunden- oder Mitarbeiterdatensatz mit einem eindeutigen Idempotency-Key.
  7. Speichern Sie UUID und ETag aus der Antwort. Wenn die Antwort verloren geht, wiederholen Sie die identische Erstellung mit demselben Schlüssel.
  8. Lesen Sie das Profil mit fields und optional mit include=files,relationships.
  9. Ändern Sie Felder mit PATCH, dem aktuellen If-Match und einem neuen Idempotency-Key.
  10. Fügen Sie nur vom Schema erlaubte Beziehungen hinzu, lesen und entfernen Sie sie. Prüfen Sie targetItemType des Ziels.
  11. Verwalten Sie Dateien über die dafür vorgesehenen Endpoints. Achten Sie auf den aktuellen ETag und unterscheiden Sie das Anhängen vom Löschen einer Datei.
  12. Prüfen Sie nach jedem Upload, Anhängen, Wechsel der Hauptdatei und DELETE die Dateiliste.
  13. Verwenden Sie stats und values, um Filter und Wertelisten zu synchronisieren.
  14. Verwenden Sie für größere Mengen clients:batch und behandeln Sie sowohl 200 als auch 207.
  15. Lesen Sie vor dem Löschen den ETag, senden Sie DELETE und bestätigen Sie den Code client_not_found.

Die Beispiele in diesem Artikel stammen aus einem Ablauf mit dem Präfix PUBLIC-API-CLI-20260905104704. Ihre Integration muss die aus Ihrer Datenbank erhaltenen Identifikatoren verwenden, nicht die Demonstrationswerte.

context = GET /api/v1/context
schema = GET /api/v1/clients/schema

client = POST /api/v1/clients
  Idempotency-Key: unique-create-key

client = GET /api/v1/clients/{id}
etag = client.data.meta.etag

updated = PATCH /api/v1/clients/{id}
  If-Match: etag
  Idempotency-Key: unique-update-key

relationship = POST /api/v1/clients/{id}/relationships
  If-Match: updated-etag
  Idempotency-Key: unique-relationship-key

files = GET /api/v1/clients/{id}/files

deleted = DELETE /api/v1/clients/{id}
  If-Match: latest-etag
  Idempotency-Key: unique-delete-key