Deliver reference data through the interface: create a key, send the call, read the response

Ein Personalsystem, ein Standortverzeichnis oder eine Datenbank mit Gebäudearten kann seine Daten selbst nach knooing schicken. Dafür braucht das Fremdsystem einen Schlüssel, der es als genau diese Quelle ausweist. Der Mandant und die Quelle ergeben sich aus dem Schlüssel, nie aus dem Inhalt der Lieferung. Ein fremdes System kann also nicht behaupten, es sei ein anderes.

Diese Anleitung ist Teil 3 von 5. Sie beschreibt, was Sie als Verantwortliche oder Verantwortlicher tun und sehen: Schlüssel anlegen, den Aufruf kennen, die Antwort lesen. Wie die Quelle ihre Rechte bekommt, steht in Teil 2, wie Sie Lieferungen im Nachhinein prüfen, in Teil 4. Wie Schlüssel allgemein funktionieren, zeigt API-Schlüssel anlegen.

Schritt 1: Einen Schlüssel mit Quelle anlegen

Klicken Sie in der Seitenleiste unten auf Einstellungen, dann im Bereich Integrationen auf Schnittstellen. Im Reiter Schlüssel klicken Sie auf Schlüssel anlegen. Im Dialog füllen Sie nur das aus, was für Referenzdaten zählt:

• Name: das liefernde System, zum Beispiel Personalsystem Beispiel Lieferung.
• Kanal: können Sie so lassen, wie er voreingestellt ist.
• Berechtigungen: Standorte liefern, Personen liefern, Wertelisten liefern. Haken Sie nur an, was das System liefern soll. Der Dialog hakt zu Beginn Störungen melden und Status eigener Meldungen abfragen an. Nehmen Sie diese Haken weg, wenn das System keine Störungen melden soll.
• Quelle: erscheint, sobald Sie eine Berechtigung für Referenzdaten anhaken. Wählen Sie die eingetragene Quelle, hier Personalsystem Beispiel.

Klicken Sie auf Anlegen.

Warum immer eine Quelle? Referenzdaten und Kontrollnachweise gehören immer zu genau einer Quelle. Die Quelle legen Sie hier fest, nie das liefernde System. Solange keine gewählt ist, steht am Feld Für Referenzdaten und Kontrollnachweise wählen Sie bitte eine Quelle. und Anlegen bleibt gesperrt.

Warum eigene Berechtigungen je Art von Daten? Wer nur Standorte liefern soll, kann keine Personen schicken. Ein Fehler im Standortverzeichnis kann dann Ihre Personenliste nicht beschädigen.

1234

1. 1Name des liefernden Systems
2. 2Nur die Berechtigungen für Referenzdaten
3. 3Quelle
4. 4Anlegen

Schritt 2: Den Schlüssel kopieren

knooing zeigt den neuen Schlüssel genau einmal an: Dieser Schlüssel wird nur jetzt angezeigt. Bewahren Sie ihn sicher auf, zum Beispiel in einem Passwort-Tresor - er lässt sich später nicht erneut abrufen. Klicken Sie auf Kopieren und dann auf Fertig. Geben Sie den Schlüssel an die Person weiter, die das Fremdsystem einrichtet, nicht per E-Mail im Klartext, sondern über einen Tresor.

!56

1. !Wird nur jetzt angezeigt
2. 5Kopieren
3. 6Fertig

Warum nur einmal? knooing speichert den Schlüssel selbst nicht, sondern nur einen daraus berechneten Prüfwert. Geht er verloren, legen Sie einen neuen an und widerrufen den alten. In der Schlüsselliste erkennen Sie Ihren Schlüssel am Präfix, an der Quelle (Quelle: Personalsystem Beispiel) und an Zuletzt benutzt.

Schritt 3: Den Beispiel-Aufruf lesen

Das Fremdsystem braucht Pfad, Berechtigung und ein Beispiel. Das alles steht auf der Seite Stammdaten im Reiter Quellen und Schnittstelle im Abschnitt Schnittstelle:

• Die Tabelle Pfade und benötigte Scopes nennt für jede Art von Daten den Pfad, die Berechtigung (den Scope) und die Lieferart:

  | Daten | Pfad | Scope | Lieferart | |---|---|---|---| | Standorte | PUT /api/v1/reference-data/locations | reference:locations:write | Delta oder Vollbestand | | Verantwortliche | PUT /api/v1/reference-data/persons | reference:persons:write | Delta oder Vollbestand | | Werteliste | PUT /api/v1/reference-data/value-lists/{key}/entries | reference:valuelists:write | Delta oder Vollbestand | | Kontrollnachweise | POST /api/v1/control-coverage/ingest | coverage:write | Nur Delta |

