API & CLI

Organisationsinhaber und Security-Admins legen API-Schlüssel unter Einstellungen → Workspace & API → API-Schlüssel an (bestätigte E-Mail-Adresse erforderlich). Ein Schlüssel wird einmal angezeigt, beginnt mit erppf_live_ und ist an seine Organisation gebunden. Senden Sie ihn im Header X-Api-Key.

Der Zugriff ist standardmäßig gesperrt: Jede Route, die API-Schlüssel aufrufen dürfen, verlangt genau einen bestimmten Scope, und Routen ohne Scope bleiben API-Schlüsseln verschlossen. In der Web-App angelegte Schlüssel erhalten projects:read, analyses:read, analyses:run, findings:read und reports:read. Die übrigen Scopes — projects:write, findings:write, landscapes:read, landscapes:write, dashboard:read, webhooks:manage und changes:propose — lassen sich beim Anlegen eines Schlüssels über die API vergeben. Die Verwaltung von API-Schlüsseln, Mitgliedern, Konto, Abrechnung, Single Sign-on und SCIM, Datenaufbewahrung und Audit-Log erfordert immer eine interaktive Anmeldung.

Scope-Katalog, Ablauf, Widerruf und Anfragelimits beschreibt API-Schlüssel & Scopes.

Alle Endpunkte liegen unter /api/v1. Typischer Automatisierungsablauf:

POST /api/v1/projects                              Projekt anlegen
POST /api/v1/projects/{projectId}/files            Artefakt hochladen (Multipart-Feld "file")
POST /api/v1/analyses                              {"projectId", "engineTypes": [...], "fileIds": [...]}
GET  /api/v1/analyses/{analysisId}                 abfragen bis COMPLETED / FAILED / PARTIAL
GET  /api/v1/findings?projectId={projectId}        Befunde mit Evidenz
POST /api/v1/projects/{projectId}/analyses/{analysisId}/export   {"format": "PDF"}

Exportformate: PDF, XLSX, CSV, JSON_BUNDLE, HTML_OFFLINE, ZIP_ALL. Die vollständige, generierte OpenAPI-Referenz ist unten verlinkt.

Die CLI (Paket @erppreflight/cli, Node.js 18 oder neuer) nutzt dieselbe API mit einem API-Schlüssel. Richten Sie sie mit --api-url oder ERP_PREFLIGHT_API_URL auf Ihre Instanz (z. B. https://api.example.com); login prüft den Schlüssel und speichert ihn in einer nur für Sie lesbaren Konfigurationsdatei:

erp-preflight login --key erppf_live_… --api-url https://api.example.com
erp-preflight status
erp-preflight project create --name "S/4HANA 2023 Upgrade" --release S4H_2023
erp-preflight upload <projectId> ./exports/billing_opd.xml
erp-preflight analyze <projectId> --engines OPD_GUARD --wait --fail-on BLOCKER,CRITICAL
erp-preflight findings <projectId> --severity CRITICAL
erp-preflight report export <projectId> <analysisId> --format PDF --out report.pdf
erp-preflight report download <analysisId> --out bundle.zip

Uploads durchlaufen dieselben serverseitigen Prüfungen wie in der Web-App (Magic Bytes, Malware-Scan, Schwärzung von Geheimnissen bei Textformaten), Analysen laufen mit denselben deterministischen Engines. project create braucht einen Schlüssel mit projects:write, den in der Web-App angelegte Schlüssel nicht haben. analyze clean-core|api-diff|mfs <pfad…> --project <id> lädt lokale Dateien hoch und startet die passende Engine. Mit --wait --fail-on endet die CLI mit Exit-Code 3, wenn Befunde der aufgeführten Schweregrade existieren — als Qualitätstor in CI. --json liefert maschinenlesbare Ausgabe. Exit-Codes: 0 ok, 1 Fehler, 2 Aufruf/Authentifizierung, 3 Qualitätstor verletzt. Details: CLI und CI-Integration.

POST /api/v1/mcp ist ein JSON-RPC-2.0-Endpunkt mit den Model-Context-Protocol-Methoden tools/list und tools/call (Tools wie search_knowledge, get_findings und explain_finding); den Handshake initialize implementiert er nicht. Für Agenten, die einen lokalen Befehl erwarten, enthält das CLI-Paket den stdio-MCP-Server erp-preflight-mcp; seine Tools tragen das Präfix erppreflight_ (z. B. erppreflight_list_projects und erppreflight_search_knowledge). Tools, Scopes und Konfiguration beschreibt MCP-Server.