Dokumente in der Codenica API

Der technische Name dieses Objekts in der Public API ist documents. Ein Dokument kann eine Rechnung, Bestellung, einen Vertrag, ein Protokoll oder ein anderes Dokument aus Ihrer Datenbank darstellen. Die Beispiele verwenden einen Datensatz vom Typ invoice mit Rechnungsdaten aus einem externen System.

Erstellen Sie vor der 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, Beziehungen und Dateien verwalten, Batch-Operationen ausführen und einen Datensatz löschen.

  • Dokumentlisten mit Seitennavigation, Sortierung und Filtern lesen;
  • Rechnungsdaten und andere Dokumenttypen lesen;
  • Datensätze erstellen und teilweise aktualisieren;
  • Änderungen mit ETag und If-Match schützen;
  • Operationen mit Idempotency-Key sicher wiederholen;
  • Dokumente miteinander und mit anderen Objekten verknüpfen;
  • Dateien hochladen, herunterladen, anhängen und löschen;
  • Statistiken und Feldwerte lesen und Batch-Operationen ausführen.

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

Dokumente - API-Adresse und Bereitstellungsart

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. Dokumentpfade beginnen mit:

{BASE_URL}/api/v1/documents

Verwenden Sie für Codenica Cloud die öffentliche Domain Ihrer Installation:

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 genau die mitgeteilte Adresse:

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

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

Dokumente - Bereiche des API-Schlüssels

Erstellen Sie den API-Schlüssel in Codenica unter Settings - API - API Keys. Verwenden Sie einen Namen, der Anwendung und Umgebung erkennen lässt, und wählen Sie anschließend nur die für Dokumentoperationen benötigten Bereiche aus.

Der vollständige Ablauf dieses Artikels benötigt:

  • documents:read - Dokumente auflisten und lesen;
  • documents:write - erstellen und aktualisieren;
  • documents:delete - Dokumente löschen;
  • documents:schema - Felder und Beziehungsziele lesen;
  • documents:stats - Statistiken und Feldwerte;
  • documents:relationships:read und documents:relationships:write - Beziehungen lesen und ändern;
  • documents:files:read und documents:files:write - Dateien verwalten.

Für eine reine Leseintegration reichen documents:read und documents:schema normalerweise aus. Fügen Sie Statistik-, Beziehungs- und Dateibereiche nur hinzu, wenn die Integration sie benötigt.

Technische Felder können documents:technical:read erfordern. Zum Schreiben geheimer Felder benötigen Sie documents:secrets:write. Speichern Sie nach der Erstellung Client ID und Client Secret in einem sicheren Speicher. Das Secret wird nur bei der Erstellung oder Rotation angezeigt.

Dokumente - Authentifizierungs-Header

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

export CLIENT_ID="cna_your_client_id"
export CLIENT_SECRET="cns_your_client_secret"

curl --request GET --url "$BASE_URL/api/v1/documents" \
  --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 eines Administrators noch eine Panel-Sitzung. Ein JWT meldet einen Benutzer bei Codenica an, während ein API-Schlüssel eine externe Anwendung mit der ausgewählten Datenbank verbindet. Außerhalb einer lokalen Testumgebung sollten Sie HTTPS verwenden.

Speichern Sie das Secret nicht in einem Repository, einer URL, Logs, der Befehlshistorie oder in an den Browser ausgeliefertem Code. Die Beispiele verwenden Platzhalterwerte.

Dokumente - Installationskontext prüfen

Lesen Sie vor den eigentlichen Operationen 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 Bereiche sowie documents in capabilities.resources. Lesen Sie auch die Limits für Seiten, Uploads und Anfragen.

Bewahren Sie meta.requestId auf. Wenn der Kontext auf die falsche Installation verweist oder ein Bereich fehlt, stoppen Sie die Synchronisierung und korrigieren Sie Adresse oder Schlüssel. Versuchen Sie nicht, die Datenbank im Request-Body zu ändern.

Dokumente - Schema der Felder und Typen

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

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

Prüfen Sie bei itemType=invoice zuerst die Pflichtfelder:

Feld
Typ
Bedeutung
date
dateTime
Dokumentdatum
docNumber
string
Rechnungs- oder Dokumentnummer

Das Schema beschreibt außerdem readable, writable, required, technical, secretWriteOnly, Optionen, die maximale Länge, Eindeutigkeit und Regeln für die automatische Erzeugung. Die Feldmenge ist nicht in jeder Datenbank gleich.

Die Felder key und keyType sind geheim. Sie werden in normalen Antworten nicht zurückgegeben und können nicht zum Filtern, Sortieren, für Statistiken oder Feldwertabfragen verwendet werden. Vergleichen Sie den Body vor dem Senden mit dem Schema.

Dokumente - verfügbare Endpoints

Die folgende Übersicht enthält die wichtigsten Operationen. Ersetzen Sie die Werte in geschweiften Klammern durch die von der API gelieferten Kennungen.

  • GET /api/v1/documents - Liste;
  • GET /api/v1/documents/schema - Feld- und Beziehungsschema;
  • GET /api/v1/documents/stats - Statistiken;
  • GET /api/v1/documents/values - Feldwerte;
  • GET /api/v1/documents/{id} - einzelnes Dokument;
  • POST /api/v1/documents - erstellen;
  • PATCH /api/v1/documents/{id} - teilweise aktualisieren;
  • DELETE /api/v1/documents/{id} - löschen;
  • POST /api/v1/documents:batch - Create-, Update- und Delete-Operationen;
  • GET /api/v1/documents/{id}/relationships - Beziehungsliste;
  • POST /api/v1/documents/{id}/relationships - Beziehung hinzufügen;
  • POST /api/v1/documents/{id}/relationships:batch - mehrere Beziehungen ändern;
  • DELETE /api/v1/documents/{id}/relationships/{targetDataSet}/{targetId} - Beziehung entfernen;
  • GET /api/v1/documents/{id}/files - Dateiliste;
  • POST /api/v1/documents/{id}/files - Upload;
  • POST /api/v1/documents/{id}/files/{fileId} - vorhandene Datei anhängen;
  • PUT /api/v1/documents/{id}/files/{fileId}/main - Hauptdatei festlegen;
  • DELETE /api/v1/documents/{id}/files/{fileId} - Datei löschen oder trennen;
  • GET /api/v1/documents/{id}/files/{fileId}/content - Inhalt herunterladen.

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

Dokumente - Auflistung und Seitennavigation

Lesen Sie die Liste seitenweise. Dieses Beispiel gibt die ersten zehn invoice-Dokumente zurück:

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&page=1&pageSize=10&sort=date&direction=desc" \
  --header "Accept: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Eine Collection-Antwort enthält items, page, pageSize, totalItems, totalPages und hasNextPage. Lesen Sie weiter, solange hasNextPage den Wert true hat. Wenn die Reihenfolge für die Synchronisierung wichtig ist, legen Sie immer eine Sortierung fest.

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

Dokumente - Suche und Filter

Das Testbeispiel sucht ein Dokument nach seiner benutzerdefinierten Kennung, seinem Typ und Status:

curl --request GET --url "$BASE_URL/api/v1/documents?itemType=invoice&customId=PUBLIC-API-DOC-20260905101715-SOURCE&status=Draft&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"

Je nach Schema können Sie unter anderem itemType, ids, search, customId, docNumber, name, status, category, currency, createdAfter, createdBefore, updatedAfter und updatedBefore verwenden.

Für genaue Bedingungen verwenden Sie filter:

filter=status:eq:Draft
filter=docNumber:contains:2026
filter=category:in:Procurement,Sales
filter=description:notEmpty:

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

Dokumente - 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/documents?itemType=invoice&fields=id,itemType,customId,docNumber,name,status,total" \
  --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/documents/$DOCUMENT_ID?include=files,relationships" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Der Zugriff auf eingeschlossene Daten muss separat gewährt werden. Fehlende Bereiche wie documents:files:read oder documents:relationships:read lassen sich nicht mit fields=* umgehen. Technische und geheime Felder werden nur zurückgegeben, wenn Bereiche und Schema dies erlauben.

