Lieferanten in der Codenica API

Der technische Ressourcenname in der Public API lautet vendors, der von der API zurückgegebene Typ vendor. Ein Lieferantendatensatz kann den Firmennamen, Kontaktdaten, Registrierungsangaben, den Status und eine Beschreibung der Geschäftsbeziehung enthalten.

Bevor Sie Ihre erste Anfrage senden, erstellen Sie den in Codenica API - Einführung beschriebenen Schlüssel. Der folgende Ablauf deckt alle Schritte ab: Schema und Listen prüfen, einen Lieferanten anlegen und ändern, die erlaubten Beziehungsziele verwalten, Dateien bearbeiten, Batch-Operationen ausführen und einen Datensatz löschen.

  • Lieferantenlisten mit Paginierung, Sortierung und Filtern lesen;
  • nur die für die Integration erforderlichen Felder anfordern;
  • Lieferantendatensätze anlegen und teilweise aktualisieren;
  • Änderungen mit ETag und If-Match schützen;
  • Schreibvorgänge mit Idempotency-Key sicher wiederholen;
  • die im Schema für Lieferanten ausgewiesenen Beziehungsziele verwenden;
  • Dateien hochladen, herunterladen, anhängen und löschen;
  • Statistiken und Feldwerte lesen und Batch-Operationen verarbeiten.

Pflichtfelder und zulässige Werte können von der Konfiguration Ihrer Datenbank abhängen. Lesen Sie vor dem Schreiben das aktuelle Schema.

Lieferanten - API-Adresse und Installationsart

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

{BASE_URL}/api/v1/vendors

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 registriert Codenica Discovery den Dienst lokal unter:

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 dafür mitgeteilte genaue Adresse:

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

Die Datenbank wird anhand der Hostadresse ausgewählt. Verwenden Sie dafür weder tenantId noch einen zusätzlichen Query-String-Parameter oder einen Wert im Request-Body. Verwenden Sie localhost nicht, wenn das Integrationsprogramm auf einem anderen Computer läuft.

BASE_URL darf nicht mit dem abschließenden /api/v1 enden:

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

# Standard-On-Premise mit Codenica Discovery:
# export BASE_URL="http://codenica.local:5150"

# On-Premise mit einer vom Administrator veröffentlichten Adresse:
# export BASE_URL="https://api.ihr-unternehmen.example"

Lieferanten - API-Schlüssel und Zugriffsbereiche

Erstellen Sie den Schlüssel für eine externe Integration in Codenica unter Einstellungen - API - API-Schlüssel. Wählen Sie einen Namen, der Anwendung, Umgebung und Zweck beschreibt, zum Beispiel Einkauf - Lieferanten - Produktion. Wählen Sie nur die für diese Integration erforderlichen Scopes aus und speichern Sie die angezeigte Kombination aus Client ID und Client Secret einmalig in einem sicheren Secret-Speicher.

Der vollständige Ablauf in diesem Artikel benötigt:

  • vendors:read, vendors:write und vendors:delete - Datensätze lesen, anlegen, ändern und löschen;
  • vendors:schema - Felder und Beziehungsziele;
  • vendors:stats - Statistiken und Feldwerte;
  • vendors:relationships:read und vendors:relationships:write - Beziehungen lesen und ändern;
  • vendors:files:read und vendors:files:write - Dateioperationen.

Wenn die Integration Dokumente oder ein anderes Beziehungsziel liest, fügen Sie auch dessen Leseberechtigung hinzu, zum Beispiel documents:read. Ein Beziehungsscope für Lieferanten ersetzt nicht den Zugriff auf das Zielobjekt.

Für eine Integration mit reinem Lesezugriff reichen normalerweise:

vendors:read
vendors:schema

Die Schlüsselgrenzen hängen von der Lizenz ab:

Lizenz
Public API
Maximale Anzahl an Schlüsseln
Starter
nicht verfügbar
0
Plus
verfügbar
50
Enterprise
verfügbar
100

Im API-Bereich werden die für Ihre Datenbank erstellten Schlüssel angezeigt. Ein eigener Schlüssel für jede Anwendung und Umgebung erleichtert die Zugriffskontrolle, die Rotation eines Secrets oder das Löschen einer einzelnen Integration, ohne andere zu unterbrechen. Ein gelöschter Schlüssel kann keine Anfragen mehr authentifizieren und wird nicht als aktiv gezählt.

