API & Integrationen

Die Integration-API deckt nahezu den gesamten Funktionsumfang der Anwendung ab: KI-Systeme, Risikobewertung, Checklisten, Dokumentation, Governance, Assurance, Controls, Incident Management, die komplette DSGVO-Suite, Model Registry, Vendor Register, Legal Logic, Export und Administration. Diese Seite erklärt die Regeln, die für alle diese Bereiche gleichermaßen gelten. Die vollständige Endpunktreferenz liegt in Ihrer Instanz unter /api/docs, der Einstiegsleitfaden unter /api/guide.

Die vier Grundregeln

Authentifizierung

• Header X-API-Key: sk_live_… – oder alternativ Authorization: Bearer sk_live_…
• Basis-URL ist Ihre eigene Organisationsdomain plus /api/v1. Beispiele aus der In-App-Dokumentation funktionieren dadurch ohne Anpassung.
• Die API ist für Server-zu-Server-Aufrufe gedacht. Ein Key gehört nie in eine Webseite: Cross-Origin-Anfragen aus fremden Ursprüngen erhalten keine CORS-Freigabe und werden vom Browser blockiert. Server, CLI und Jobs betrifft das nicht.
• Referenz und Leitfaden antworten auf denselben Key: Sie können die OpenAPI-Spezifikation per Skript unter /api/docs-json abholen, ohne Browsersitzung.

Limits

Beide Limits gelten gleichzeitig und kumulativ. Ein Key kann sein Stundenbudget also nicht in einem einzigen Schwall verbrauchen.

Fehlercodes

Jeder Fehler kommt im selben JSON-Umschlag mit Statuscode, UTC-Zeitstempel, Pfad und Meldung – auch bei Download-Endpunkten. Ein fehlgeschlagener PDF- oder ZIP-Abruf antwortet als JSON, nie mit dem Medientyp des Erfolgsfalls.

Schreibsemantik, die man kennen sollte

• PUT und PATCH führen beide eine Teiländerung durch: Ein Feld, das Sie weglassen, behält seinen Wert. Sie müssen also nie das vollständige Objekt senden.
• Ein Feld leeren geht über null – sofern das Feld leer sein darf. Auf einem Pflichtfeld ist null kein Löschweg.
• Listenfelder werden ersetzt, nicht ergänzt. Eine gesendete Liste überschreibt die gespeicherte; eine leere Liste löscht sie; ein weggelassenes Feld lässt sie unverändert.
• Unbekannte Felder im Anfragekörper werden abgelehnt statt ignoriert – ein Tippfehler im Feldnamen scheitert, statt den Wert still zu verschlucken.
• Verweise auf andere Datensätze müssen auflösbar sein. Eine ID, die nicht zu Ihrer Organisation gehört, lässt den gesamten Aufruf mit 404 scheitern – gespeichert wird nichts.
• Datumsangaben sind ISO-8601-Kalendertage. Ein Datum, das es nicht gibt (etwa der 30. Februar), wird abgelehnt und nicht stillschweigend verschoben.

Geschäftsregel-Fehler unter 400

Nicht jeder 400 ist ein Tippfehler. Lehnt die App einen Aufruf ab, weil ein Ablauf es nicht zulässt (ein Statuswechsel ist nicht erlaubt, ein Gate ist zu, ein Nachweis fehlt), kommt derselbe Umschlag mit error: „Business Rule“. Im Feld errors steht dann ein Eintrag mit constraints: [Regel-ID], gegebenenfalls field (etwa status) und messages mit dem lesbaren Text.

Verzweigen Sie auf die Regel-ID, nicht auf den Text. Die vollständige Liste veröffentlicht die OpenAPI-Spezifikation; Beispiele sind rule.approval_required, rule.annex_iv_transition, rule.checklist_justification_required, rule.governance_workflow_not_approved, rule.incident_status_transition und ai_intake.unreviewed_sections.

Freigabe-Sperre: rule.approval_required

Hat Ihre Organisation für einen Objekttyp einen mehrstufigen Freigabe-Workflow eingerichtet, kann die API den Abschlussstatus nicht mehr direkt setzen:

• Ein Statuswechsel in den Abschlussstatus (etwa ein Anhang-IV-Dossier auf APPROVED oder ein Lieferant auf FREIGEGEBEN) braucht eine abgeschlossene, noch nicht verbrauchte Freigabe. Fehlt sie, antwortet die API mit 400 und rule.approval_required; die Meldung nennt Objekttyp und Zahl der Stufen.
• Ein Datensatz, der direkt im Abschlussstatus angelegt werden soll, wird aus demselben Grund abgelehnt. Legen Sie ihn darunter an und lassen Sie ihn freigeben.
• Jede Freigabe wird genau einmal verbraucht. Für einen erneuten Abschluss ist eine neue Freigabe nötig.

Nur mit Anmeldung, nicht per API-Key

Manche Handlungen sind persönliche Entscheidungen. Ein API-Key handelt im Namen der Person, die ihn angelegt hat: genau das soll das Vier-Augen-Prinzip verhindern.

Paging: uneinheitlich

Die API hat kein einheitliches Paging. Die meisten Listen liefern alles auf einmal; wenige Endpunkte begrenzen:

• Ohne Paging, vollständige Liste: zum Beispiel KI-Systeme (neueste zuerst) und Webhooks.
• page und limit: Einwilligungsnachweise.
• limit und offset: System-Log.
• Nur limit: DSGVO-Audit-Trail im Dashboard (Standard 100, höchstens 500).
• Prüfen Sie im Zweifel die Beschreibung des Endpunkts in der OpenAPI-Referenz und planen Sie für große Organisationen mit vollständigen Listen.

Sprache der Fehlermeldungen

Meldungstexte richten sich nach dem Header Accept-Language (Deutsch, Englisch, Spanisch, Französisch); ohne Header antwortet die API auf Englisch. Einige technische Meldungen sind nicht übersetzt und erscheinen immer auf Englisch. Regel-IDs und Feldnamen sind sprachunabhängig. Darauf verzweigen Sie.

Webhooks

• Zustellung per POST mit JSON-Körper { id, type, timestamp, data } und den Headern X-SimpleAct-Event (Ereignistyp) und X-SimpleAct-Signature.
• Die Signatur ist ein HMAC-SHA256 über den Körper, hex-kodiert, mit dem Webhook-Secret als Schlüssel. Prüfen Sie sie gegen den unveränderten Körper.
• Ohne eigenes Secret erzeugt SimpleAct eines mit 64 Zeichen; ein eigenes muss mindestens 16 Zeichen haben. Speichern Sie es beim Anlegen sicher. Die Anzeige des Secrets wird auf den Moment des Anlegens beschränkt.
• Kein automatischer Neuversuch: Eine fehlgeschlagene Zustellung wird nicht wiederholt. Nach zehn Fehlschlägen in Folge wird der Webhook deaktiviert und lässt sich über die API nicht wieder einschalten.
• Ziele in privaten oder lokalen Netzen sind gesperrt. Eine Registrierung lässt sich nicht ändern; für eine neue URL oder neue Ereignisse löschen und neu anlegen.
• Ereigniskatalog: Derzeit gibt es nur die Testzustellung webhook.test, mit der Sie Ihre Empfängerseite prüfen. Fachliche Ereignisse kommen schrittweise hinzu; nur Typen aus dem Katalog lassen sich abonnieren.

SCIM und MCP

Was die API bewusst nicht abdeckt

Diese Bereiche fehlen nicht, sie sind ausgeschlossen – jeweils aus einem konkreten Grund.

• Abrechnung und Abonnements: Zahlungsdaten werden ausschließlich über den geprüften Zahlungsablauf geändert, damit kein Integrationsfehler zu falschen Buchungen führt.
• Die API-Key-Verwaltung selbst: Keys können sich nicht gegenseitig erzeugen oder verlängern. Das Anlegen bleibt eine bewusste Handlung eines angemeldeten Administrators.
• Sitzungsgebundene Abläufe – Anmeldung, SSO, Passwort-Reset, eigenes Profil, Organisationswechsel. Sie beziehen sich auf den eingeloggten Menschen, wofür ein langlebiger Key kein sinnvolles Gegenstück ist.
• Plattformweite Super-Admin-Funktionen. Für API-Keys sind sie nicht erreichbar.