Dokumente - einen Datensatz erstellen

Verwenden Sie POST /api/v1/documents, um ein Dokument zu erstellen. Geben Sie den Typ in itemType und beschreibbare Felder in attributes an. Dieses Beispiel stellt eine Rechnung aus einem Buchhaltungssystem dar:

export IDEMPOTENCY_KEY="documents-create-20260905-0001"

curl --request POST --url "$BASE_URL/api/v1/documents" \
  --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 '{
    "itemType": "invoice",
    "attributes": {
      "customId": "PUBLIC-API-DOC-20260905101715-SOURCE",
      "date": "2026-09-05T10:17:15Z",
      "docNumber": "FV/2026/0001",
      "name": "Invoice from ERP",
      "category": "Procurement",
      "type": "invoice",
      "status": "Draft",
      "currency": "PLN",
      "paymentMethod": "bank_transfer",
      "total": 1250.50,
      "description": "Document imported from the external accounting system."
    }
  }'

Im getesteten invoice-Schema waren date und docNumber Pflichtfelder. Ihre Datenbank kann zusätzliche Felder oder andere Werte verlangen. Senden Sie keine schreibgeschützten Felder und keine id, sofern das Schema dies nicht ausdrücklich erlaubt.

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 das Dokument später im externen System leichter finden.

Dokumenterstellung sicher wiederholen

Wenn nach dem Senden einer Rechnung ein Timeout auftritt, wissen Sie noch nicht, ob der Datensatz gespeichert wurde. Senden Sie exakt dieselbe Anfrage mit demselben Idempotency-Key und identischem Body. Erstellen Sie nicht deshalb einen neuen Schlüssel, weil die erste Antwort nicht angekommen ist:

curl --request POST --url "$BASE_URL/api/v1/documents" \
  --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 '{
    "itemType": "invoice",
    "attributes": {
      "customId": "PUBLIC-API-DOC-20260905101715-SOURCE",
      "date": "2026-09-05T10:17:15Z",
      "docNumber": "FV/2026/0001",
      "name": "Invoice from ERP",
      "category": "Procurement",
      "type": "invoice",
      "status": "Draft",
      "currency": "PLN",
      "paymentMethod": "bank_transfer",
      "total": 1250.50,
      "description": "Document imported from the external accounting system."
    }
  }'

Eine idempotente Wiederholung gibt dasselbe Dokument zurück, statt ein Duplikat zu erstellen. Derselbe Schlüssel darf später keinen anderen Body, Endpoint oder Zweck beschreiben. Eine solche Wiederverwendung liefert 422 idempotency_key_reused. Verwenden Sie für jede neue Absicht einen neuen Wert.

Dokumente - einen einzelnen Datensatz lesen

Lesen Sie ein erstelltes oder gefundenes Dokument über seine UUID:

export DOCUMENT_ID="11111111-1111-1111-1111-111111111111"

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

Die Antwort enthält id, itemType, Felder in attributes und Metadaten in meta. Den aktuellen ETag finden Sie im HTTP-Header und normalerweise auch in data.meta.etag sowie in der Hülle meta.etag.

Lesen Sie vor jeder Änderung am Dokument, an einer Beziehung oder an einer Datei einen aktuellen ETag. Verwenden Sie keinen früher gespeicherten Wert, wenn ein anderer Benutzer oder eine andere Integration den Datensatz geändert haben könnte.

Dokumente - teilweise Aktualisierung mit ETag

PATCH ändert nur die im Body gesendeten Felder. Erforderlich sind der aktuelle Wert von If-Match und ein neuer Idempotency-Key:

export CURRENT_ETAG='"etag-v1"'
export UPDATE_IDEMPOTENCY_KEY="documents-update-20260905-0001"

curl --request PATCH --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: $UPDATE_IDEMPOTENCY_KEY" \
  --data-raw '{
    "attributes": {
      "status": "Approved",
      "total": 1350.75,
      "description": "Invoice approved after verification in the accounting system."
    }
  }'