Das Client Secret wird nur beim Erstellen oder Rotieren eines Schlüssels angezeigt. Speichern Sie es nicht in einem Repository, einer URL, Protokollen, der Befehlshistorie oder in browserseitigem Code.

Lieferanten - Authentifizierungs-Header

Die externe Anwendung sendet Server-zu-Server-Anfragen mit zwei Headern, die den Schlüssel identifizieren:

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

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

Senden Sie in diesem Szenario weder ein Administrator-JWT noch Sitzungscookies aus dem Panel. Die Integration verwendet den dieser Datenbank zugewiesenen API-Schlüssel. Eine Produktivinstallation sollte über HTTPS angesprochen werden.

Jede Änderung an Daten benötigt einen eindeutigen Header:

Idempotency-Key: public-api-vendors-create-20260905111218

Aktualisierungen, Löschungen, Beziehungsänderungen und Dateioperationen benötigen das aktuelle ETag des Datensatzes:

If-Match: "aktuelles-lieferanten-etag"

Speichern Sie nach jeder erfolgreichen Mutation das neue ETag aus dem Header und aus data.meta.etag. Bei der Wiederholung derselben logischen Operation müssen Idempotency-Key und Request-Body identisch bleiben.

Lieferanten - Installationskontext prüfen

Lesen Sie vor dem Start der Synchronisation 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 vendors in capabilities.resources. Lesen Sie außerdem die Grenzwerte für Seiten, Dateien, Batches und Anfragen.

Eine vollständige Integration sollte normalerweise supportsBatch, supportsRelationships, supportsFiles, supportsETag und supportsIdempotency ausweisen. Bewahren Sie meta.requestId aus jeder Antwort auf. Diese Kennung benötigen Sie bei der Fehleranalyse und beim Kontakt mit dem Administrator.

Wenn der Kontext auf eine andere Datenbank zeigt oder ein erforderlicher Scope fehlt, stoppen Sie die Synchronisation und korrigieren Sie Adresse oder Schlüssel. Versuchen Sie nicht, die Datenbank im Request-Body zu ändern.

Lieferanten - Feldschema und Beziehungsziele

Lesen Sie das Schema vor dem ersten Schreibvorgang:

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

In der Antwort ist data.itemType gleich vendor. Das Schema beschreibt den Feldtyp, die Lesbarkeit und Schreibbarkeit, die Pflichtangabe, die maximale Länge, die Eindeutigkeit und die automatische Erzeugung. Im aktuellen Schema ist name erforderlich und kann bis zu 300 Zeichen enthalten:

Feld
Typ
Erforderlich
Limit
Beispielbedeutung
name
string
ja
300
Name des Lieferanten

Häufig verwendete Felder lassen sich mehreren Gruppen zuordnen:

  • Identifikation: customId, name, displayName, type, category, role, status;
  • Standort: location, department, address, city, country, state, zipCode;
  • Kontakt: email, phone, phoneWork, phoneMobile, contactName, contactPhone, contactMobile, contactEmail;
  • Register und Kennzeichnungen: website, tag, taxId, idNumber, registryNumber, link, number;
  • Beschreibung und Status: comments, description, notification, value, isLicensed, isVerified.

Das Schema liefert außerdem den Katalog der Beziehungsziele. Im aktuellen Lieferantenmodell sind dies documents, notes, worktasks und requesteditems. Gehen Sie nicht davon aus, dass jede im Kontext sichtbare Ressource ein Beziehungsziel für Lieferanten ist.

Lieferanten - Übersicht der Endpunkte

