Codenica API

Die Codenica API verbindet externe Anwendungen mit den Daten Ihres Codenica-Systems - sowohl in der Cloud als auch On-Premise. Dieser Artikel beschreibt die Regeln, die für die gesamte API gelten: Schlüssel erstellen, Berechtigungsbereiche auswählen, die Service-Adresse ermitteln, Anfragen authentifizieren und sicher senden. Felder und Vorgänge der einzelnen Objekte werden in eigenen API-Artikeln beschrieben.

API-Schlüssel erstellen

Beginnen Sie die Vorbereitung der Integration mit dem passenden API-Schlüssel. Der Schlüssel ist Ihrem Unternehmen zugeordnet und erlaubt einer externen Anwendung nur die Vorgänge, die durch die ausgewählten Berechtigungsbereiche abgedeckt sind.

Öffnen Sie Einstellungen und wählen Sie anschließend API und API Keys.
Tragen Sie unter Name einen Namen für die Integration ein, zum Beispiel Lagerintegration oder BI-Berichte.
Ergänzen Sie bei Bedarf eine Beschreibung, damit Sie den Verwendungszweck später erkennen.
Legen Sie das Datum Aktiv bis fest. Eine kürzere Gültigkeit begrenzt die Folgen versehentlich offengelegter Zugangsdaten.
Wählen Sie nur die Berechtigungsbereiche aus, die die Integration benötigt.
Wählen Sie API-Schlüssel erstellen.
Kopieren Sie Client ID und Client Secret sofort und speichern Sie beide im Secret Store der Integration.

Das Client Secret wird nur bei der Erstellung des Schlüssels oder bei einer Rotation angezeigt. Die Schlüsselliste enthält die Schlüsseldaten, gibt das Secret aber nicht erneut zurück. Wenn das Secret verloren geht, rotieren Sie den Schlüssel oder löschen Sie ihn und erstellen Sie einen neuen.

API-Keys-Bereich in den Codenica-Einstellungen mit dem Formular zum Erstellen eines Schlüssels und der Liste der Berechtigungsbereiche.

Schlüssellimits nach Lizenz

Behandeln Sie jeden Schlüssel als eigenen Zugangskanal für eine Integration. Die Zahl der verfügbaren Schlüssel hängt von der Lizenz des Unternehmens ab:

Lizenz

API-Zugriff

Maximale Zahl aktiver Schlüssel

Starter

Nicht verfügbar

Plus

Enterprise

100

Beim Löschen eines Schlüssels wird sein Datensatz entfernt und ein Platz im Limit frei. Der Vorgang ist endgültig. Vergewissern Sie sich daher vor dem Löschen, dass die Integration diesen Schlüssel nicht mehr verwendet.

Nach Ablauf des Schlüssels wird die Authentifizierung beendet, der Datensatz bleibt jedoch in der Liste sichtbar.

Wenn Sie bei der Erstellung kein Enddatum festlegen, beträgt die Standardgültigkeit 90 Tage. Ein Schlüssel kann höchstens 5 Jahre aktiv sein. Wählen Sie das Datum am besten passend zum Prüfzyklus der Integration.

API-Adresse und Authentifizierung

Die Basisadresse hängt vom Bereitstellungsmodell ab. Ergänzen Sie die Basisadresse um /api/v1 und den Pfad der gewünschten Ressource.

Cloud: Verwenden Sie die öffentliche Adresse des Unternehmens, zum Beispiel https://ihr-unternehmen.codenica.com/api/v1.
On-Premise: Die von Codenica Discovery registrierte Standardadresse lautet http://codenica.local:5150/api/v1. Wenn der Administrator die Installation unter einem eigenen DNS-Namen, über einen Reverse Proxy oder mit HTTPS veröffentlicht hat, verwenden Sie die für den Integrationsserver erreichbare Adresse. Einzelheiten zur Bereitstellung finden Sie in der Installationsanleitung für Codenica On-Premise.