Sie müssen nicht das gesamte Dokument senden. Nicht im Body enthaltene Felder bleiben unverändert. Speichern Sie nach einer erfolgreichen Operation den neuen, von der API zurückgegebenen ETag.

Dokumente - Schutz vor einer veralteten Änderung

Die API lehnt eine Änderung ohne den aktuellen ETag ab. Wenn If-Match fehlt, wird 428 if_match_required zurückgegeben:

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

Wenn Sie einen alten ETag senden, erhalten Sie 412 if_match_failed und der Datensatz bleibt unverändert. Lesen Sie das Dokument erneut, prüfen Sie die neue Version und entscheiden Sie erst dann, ob Sie die Änderung erneut senden.

{
  "status": 412,
  "code": "if_match_failed",
  "detail": "The supplied ETag is not the current document version.",
  "requestId": "request-id-from-response"
}

Dieselbe Regel gilt für das Löschen von Dokumenten, Änderungen an Beziehungen und Dateioperationen, wenn der Pfad den Datensatz verändert.

Dokumente - Beziehungen und gültige Ziele

Ein Dokument kann mit einem anderen Objekt verknüpft werden, wenn das Ziel für den Schlüssel sichtbar und im Schema erlaubt ist. Prüfen Sie vor dem Senden einer Beziehung relationshipTargets in der Schemaantwort.

Senden Sie targetId, targetDataSet, optional targetItemType und relationshipType, sofern das ausgewählte Ziel dies unterstützt. Dieses Beispiel verknüpft zwei Rechnungen direkt:

curl --request POST --url "$BASE_URL/api/v1/documents/$DOCUMENT_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: documents-relationship-add-0001" \
  --data-raw '{
    "targetId": "22222222-2222-2222-2222-222222222222",
    "targetDataSet": "documents",
    "targetItemType": "invoice",
    "relationshipType": "related"
  }'

Senden Sie keinen targetItemType, der vom tatsächlichen Typ des Ziels abweicht. Erstellen Sie keine Beziehung zum selben Datensatz oder zu einem Ziel, das für den Schlüssel nicht sichtbar ist.

Dokumente - Beziehungen lesen und entfernen

Lesen Sie die aktuelle Beziehungsliste getrennt oder zusammen mit dem Dokument:

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

Um eine einzelne Beziehung zu entfernen, lesen Sie zuerst einen aktuellen ETag des Dokuments und senden Sie:

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/relationships/documents/$TARGET_DOCUMENT_ID?relationshipType=related&targetItemType=invoice" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-relationship-delete-0001"

Eine erfolgreiche Entfernung gibt 200 mit data=true zurück. Lesen Sie die Liste danach erneut und speichern Sie den neuen ETag des Dokuments.

Dokumente - mehrere Beziehungen gemeinsam ändern

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

curl --request POST --url "$BASE_URL/api/v1/documents/$DOCUMENT_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: documents-relationship-batch-0001" \
  --data-raw '{
    "add": [
      {
        "targetId": "33333333-3333-3333-3333-333333333333",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      }
    ],
    "remove": [
      {
        "targetId": "22222222-2222-2222-2222-222222222222",
        "targetDataSet": "documents",
        "targetItemType": "invoice",
        "relationshipType": "related"
      }
    ]
  }'

Die Antwort enthält die Zähler added, removed und skipped. Verwenden Sie auch dann einen aktuellen ETag, wenn der Batch nur eine Änderung enthält. Prüfen Sie bei einem Teilergebnis jedes Element, bevor Sie eine weitere Anfrage senden.

Dokumente - eine Datei auflisten und hochladen

Dateien werden getrennt von den Dokumentfeldern verwaltet. Lesen Sie zunächst die aktuelle Liste:

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

Senden Sie die Datei als multipart/form-data. Dieses Beispiel erstellt eine Textdatei und setzt sie als Hauptdatei:

printf 'Invoice attachment created by the ERP integration.\n' > invoice-primary.txt
export FILE_UPLOAD_ETAG='"etag-v1"'

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

Die Antwort enthält id, fileName, contentType, size, relationshipType, isMain und downloadUrl. Diese URL ist relativ zu BASE_URL.

