Quickstart für Entwickler¶

Ziel: in weniger als zehn Minuten den ersten authentifizierten API-Aufruf gegen Expecto absetzen, eine Session erstellen und denselben Ablauf über die MCP-Oberfläche durchlaufen. Sie konfigurieren hier weder Projekte noch Entities — das ist der Pfad der Projektverantwortlichen. Wir gehen davon aus, dass das bereits eingerichtet ist und Sie einen API-Schlüssel haben.

Voraussetzungen¶

Ein API-Schlüssel — wird vom Organisations-Administrator unter Org-Einstellungen → API-Schlüssel ausgestellt. Behandeln Sie ihn wie ein Passwort; er gewährt Zugriff auf alles, was Ihre Organisation sehen kann. Wenn Sie keinen haben, fragen Sie die Person, die Ihre Organisation eingerichtet hat. Die API-Schlüssel-Anleitung der Org-Admins beschreibt die Ausstellung.
Ihre Expecto-Basis-URL. Für die gehostete Instanz ist das https://expecto-app.onrender.com. Ersetzen Sie unten EXPECTO_BASE_URL durch die Instanz, die Sie erhalten haben.
Ein Terminal mit curl und optional Python ≥ 3.10 für den MCP-Schritt. Jeder MCP-kompatible Client (Claude Desktop, Claude Code, Cursor, ein eigener Client) eignet sich ebenfalls.

export EXPECTO_BASE_URL="https://expecto-app.onrender.com"
export EXPECTO_API_KEY="hier-den-schluessel-einsetzen"

Alle folgenden Beispiele setzen voraus, dass diese beiden Variablen gesetzt sind.

Schritt 1 — Verbindung prüfen¶

Rufen Sie den Endpunkt /api/me auf. Er gibt Organisation und Mitgliedschaft hinter Ihrem API-Schlüssel zurück. Wenn das klappt, ist Ihr Schlüssel gültig und Ihr Netzwerk erreicht die API.

curl -sS \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/me" | jq .

Sie sollten ein JSON-Objekt mit Benutzer, Organisation und Rolle sehen. 401 bedeutet, dass der Schlüssel falsch oder widerrufen ist; 403 heißt meist, dass der Schlüssel zu einer anderen Organisation gehört als die angefragte Ressource.

Die API interaktiv erkunden

Jeder unten verwendete Endpunkt ist in der interaktiven Swagger-UI unter <EXPECTO_BASE_URL>/api/docs dokumentiert (ReDoc unter /api/redoc). Klicken Sie auf Authorize, fügen Sie Ihren API-Schlüssel ein und testen Sie Aufrufe direkt im Browser.

Expecto Swagger-UI unter /api/docs

Schritt 2 — Ihre Projekte auflisten¶

Jeder Empfangs-Use-Case lebt innerhalb eines Projekts. Listen Sie diejenigen auf, die Ihr Schlüssel sehen kann:

curl -sS \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/projects" | jq '.items[] | {id, name}'

Wählen Sie eines aus und speichern Sie die ID — die meisten weiteren Aufrufe brauchen einen Projektkontext, direkt oder über eine Session:

export PROJECT_ID="..."

Schritt 3 — Session anlegen und Datei hochladen¶

Eine Session ist ein Lieferakt: ein Lieferant + ein Zeitraum + ein Satz Dateien durch die Pipeline. Um Daten per API einzureichen, erstellen Sie eine Session, hängen Dateien an und stoßen die Pipeline an.

Anlegen:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$PROJECT_ID"'",
    "data_contract_id": "PUT_CONTRACT_ID_HERE",
    "period_label": "2026-06"
  }' \
  "$EXPECTO_BASE_URL/api/sessions" | jq .

Speichern Sie die zurückgegebene id als SESSION_ID. Laden Sie dann eine Datei für die im Vertrag definierte Quellrolle hoch:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -F "source_role=buchungsdatei" \
  -F "file=@/pfad/zur/datei.csv" \
  "$EXPECTO_BASE_URL/api/sessions/$SESSION_ID/files" | jq .

Pipeline starten (asynchron):

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/sessions/$SESSION_ID/run"

Antwort 202 Accepted mit einer job_id. Pollen Sie die Session auf den Status — parse → transform → check:

curl -sS \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/sessions/$SESSION_ID" | jq '{status, health, stages}'

Sobald health auf ready steht, hat die Validierung bestanden und die Session kann confirmed und dann approved werden, um das Exportpaket zu erzeugen.

Schritt 4 — Dasselbe über MCP¶

Expecto stellt einen MCP-Server unter <EXPECTO_BASE_URL>/mcp/ bereit. Die Authentifizierung erfolgt über denselben X-API-Key-Header.

Fügen Sie ihn in Ihrem MCP-Client hinzu. Für Claude Desktop bearbeiten Sie claude_desktop_config.json:

{
  "mcpServers": {
    "expecto": {
      "url": "https://expecto-app.onrender.com/mcp/",
      "transport": "http",
      "headers": {
        "X-API-Key": "ihr-api-schluessel-hier"
      }
    }
  }
}

Nach dem Verbinden stehen Werkzeuge wie list_projects, get_project, create_session, upload_session_file, run_session_pipeline, list_sessions, get_session, get_session_violations zur Verfügung. Der Ablauf aus Schritt 3 wird zu:

list_projects → eines auswählen
create_session(project_id, data_contract_id, period="2026-06")
upload_session_file(session_id, source_role="buchungsdatei", file=...)
run_session_pipeline(session_id)
get_session(session_id)

Die meisten KI-Assistenten verketten diese Aufrufe selbständig, sobald das Ziel formuliert ist ("Juni-Daten für IntReal in Projekt X einreichen") — das ist der Hauptgrund, MCP statt REST für menschen-gesteuerte Einreichungen zu nutzen.

Wohin als Nächstes¶

Wenn Sie…	Hier weitermachen
Jeden REST-Endpunkt nachschlagen wollen	REST-API-Referenz — Coming soon. Interaktive Spezifikation unter /api/docs auf Ihrer Instanz
Alle MCP-Werkzeuge durchsehen	MCP-Werkzeugkatalog
Das zugrundeliegende Domain-Modell verstehen	Konzepte
Einen reicheren "Daten einreichen"-Ablauf aus CI	CI und Automatisierung einrichten — Coming soon.
Ergebnisse nachgelagert an BuiltAPI weitergeben	Nachgelagert mit BuiltAPI integrieren — Coming soon.