Verwenden Sie localhost, eine Container-Adresse oder eine Datenbankadresse nur dann, wenn die integrierende Anwendung tatsächlich auf demselben Computer läuft und dies eine bewusste Testkonfiguration ist. Der Integrationsserver muss die veröffentlichte Codenica-Adresse erreichen können.

Authentifizieren Sie jede API-Anfrage mit zwei Headern:

X-Codenica-Client-Id - die Kennung des Schlüssels;
X-Codenica-Client-Secret - das Secret des Schlüssels.

Übergeben Sie der Public API weder eine Panelsitzung noch das JWT des Benutzers. Speichern Sie das Secret niemals in der URL, in Query-Parametern, im Antwortinhalt oder in Logs.

export BASE_URL="https://ihr-unternehmen.codenica.com"
export CLIENT_ID="cna_ihre_client_id"
export CLIENT_SECRET="cns_ihr_client_secret"

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"

Ersetzen Sie für die standardmäßige On-Premise-Installation BASE_URL im Beispiel durch http://codenica.local:5150. Verwenden Sie in der Produktion HTTPS, wenn die Installation mit einem Zertifikat veröffentlicht ist.

Standardformat für Anfragen

Die Beispiele in den folgenden Artikeln verwenden einen einfachen REST-Aufbau: Methode, URL, Header und bei Vorgängen mit Inhalt JSON über --data-raw. Dieses Format lässt sich direkt in Anwendungscode oder ein Integrationstool übernehmen.

Vorgänge, die Daten ändern, benötigen zusätzlich den Header Idempotency-Key. Verwenden Sie für jede Ausführungsabsicht einen eindeutigen Wert. Eine identische Wiederholung mit demselben Schlüssel darf keinen zweiten Datensatz anlegen.

curl --request POST \
  --url "$BASE_URL/api/v1/<resource>" \
  --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: integration-create-20260907-001" \
  --data-raw '{"field":"value"}'

Bei Aktualisierungen, Löschvorgängen, Beziehungen und Dateioperationen senden Sie außerdem den Header If-Match mit dem aktuellen ETag-Wert. Die Artikel zu den einzelnen Objekten enthalten die genauen Pfade, Feldnamen und JSON-Inhalte.

Gemeinsamer Ablauf einer Integration

Senden Sie GET /api/v1/context, um Unternehmensdaten und Caller, Berechtigungsbereiche, API-Funktionen und Limits zu prüfen.
Öffnen Sie das Schema des benötigten Objekts, zum Beispiel GET /api/v1/assets/schema, um Felder, Vorgänge, Berechtigungsbereiche und unterstützte Beziehungen zu sehen.
Rufen Sie Objektlisten mit Pagination und Filtern ab. Die Filterparameter sind im Artikel des jeweiligen Objekts beschrieben.
Lesen Sie einen einzelnen Datensatz über seine ID, wenn Sie aktuelle Daten und den ETag benötigen.
Erstellen, aktualisieren und löschen Sie Datensätze mit Idempotency-Key und, falls erforderlich, If-Match.
Verwenden Sie Beziehungen, Dateien, Batch-Vorgänge und spezielle Aktionen ausschließlich über die für das Objekt dokumentierten Pfade.

Gemeinsames Antwortformat

Erfolgreiche Antworten liefern die Daten in der Eigenschaft data. Technische Informationen wie requestId und teilweise ETag stehen in meta. Protokollieren Sie requestId, damit eine Anfrage bei der Fehleranalyse schnell gefunden werden kann.

ETag, Wiederholungen und Fehler

ETag schützt einen Datensatz davor, Änderungen einer anderen Person oder Integration zu überschreiben. Speichern Sie nach dem Lesen den Wert des ETag-Headers. Senden Sie ihn vor einer Aktualisierung oder Löschung als If-Match. Verwenden Sie nach einer erfolgreichen Änderung den neuen Wert aus der API-Antwort.