Dokumente - Datei herunterladen und Hauptdatei wechseln

Laden Sie den Dateiinhalt über den Endpoint content herunter. Speichern Sie ihn als Binärdaten:

curl --request GET --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$FILE_ID/content" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --output downloaded-invoice-file

Sie können eine zweite Datei mit makeMain=false hochladen. Um die Hauptdatei zu wechseln, lesen Sie den aktuellen ETag des Dokuments und rufen Sie auf:

curl --request PUT --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID/files/$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: documents-file-main-0001"

Lesen Sie die Dateiliste nach der Änderung. Genau eine Datei sollte isMain=true haben. Speichern Sie danach den neuen ETag.

Dokumente - eine vorhandene Datei anhängen

Wenn eine Datei bereits bei einem anderen Dokument gespeichert ist, können Sie sie an einen weiteren Datensatz anhängen, ohne den Inhalt erneut hochzuladen:

export TARGET_DOCUMENT_ID="11111111-1111-1111-1111-111111111111"
export EXISTING_FILE_ID="44444444-4444-4444-4444-444444444444"

curl --request POST --url "$BASE_URL/api/v1/documents/$TARGET_DOCUMENT_ID/files/$EXISTING_FILE_ID?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: documents-file-attach-0001"

Das Anhängen erzeugt eine Beziehung zwischen Dokument und Datei. Das Trennen über DELETE /documents/{id}/files/{fileId} entfernt die Beziehung von diesem Dokument, löscht aber keine Datei, die zu einem anderen Dokument gehört. Das Löschen der Datei aus ihrem Eigentümerdokument ist eine eigene Operation.

Dokumente - eine Datei löschen

Lesen Sie vor dem Löschen einer Datei eine aktuelle Dateiliste und den ETag des Dokuments. 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/documents/$DOCUMENT_ID/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: documents-file-delete-0001"

Aktualisieren Sie nach der Antwort 200 den ETag und lesen Sie die Liste erneut. Das Löschen der letzten Datei löscht nicht das Dokument, sondern hinterlässt eine leere Dateisammlung. Wenn die Datei nur an das Dokument angehängt war, entfernen Sie zuerst die Beziehung und prüfen Sie erst danach, ob die Datei an ihrem Speicherort gelöscht werden soll.

Dokumente - Statistiken und Feldwerte

Statistiken zeigen die Verteilung der Daten. Der Endpoint values liefert Werte, die zum Aufbau von Filtern geeignet sind:

curl --request GET --url "$BASE_URL/api/v1/documents/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/documents/values?field=status&search=Draf&limit=20" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET"

Beispiel für eine Werteantwort:

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

Statistiken und Werte verändern keine Daten. Verwenden Sie sie nicht für geheime oder technische Felder ohne den passenden Bereich.

Dokumente - Batch-Operationen

Der Endpoint documents:batch kann mehrere Dokumente in einer Anfrage erstellen, aktualisieren und löschen. update- und delete-Operationen benötigen für jedes Element einen eigenen ETag:

curl --request POST --url "$BASE_URL/api/v1/documents:batch" \
  --header "Content-Type: application/json" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "Idempotency-Key: documents-batch-0001" \
  --data-raw '{
    "items": [
      {
        "operation": "create",
        "create": {
          "itemType": "invoice",
          "attributes": {
            "customId": "PUBLIC-API-DOC-20260905101715-TARGET-A",
            "date": "2026-09-05T10:18:00Z",
            "docNumber": "FV/2026/0002",
            "name": "Related invoice",
            "category": "Procurement",
            "type": "invoice",
            "status": "Draft",
            "currency": "PLN",
            "paymentMethod": "bank_transfer",
            "total": 510.00
          }
        }
      },
      {
        "operation": "update",
        "id": "11111111-1111-1111-1111-111111111111",
        "ifMatch": "\"etag-v1\"",
        "update": {
          "attributes": {
            "status": "Approved"
          }
        }
      },
      {
        "operation": "delete",
        "id": "22222222-2222-2222-2222-222222222222",
        "ifMatch": "\"etag-v3\""
      }
    ]
  }'