Diese Übersicht ordnet die wichtigsten Operationen für Lieferantendatensätze. Ersetzen Sie Werte in geschweiften Klammern durch UUIDs aus früheren Antworten.

  • GET /api/v1/vendors - Liste;
  • GET /api/v1/vendors/schema - Feld- und Beziehungsschema;
  • GET /api/v1/vendors/stats - Statistiken;
  • GET /api/v1/vendors/values - Feldwerte;
  • GET /api/v1/vendors/{id} - einzelner Datensatz;
  • POST /api/v1/vendors - anlegen;
  • PATCH /api/v1/vendors/{id} - teilweise aktualisieren;
  • DELETE /api/v1/vendors/{id} - löschen;
  • POST /api/v1/vendors:batch - Anlegen, Aktualisieren und Löschen in einem Batch;
  • GET /api/v1/vendors/{id}/relationships - Beziehungsliste;
  • POST /api/v1/vendors/{id}/relationships - Beziehung hinzufügen;
  • POST /api/v1/vendors/{id}/relationships:batch - mehrere Beziehungen in einer Anfrage ändern;
  • DELETE /api/v1/vendors/{id}/relationships/{targetDataSet}/{targetId} - Beziehung entfernen;
  • GET /api/v1/vendors/{id}/files - Dateiliste;
  • POST /api/v1/vendors/{id}/files - hochladen;
  • POST /api/v1/vendors/{id}/files/{fileId} - vorhandene Datei anhängen;
  • PUT /api/v1/vendors/{id}/files/{fileId}/main - Hauptdatei festlegen;
  • DELETE /api/v1/vendors/{id}/files/{fileId} - Datei löschen;
  • GET /api/v1/vendors/{id}/files/{fileId}/content - Inhalt herunterladen.

Wenn ein Endpunkt 403 zurückgibt, prüfen Sie zuerst den dem Schlüssel zugewiesenen Scope und anschließend die Berechtigungen seines Eigentümers.

Lieferanten - Listen, Sortieren und Paginierung

Lesen Sie die Liste seitenweise. Dieses Beispiel liefert die ersten zwanzig Datensätze und sortiert sie nach dem Namen:

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

Die Collection-Hülle enthält items, page, pageSize, totalItems, totalPages und hasNextPage. Wenn hasNextPage den Wert true hat, lesen Sie die nächste Seite. Für reproduzierbare Synchronisationen legen Sie die Sortierung ausdrücklich fest.

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

Lieferanten - Suchen und Filtern

Nach dem Anlegen können Sie einen Datensatz über die eigene Kennung und den Status finden:

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

Für eine Textsuche verwenden Sie search:

curl --request GET --url "$BASE_URL/api/v1/vendors?search=technology&page=1&pageSize=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Je nach Schema können Sie unter anderem ids, search, name, displayName, email, status, category, type, role, location, department, customId, tag, createdAfter, createdBefore, updatedAfter und updatedBefore verwenden.

Für genauere Bedingungen verwenden Sie filter:

filter=status:eq:Active
filter=name:contains:Technology
filter=category:in:Technology,Hardware
filter=description:notEmpty:

Die Operatoren vergleichen Werte, suchen Textteile, wählen einen Wert aus mehreren Möglichkeiten und prüfen leere Felder. Kodieren Sie Leerzeichen und Sonderzeichen nach den URL-Regeln, bevor Sie den Filter senden.

Lieferanten - Felder auswählen und Daten einbeziehen

Mit fields begrenzen Sie die Antwort auf die für die Integration benötigten Eigenschaften:

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

Mit include lesen Sie Dateien und Beziehungen zusammen mit dem Datensatz:

curl --request GET --url "$BASE_URL/api/v1/vendors/a8156781-3b1c-4fa5-9cf2-05077e5d1399?fields=customId,displayName,email,status,description&include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Die Antwort kann die angeforderten Attribute sowie die Collections files und relationships enthalten. Der Zugriff auf einbezogene Daten muss separat erteilt werden. Das Fehlen von vendors:files:read oder vendors:relationships:read lässt sich nicht mit fields=* umgehen.

Lieferanten - Datensatz anlegen

Verwenden Sie zum Anlegen POST /api/v1/vendors. Schreibbare Eigenschaften gehören in attributes. Die minimale Anfrage benötigt name. In der Praxis sollten Sie zugleich die Kennung des Quellsystems und die wichtigsten Kontaktdaten übergeben:

{
  "attributes": {
    "customId": "ERP-VENDOR-2026-001",
    "name": "Northwind Technology Services",
    "displayName": "Northwind Technology Services",
    "email": "[email protected]",
    "category": "Technology",
    "type": "Supplier",
    "role": "Supplier",
    "status": "Active",
    "description": "Anbieter für IT-Infrastrukturdienste."
  }
}
curl --request POST --url "$BASE_URL/api/v1/vendors" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001" \
  --data @vendor-create.json