• Unter Beispiel für wählen Sie die Art der Daten. Darunter stehen Beispiel-Payload und Aufruf mit curl, jeweils mit dem Knopf Kopieren.

• Gesamte API-Dokumentation öffnet die vollständige Beschreibung der Schnittstelle in einem neuen Fenster. Zur Schlüsselverwaltung führt zurück zu den Schlüsseln.

123

1. 1Zur Schlüsselverwaltung
2. 2Pfade und benötigte Scopes
3. 3Beispiel für

Warum sagt die Tabelle den Scope dazu? Der Schlüssel muss genau die Berechtigung tragen, die der Pfad verlangt. Fehlt sie, antwortet die Schnittstelle mit einer Ablehnung (siehe unten).

Schritt 4: Die Lieferung senden

Das Fremdsystem sendet eine Anfrage an den Pfad der Daten. Den Schlüssel trägt es im Kopffeld X-API-Key oder als Authorization: Bearer-Kopf. Die Adresse der Schnittstelle Ihres knooing-Systems steht im Beispiel Aufruf mit curl. Im Text unten steht <Adresse Ihres knooing-Systems> stellvertretend.

Der Körper ist ein JSON-Objekt:

• batchId (Pflicht): die Kennung dieser Lieferung, 1 bis 128 Zeichen aus Buchstaben, Ziffern und . _ : -.
• mode: delta (voreingestellt) oder snapshot.
• rows (Pflicht): die Zeilen, höchstens 5000 je Lieferung. Jede Zeile trägt eine externalId, die Kennung im liefernden System.
• dryRun: mit true ein Probelauf, der nichts schreibt.

Die Zeilen unterscheiden sich je nach Daten. Bei Standorten gehören name, kind und optional parentExternalId (der übergeordnete Eintrag) und active dazu. Gültige Arten sind country, site, building, floor, room, rack, cloud_region und warehouse. Bei Personen sind es name, optional email und active. Bei Wertelisten sind es value und label, der Schlüssel der Liste steht im Pfad.

Ein vollständiges Beispiel für Standorte:

curl -X PUT '<Adresse Ihres knooing-Systems>/api/v1/reference-data/locations' \
  -H 'X-API-Key: <Ihr Schlüssel>' \
  -H 'Content-Type: application/json' \
  --data '{
    "batchId": "standorte-2026-10-06-001",
    "mode": "delta",
    "rows": [
      { "externalId": "LOC-BL", "name": "Beispielland", "kind": "country" },
      { "externalId": "LOC-BL-NORD", "name": "Standort Nord", "kind": "site", "parentExternalId": "LOC-BL" },
      { "externalId": "LOC-BL-NORD-G1", "name": "Gebäude 1", "kind": "building", "parentExternalId": "LOC-BL-NORD" }
    ]
  }'

Warum eine batchId? Jede Lieferung braucht eine eigene Kennung, damit eine Wiederholung nichts doppelt tut. Schickt das Fremdsystem dieselbe batchId mit demselben Inhalt noch einmal, bekommt es die gespeicherte Antwort zurück und knooing ändert nichts ein zweites Mal. Das schützt bei Netzwerkfehlern: Im Zweifel einfach nochmals senden. Mit anderem Inhalt antwortet die Schnittstelle mit 409.

Warum darf die Reihenfolge der Zeilen beliebig sein? Eine Lieferung löst Verweise auf übergeordnete Einträge selbst auf. Ein Raum darf vor seinem Gebäude stehen.

Schritt 5: Die Antwort lesen

Bei einer angenommenen Lieferung antwortet knooing mit Status 200 und einem JSON-Objekt. Die wichtigsten Felder:

• status: succeeded (alles übernommen), partially_failed (einzelne Zeilen abgelehnt), failed (nichts übernommen), blocked (ein Abschluss ist gesperrt) oder dry_run.
• counts: received (empfangen), created (angelegt), updated (geändert), unchanged (unverändert), deactivated (deaktiviert) und rejected (abgelehnt).
• runId: die Kennung des Laufs, so erscheint er in der Laufhistorie.
• deliveryUsable: ob die Lieferung als Abgleich zählt. Liegt die Ablehnquote über 5 Prozent, steht hier false, und hints sagt es mit Die Ablehnquote liegt über 5 %. Fehlerfreie Zeilen sind übernommen, die Lieferung zählt aber nicht als erfolgreicher Abgleich.
• rows: die abgelehnten Zeilen mit Zeilennummer, Ihrer externalId, einem code und einer Meldung.
• hints: Hinweise, zum Beispiel dass die Handpflege für die Quelle gesperrt ist.

Die Codes der abgelehnten Zeilen, die Sie am häufigsten sehen:

| Code | Bedeutung | |---|---| | invalid_value | Ein Pflichtfeld fehlt oder ein Wert ist ungültig. | | duplicate_in_batch | Diese Kennung kommt in der Lieferung mehrfach vor. | | unknown_parent | Der übergeordnete Eintrag ist nicht bekannt oder nicht aktiv. | | parent_rejected | Der übergeordnete Eintrag dieser Lieferung wurde abgelehnt. | | cycle | Die Hierarchie enthält einen Ring. | | identity_conflict | Name oder E-Mail-Adresse sind bereits einem anderen Eintrag zugeordnet. | | value_change_forbidden | Der Wert eines bestehenden Eintrags kann nicht geändert werden. |

Warum nur ein gemeinsamer Code für Name und E-Mail? Getrennte Codes würden verraten, ob eine bestimmte E-Mail-Adresse im Mandanten vorkommt. Darum bleibt die Meldung bewusst allgemein.

Schritt 6: Die Lieferung in der Laufhistorie prüfen

Öffnen Sie unter Stammdaten den Reiter Quellen und Schnittstelle und klicken Sie bei der Karte der Quelle auf Laufhistorie anzeigen. Jede Lieferung steht dort als Zeile, bei Standorten zum Beispiel mit Delta, Lieferkennung standorte-2026-10-06-001 und dem Ergebnis Erfolgreich sowie 6 übernommen, 0 abgelehnt von 6. Die Karte zeigt darüber Fristgerecht, sobald eine Lieferfrist gesetzt ist. Mehr dazu in Teil 4.

1

1. 1Ergebnis der Lieferung

Wenn etwas nicht klappt

Die Antworten der Schnittstelle sind Teil der Lieferung. Diese Meldungen sehen Sie im Fremdsystem oder im Protokoll des Aufrufs:

• Ungültiger oder fehlender API-Schlüssel. (Status 401, unauthorized) Der Schlüssel fehlt im Kopffeld, ist falsch kopiert, abgelaufen oder widerrufen. Prüfen Sie Status und Ablauf in der Schlüsselliste.
• Dem Schlüssel fehlt die Berechtigung "reference:persons:write". (Status 403, insufficient_scope) Der Schlüssel darf diese Art von Daten nicht liefern. Legen Sie einen Schlüssel mit der passenden Berechtigung an und widerrufen Sie den alten.
• Zu viele Anfragen mit diesem Schlüssel. Bitte später erneut versuchen. (Status 429) Die Grenze der Anfragen je Minute ist erreicht. Das Fremdsystem soll langsamer senden und es später nochmals versuchen.
• Die Quelle dieses Schlüssels ist nicht aktiv. und Dieser Schlüssel ist an keine Quelle gebunden. Referenzdaten und Nachweise brauchen einen Schlüssel mit Quelle. (Status 403, source_not_bound) Die Quelle ist stillgelegt oder dem Schlüssel fehlt die Quelle. Wenden Sie sich an die Verwaltung der CMDB.
• Die CMDB ist für diesen Mandanten nicht aktiviert. (Status 403, feature_disabled) Das Modul CMDB ist für Ihren Mandanten nicht freigeschaltet.
• batchId ist Pflicht (1 bis 128 Zeichen: Buchstaben, Ziffern, . _ : -). (Status 400) Die Lieferung hat keine oder eine ungültige batchId.
• rows ist leer. Eine leere Lieferung ist keine Lieferung. (Status 400) Schicken Sie mindestens eine Zeile.
• Diese batchId wurde bereits mit anderem Inhalt geliefert. Bitte eine neue batchId verwenden. (Status 409, batch_conflict) Zu jeder Lieferung gehört eine neue batchId, sobald sich der Inhalt ändert.
• Diese Werteliste ist nicht an die Quelle des Schlüssels gebunden. (Status 403, list_not_bound) Binden Sie die Liste im Reiter Wertelisten an die Quelle des Schlüssels.
• Vollbestands-Lieferungen sind für diese Quelle nicht freigegeben. Freigabe unter „Stammdaten“ im Reiter „Quellen und Schnittstelle“. (Status 403, snapshot_not_allowed) Schalten Sie Vollbestand erlaubt ein oder liefern Sie als Delta (siehe Teil 2).
• Der Körper ist kein gültiges JSON. (Status 400) Prüfen Sie Anführungszeichen und Klammern im Körper der Anfrage.
• Höchstens 5000 Zeilen je Lieferung. (Status 413, payload_too_large) Teilen Sie größere Bestände auf.
• Die Schnittstellenbeschreibung ließ sich nicht laden. Diese Meldung erscheint bei den Knöpfen Beschreibung als JSON und Beschreibung als YAML. Nutzen Sie solange Gesamte API-Dokumentation.