Bei vollständigem Erfolg erhalten Sie 200, bei Teilerfolg 207. Ein Batch ist keine Alles-oder-nichts-Transaktion. Speichern Sie Kennungen, ETags und Status jeder einzelnen Operation.

Dokumente - einen Datensatz löschen

Das Löschen eines Dokuments kann über die API nicht rückgängig gemacht werden. Lesen Sie den aktuellen ETag und prüfen Sie UUID und Datenbankadresse:

curl --request DELETE --url "$BASE_URL/api/v1/documents/$DOCUMENT_ID" \
  --header "X-Codenica-Client-Id: $CLIENT_ID" \
  --header "X-Codenica-Client-Secret: $CLIENT_SECRET" \
  --header "If-Match: $CURRENT_ETAG" \
  --header "Idempotency-Key: documents-delete-0001"

Eine erfolgreiche Antwort gibt 200 und data=true zurück. Ein späterer Leseversuch liefert 404 document_not_found. Wenn der Datensatz Beziehungen oder Dateien besitzt, sichern Sie die benötigten Daten vor dem Löschen außerhalb des Systems.

Dokumente - 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 Dokumenttyp oder ungültige Beziehung;
  • 401 - fehlende oder ungültige Zugangsdaten;
  • 403 - fehlender Bereich oder fehlende Berechtigung;
  • 404 - Dokument oder Ziel nicht vorhanden oder nicht sichtbar;
  • 409 - Datenkonflikt;
  • 412 - veralteter ETag;
  • 413 - Datei überschreitet das Limit;
  • 428 - If-Match oder Idempotency-Key fehlt;
  • 429 - Anfrage-Limit überschritten;
  • 503 - Dienst vorübergehend nicht verfügbar.

Lesen Sie X-RateLimit-Limit und X-RateLimit-Remaining. Verwenden Sie bei 429 den zurückgegebenen Wert Retry-After und bei weiteren Versuchen wachsende Wartezeiten. Maskieren Sie Client Secret, Dokumentgeheimnisse und Dateiinhalte in Logs.

Dokumente - vollständiger Integrationsablauf

  1. Erstellen Sie unter Settings - API - API Keys einen Schlüssel und vergeben Sie nur die für die Integration erforderlichen Bereiche.
  2. Setzen Sie BASE_URL auf die öffentliche Codenica-Cloud-Adresse oder die vom Administrator mitgeteilte On-Premise-Adresse.
  3. Senden Sie GET /api/v1/context und bestätigen Sie die richtige Datenbank, den Aufrufer, die Bereiche und die Limits.
  4. Lesen Sie GET /api/v1/documents/schema und wählen Sie Dokumenttyp, Pflichtfelder und akzeptierte Werte.
  5. Lesen Sie die paginierte und gefilterte Liste oder rufen Sie ein Dokument über seine UUID ab.
  6. Erstellen Sie eine Rechnung mit einem eindeutigen Idempotency-Key, speichern Sie UUID und ETag und wiederholen Sie nach einem Timeout die identische Anfrage.
  7. Aktualisieren Sie den Datensatz nur mit dem aktuellen If-Match und speichern Sie nach jeder Änderung den neuen ETag.
  8. Fügen Sie die vom Schema erlaubten Beziehungen hinzu, lesen und entfernen Sie sie.
  9. Verwenden Sie die speziellen Datei-Endpoints, behalten Sie den aktuellen ETag und unterscheiden Sie Anhängen und Löschen.
  10. Nutzen Sie für größere Mengen stats, values und documents:batch und prüfen Sie anschließend jedes Operationsergebnis.
  11. Lesen Sie das Dokument vor dem Löschen erneut, bestätigen Sie den richtigen ETag und verwenden Sie einen neuen Idempotenzschlüssel.

Mit diesem Ablauf können Sie die Verarbeitung von Rechnungen und anderen Dokumenten in eine Buchhaltungssoftware, einen Dokumentenworkflow, ein ERP-System oder eine eigene Integrationsanwendung übernehmen.