Eine erfolgreiche Antwort hat den Status 201 Created. Speichern Sie data.id, data.meta.etag und den HTTP-Header ETag. Im Demonstrationsdatensatz gab die API itemType: vendor und die Kennung a8156781-3b1c-4fa5-9cf2-05077e5d1399 zurück.

Lieferanten - Erstellungsanfrage sicher wiederholen

Wenn nach dem Senden ein Timeout auftritt oder die Antwort verloren geht, legen Sie nicht sofort einen zweiten Datensatz an. Wiederholen Sie exakt dieselbe Anfrage mit demselben Schlüssel:

Idempotency-Key: public-api-vendors-create-erp-vendor-2026-001

Der Request-Body muss identisch sein und der Schlüssel darf nur zu dieser einen logischen Operation gehören. Die Wiederholung mit demselben Schlüssel legt keinen zweiten Lieferanten an. Verwenden Sie ihn nicht für einen anderen Datensatz, eine Aktualisierung oder eine Löschung.

Idempotenz gilt für Mutationen. Jeder neue Schreibvorgang benötigt einen neuen, eindeutigen Schlüssel.

Lieferanten - einzelnen Datensatz lesen

Lesen Sie den angelegten oder gefundenen Datensatz über die von der API zurückgegebene UUID:

VENDOR_ID="a8156781-3b1c-4fa5-9cf2-05077e5d1399"

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

Eine Antwort mit 200 OK enthält data.itemType: vendor. Das aktuelle ETag steht im HTTP-Header und in data.meta.etag. Verwenden Sie die Kennung des Quellsystems nicht anstelle der UUID, außer Sie haben den Datensatz zuvor darüber gesucht.

Lieferanten - teilweise Aktualisierung mit ETag

Lesen Sie zuerst den Datensatz und verwenden Sie das zurückgegebene ETag. PATCH ändert nur die in attributes übermittelten Eigenschaften:

CURRENT_ETAG='"ao_LJiJqs-uhBu9oDENCFJH6JY8qwbl_vt77Gl5cjGQ"'

curl --request PATCH --url "$BASE_URL/api/v1/vendors/$VENDOR_ID" \
  --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-vendors-update-20260905111218" \
  --data '{"attributes":{"displayName":"Northwind Technology Services - Einkauf","description":"Lieferantendaten durch die Integration aktualisiert."}}'

Eine erfolgreiche Antwort hat den Status 200 OK. Senden Sie keine Eigenschaften, die Sie nicht ändern möchten. Ersetzen Sie nach dem Erfolg das gespeicherte ETag durch den neuen Wert, zum Beispiel "ek44P2KnmKSAB1xX4Ycs_NgIn0I3NLoDdqsezEUgBTY".

Lieferanten - Schutz vor dem Überschreiben von Änderungen

Wenn zwei Prozesse denselben Datensatz gelesen haben, kann der zweite bereits eine veraltete Version besitzen. Die Public API lehnt die Aktualisierung mit dem Code if_match_failed und dem Status 412 Precondition Failed ab:

{
  "type": "https://docs.codenica.com/errors/if_match_failed",
  "title": "Precondition failed.",
  "status": 412,
  "detail": "The supplied ETag is not the current vendor version.",
  "code": "if_match_failed"
}

Fehlt If-Match bei einer Aktualisierung oder Löschung, wird 428 Precondition Required mit dem Code if_match_required zurückgegeben. Lesen Sie nach 412 oder 428 den Datensatz erneut, prüfen Sie den aktuellen Zustand und entscheiden Sie erst dann über einen neuen Versuch. Senden Sie kein zufälliges ETag.

Lieferanten - eingeschränkter Beziehungskatalog

Nicht jedes im System verfügbare Objekt kann ein Beziehungsziel für Lieferanten sein. Maßgeblich ist relationshipTargets aus /api/v1/vendors/schema. Das aktuelle Modell stellt folgende Ziele bereit:

documents
notes
worktasks
requesteditems