428 Precondition Required mit dem Code if_match_required bedeutet, dass der erforderliche Header If-Match oder Idempotency-Key fehlt.
412 Precondition Failed mit dem Code if_match_failed bedeutet, dass der übergebene ETag nicht mehr aktuell ist. Lesen Sie den Datensatz erneut und entscheiden Sie, ob Sie die Änderung wiederholen möchten.
429 Too Many Requests bedeutet, dass das Limit überschritten wurde. Wenn vorhanden, lesen Sie den Header Retry-After und wiederholen Sie die Anfrage nach dieser Zeit mit zunehmend längeren Pausen.

Fehler verwenden das Format Problem Details. Die wichtigsten Felder sind status, code, detail und requestId. Verwenden Sie den Text in detail nicht als stabiles Fehlerkennzeichen, sondern das Feld code in der Anwendungslogik.

Antworten enthalten außerdem Limit-Header wie X-RateLimit-Limit und X-RateLimit-Remaining. Die Integration sollte die Anfragerate steuern, auf 429 reagieren und keine aggressive Wiederholungsschleife ausführen.

API-Artikel für einzelne Objekte

Wählen Sie nach dem Erstellen des Schlüssels und der Verbindungsprüfung den Artikel für die Daten aus, die Sie integrieren möchten:

API - IT-Assets - Computer, Geräte, Software und weitere Inventarelemente mit Feldern, Beziehungen und Dateien.
API - Dokumente - Unternehmensdokumente wie Rechnungen, beschreibende Daten, Dateien und Beziehungen.
API - Kunden / Mitarbeiter - Kunden- oder Mitarbeiterdaten, Kontakte, Organisationsinformationen und unterstützte Beziehungen.
API - Lieferanten - Lieferantenstammdaten und die für dieses Objekt verfügbaren Beziehungen, insbesondere Dokumente und Notizen.
API - Tickets - Service-Desk-Tickets, Lebenszyklus, operative Felder, Dateien und Beziehungen.
API - Changes - geplante Änderungen in der IT-Umgebung, Umsetzungsschritte und Daten zur Prozesskontrolle.
API - Probleme - Probleme mit Ursachenanalyse, Prozessbearbeitung und Verknüpfungen zu anderen Elementen.
API - Releases - Planung und Bearbeitung von Releases, Status und Informationen zu ausgerollten Änderungen.
API - Lösungen - Einträge der Lösungsdatenbank und ihre Problembeziehungen.
API - Notizen - Notizen, Privatsphäre, Anheften, Dateien und Beziehungen zu Datensätzen.
API - Genehmigungen - Genehmigungsprozesse, Entscheidungsdaten, Zuordnungen und Ergebnisverarbeitung.
API - Bestätigungen - Bestätigungen mit erforderlicher Kundenentscheidung sowie deren Dateien und Beziehungen.
API - Aufgaben - Arbeitsaufgaben, Zuordnungen, Status, Beziehungen und Anhänge.
API - Anforderungen - Anforderungen für Produkte oder Dienstleistungen, Fulfillment-Daten, Dateien und Beziehungen.
API - Arbeitszeiten - Zeiteinträge zu einem Ticket, Change, Problem, Release oder einer Arbeitsaufgabe.

Kurze Checkliste vor dem Produktivstart

Erstellen Sie für jede Integration einen eigenen Schlüssel und vergeben Sie nur die benötigten Berechtigungsbereiche.
Speichern Sie Client ID und Client Secret in einem Secret Store, nicht in einem Repository oder in an den Browser ausgeliefertem Code.
Wählen Sie eine Gültigkeitsdauer, die zur Verwaltung der Integration passt.
Verwenden Sie in der Produktion HTTPS und eine vom Integrationsserver erreichbare Unternehmensadresse.
Protokollieren Sie requestId, HTTP-Status und Fehlercode, maskieren Sie aber das Client Secret.
Behandeln Sie Pagination, Limits, 429, ETag und sichere Wiederholungen.

Wenn diese Punkte erfüllt sind, öffnen Sie den Artikel des gewünschten Objekts. Dort finden Sie die passenden Pfade, Felder und Beispiele für die jeweilige Datenart.