Verknüpfen Sie Lieferanten nicht mit clients oder assets. Leiten Sie die Unterstützung einer Collection nicht daraus ab, dass sie in capabilities.resources erscheint. Die Ressourcenliste der Installation ist umfassender als die Beziehungsziele eines einzelnen Objekts.

Objektbeziehungen von Lieferanten verwenden relationshipType nicht. Senden Sie das Feld nicht im Request-Body und hängen Sie relationshipType=related nicht an die Query String an. Wenn ein Datei-Endpunkt relationshipType=documentation oder relationshipType=manual verwendet, handelt es sich um Dateimetadaten und nicht um eine Beziehung zu einem anderen Objekt.

Lieferanten - Beziehung hinzufügen und lesen

Lesen Sie vor einer Beziehungsänderung ein frisches ETag des Lieferantendatensatzes. Der Beziehungs-Body enthält Ziel, Collection und, wenn das Zielobjekt es verlangt, dessen targetItemType:

{
  "targetId": "31fe2881-6236-4100-9a87-2c018cbaf709",
  "targetDataSet": "documents",
  "targetItemType": "warranty"
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/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-vendors-relationship-document-a-20260905111218" \
  --data '{"targetId":"31fe2881-6236-4100-9a87-2c018cbaf709","targetDataSet":"documents","targetItemType":"warranty"}'

Eine erfolgreiche Hinzufügung gibt 201 Created zurück. Lesen Sie die Beziehungen separat:

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

Die Antwort enthält unter anderem targetId, targetDataSet, targetItemType, customId und status. Die Beziehungsliste enthält keinen Parameter relationshipType.

Lieferanten - Beziehungs-Batch und Entfernen einer Verknüpfung

Verwenden Sie relationships:batch, um mehrere Beziehungen in einer Anfrage hinzuzufügen oder zu entfernen:

{
  "add": [
    {
      "targetId": "31eed973-79cf-4650-ac0e-1e3ef5513d9f",
      "targetDataSet": "documents",
      "targetItemType": "warranty"
    }
  ],
  "remove": []
}
curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_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: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-batch-20260905111218" \
  --data @vendor-relationships-batch.json

Das Ergebnis enthält die Zähler added, removed und skipped. Entfernen Sie eine einzelne Beziehung mit:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/relationships/documents/31fe2881-6236-4100-9a87-2c018cbaf709" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-relationship-delete-20260905111218"

Fügen Sie relationshipType nicht hinzu. Lesen Sie die Collection danach erneut, um den Zustand zu bestätigen.

Lieferanten - Dateien auflisten

Dateien werden als eigene Collection am Lieferantendatensatz verwaltet:

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

Eine leere Collection enthält beispielsweise items: [], totalItems: 0 und hasNextPage: false. Lesen Sie die Collection nach jeder Dateioperation erneut, weil sie die tatsächlichen Werte für isMain, relationshipType, die Größe und die Downloadadresse zeigt.

Lieferanten - Datei hochladen

Lesen Sie vor dem Upload das aktuelle ETag des Lieferanten. Der Upload verwendet eine Multipart-Anfrage:

curl --request POST --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/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-vendors-file-upload-20260905111218" \
  --form "[email protected];type=text/plain"

Hier beschreibt relationshipType=documentation die Datei und keine Objektbeziehung. Die Antwort 201 Created enthält unter anderem die Datei-ID, den Namen, den Inhaltstyp, die Größe und downloadUrl. Prüfen Sie in der Liste, ob die Datei isMain: true hat.

Lesen Sie das Upload-Limit aus data.capabilities.limits.maxUploadBytes. In der Beispielinstallation betrug es 20971520 Bytes.

Lieferanten - Datei herunterladen und Hauptdatei wechseln

Laden Sie den Inhalt über downloadUrl oder den entsprechenden Endpunkt herunter:

FILE_ID="025222b9-abef-4bad-a2ba-28229a0d73fb"

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

Die Antwort sollte 200 OK, den richtigen Content-Type und den Header Content-Disposition enthalten. Um eine zweite Datei anzulegen, ohne die Hauptdatei zu ändern, verwenden Sie makeMain=false und beispielsweise relationshipType=manual. Legen Sie sie anschließend als Hauptdatei fest:

curl --request PUT --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124/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-vendors-file-set-main-20260905111218"

Nach dem erneuten Lesen der Liste hat die neue Datei isMain: true und die vorherige isMain: false.

Lieferanten - vorhandene Datei anhängen

Sie können eine Datei, die bei einem Lieferanten gespeichert ist, an einen anderen Datensatz anhängen, ohne den Inhalt erneut hochzuladen. Dies ist eine Dateioperation, daher ist relationshipType hier Dateimetadatum:

TARGET_VENDOR_ID="4bfece8f-5bb3-438c-a95b-f14ccf93cce3"
TARGET_ETAG='"l5sRayy308rVRi4PNmUReFFcJGowi0KZUi8-hOGGlr0"'

curl --request POST --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e?makeMain=true&relationshipType=manual" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-attach-20260905111218"

Das Trennen entfernt die Verbindung beim Ziel-Lieferanten, löscht die Datei aber nicht aus dem Datensatz ihres Eigentümers:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$TARGET_VENDOR_ID/files/2a1f9727-0990-405d-b22c-fbd93273cc6e" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $TARGET_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-detach-20260905111218"

Prüfen Sie nach dem Trennen die Dateiliste des Ziel-Lieferanten und des Eigentümers.

Lieferanten - Datei löschen

Auch das Löschen einer Datei erfordert das aktuelle ETag des Lieferantendatensatzes:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_ID/files/cc182dea-47d3-4ca2-818b-c639cde5a124" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: public-api-vendors-file-delete-20260905111218"

Wenn Sie die aktuelle Hauptdatei löschen, kann das System automatisch eine andere verbleibende Datei als Hauptdatei auswählen. Lesen Sie nach 200 OK die Liste erneut und prüfen Sie totalItems sowie isMain. Eine Datei zu trennen ist nicht dasselbe wie die Datei beim Eigentümer zu löschen.

Lieferanten - Statistiken und Feldwerte

Statistiken helfen Ihnen zu prüfen, wie die Daten auf die Lieferantendatensätze verteilt sind:

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

Das Ergebnis kann die Gesamtzahl der Datensätze, den Feldnamen und Werte mit Zählern enthalten. Die Werte stammen aus Ihrer Datenbank. active, Active und aktiver Lieferant können beispielsweise unterschiedliche Einträge sein, wenn sie aus verschiedenen Quellen stammen.

Verwenden Sie den Endpunkt values, um Filtervorschläge zu erstellen:

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

Statistiken und Feldwerte sind reine Leseoperationen und ändern keine Daten.

Lieferanten - Batch zum Anlegen

Mit einem Batch können Sie mehrere Lieferantendatensätze in einer Anfrage anlegen. Jedes Element enthält operation: create und ein create-Objekt:

{
  "items": [
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-A",
          "name": "Northwind Batch A",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    },
    {
      "operation": "create",
      "create": {
        "attributes": {
          "customId": "ERP-VENDOR-BATCH-B",
          "name": "Northwind Batch B",
          "email": "[email protected]",
          "category": "Technology",
          "type": "Supplier",
          "role": "Supplier",
          "status": "Active"
        }
      }
    }
  ]
}
curl --request POST --url "$BASE_URL/api/v1/vendors: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-vendors-batch-create-20260905111218" \
  --data @vendors-batch-create.json

Das Ergebnis enthält den Status der Gesamtanfrage und den Status jeder Operation in data.items. Ein erfolgreicher Batch kann 200 OK, succeeded: 2, failed: 0 und zwei Elemente mit Status 201 zurückgeben. Speichern Sie jede neue UUID und jedes ETag getrennt.

Lieferanten - Batch-Aktualisierung, Löschung und Teilerfolg

Eine Batch-Aktualisierung benötigt id, das aktuelle ifMatch und ein update-Objekt:

{
  "items": [
    {
      "operation": "update",
      "id": "76d1698d-dfdb-47a3-9d84-3e476fa7894c",
      "ifMatch": "ETAG_FROM_GET",
      "update": {
        "attributes": {
          "displayName": "Northwind Batch A - aktualisiert",
          "description": "Änderung durch die Batch-Operation für Lieferanten."
        }
      }
    },
    {
      "operation": "invalid"
    }
  ]
}

Wenn eine Operation erfolgreich ist und eine andere ungültig, gibt die API 207 Multi-Status zurück. Behandeln Sie 207 weder als vollständigen Fehlschlag noch als vollständigen Erfolg. Verarbeiten Sie jeden Eintrag in data.items separat. Für das Löschen gilt dieselbe Regel: Senden Sie Kennung und aktuelles ifMatch:

{
  "operation": "delete",
  "id": "9462d541-c405-44bf-9c75-000d8b862136",
  "ifMatch": "ETAG_FROM_GET"
}

Führen Sie nach einem Batch-Löschen einen Kontroll-GET aus. Der gelöschte Datensatz sollte 404 mit dem Code vendor_not_found zurückgeben.

Lieferanten - Datensatz löschen

Lesen Sie den Datensatz vor dem Löschen erneut, damit Sie ein aktuelles ETag besitzen:

curl --request DELETE --url "$BASE_URL/api/v1/vendors/$VENDOR_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-vendors-delete-20260905111218"

Eine erfolgreiche Löschung gibt 200 OK und data: true zurück. Ein späterer Lesezugriff gibt 404 Not Found mit dem Code vendor_not_found zurück. Sie können zusätzlich nach Ihrem customId filtern und totalItems: 0 bestätigen.

Wenn die DELETE-Antwort verloren ging, senden Sie nicht sofort eine neue Operation mit einem anderen Schlüssel. Verwenden Sie den ursprünglichen Idempotency-Key, prüfen Sie den Datensatz und entscheiden Sie erst danach über das weitere Vorgehen.

Lieferanten - Fehler, Limits und vollständiger Integrationsablauf

Fehler der Public API verwenden das Format Problem Details. Richten Sie die Anwendungslogik am stabilen Feld code aus und bewahren Sie requestId bei jeder Fehlermeldung auf.

  • 400 - ungültiges Feld, Beziehungsziel oder Batch-Element;
  • 401 - fehlende oder ungültige Anmeldedaten;
  • 403 - Scope oder Berechtigung fehlt;
  • 404 - Datensatz, Datei oder Ziel existiert nicht oder ist nicht sichtbar;
  • 409 - Daten- oder Eindeutigkeitskonflikt;
  • 412 - veraltetes ETag;
  • 413 - Datei überschreitet das Limit;
  • 422 - Fehler bei der fachlichen Validierung;
  • 428 - If-Match oder Idempotency-Key fehlt;
  • 429 - Anfragelimit überschritten;
  • 207 - Batch nur teilweise ausgeführt.

Lesen Sie X-RateLimit-Limit und X-RateLimit-Remaining. Verwenden Sie bei 429 den Header Retry-After, falls er zurückgegeben wird, und vergrößern Sie die Wartezeit zwischen Versuchen. Protokollieren Sie niemals X-Codenica-Client-Secret, Secrets oder vertrauliche Dateiinhalte.

Empfohlene Reihenfolge:

  1. Setzen Sie BASE_URL auf die richtige Installation.
  2. Erstellen Sie unter Einstellungen - API - API-Schlüssel einen Schlüssel mit den minimal erforderlichen Scopes.
  3. Lesen Sie /api/v1/context und /api/v1/vendors/schema.
  4. Legen Sie einen Lieferanten mit einem eindeutigen Idempotency-Key an und speichern Sie UUID und ETag.
  5. Lesen Sie Listen mit Paginierung, Filtern und optionalem include.
  6. Aktualisieren Sie den Datensatz nur mit dem aktuellen If-Match.
  7. Fügen Sie Beziehungen nur zu Schema-Zielen und ohne relationshipType hinzu.
  8. Verwenden Sie die eigenen Datei-Endpunkte und prüfen Sie die Dateiliste nach jeder Änderung.
  9. Prüfen Sie bei größeren Mengen das Ergebnis jeder Batch-Operation.
  10. Lesen Sie vor dem Löschen das aktuelle ETag und führen Sie danach einen Kontroll-GET aus.

Die Beispiele verwenden das Demonstrationspräfix PUBLIC-API-VEN-20260905111218. Ihre Integration muss die von Ihrer eigenen Datenbank zurückgegebenen Kennungen verwenden und nicht die Werte dieser Seite.