Quickstart für Projektverantwortliche¶

Ziel: in etwa dreißig Minuten den End-to-End-Empfang von einem Lieferanten aufsetzen und die erste valide Lieferung annehmen. Das Beispiel unten verwendet den FIBU-Import-Fall (deutsche Hausverwaltung). Dieselbe Struktur gilt für jede andere Domäne.

Diese Seite ist bewusst auf hoher Flughöhe — jeder Schritt verweist auf die ausführliche Anleitung. Wenn Sie zuerst das Vokabular brauchen, lesen Sie Konzepte.

Voraussetzungen¶

Ein Organisations-Administrator hat Sie in Ihre Organisation eingeladen, mindestens mit der Rolle Projektverantwortliche.
Sie wissen, in welcher Form die Daten am Ende vorliegen sollen — also welche Spalten das nachgelagerte System erwartet.
Eine Beispieldatei von mindestens einem Lieferanten, damit Sie durchgehend gegen echte Eingaben prüfen können.

Die Konsolen-Verweise unten gehen davon aus, dass Sie an Ihrer Expecto-Instanz angemeldet sind. Die API-Verweise gehen davon aus, dass $EXPECTO_BASE_URL und $EXPECTO_API_KEY gesetzt sind, wie im Entwickler-Quickstart beschrieben.

Schritt 1 — Projekt anlegen¶

Ein Projekt bündelt alles für einen Empfangs-Use-Case: Entities, Verträge, Transformer, Geschäftsregeln, Exporte, Lieferanten.

In der Konsole: Projekte → Create Project. Vergeben Sie einen Namen wie FIBU 2026 und eine kurze Beschreibung. Belassen Sie die Voreinstellungen für Approval Mode (Dual Approval) und Session Creation (Both), sofern Sie keinen Grund für etwas anderes haben.

Dialog „Create Project“ mit Name und Beschreibung

Das neue Projekt erscheint sofort in der Liste:

Projektliste mit dem neu angelegten Projekt FIBU 2026

Oder per API:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "FIBU 2026", "description": "Monatlicher Buchhaltungs-Empfang"}' \
  "$EXPECTO_BASE_URL/api/projects" | jq .

Speichern Sie die zurückgegebene id als PROJECT_ID.

Schritt 2 — Ziel-Entity definieren¶

Eine Entity ist das Schema, in dem Ihre Daten nach der Normalisierung landen — eine Zieltabelle mit Spaltentypen und Zeilen-Validierungsregeln.

In der Konsole: Entities → Add Entity. Nennen Sie es Buchung und geben Sie eine kurze Beschreibung.

Dialog „Create Entity“

Öffnen Sie die Entity und definieren Sie ihre Spalten (z. B. konto Text, betrag Decimal, buchungstext Text, belegdatum Datum). Fügen Sie mindestens eine Validierungsregel hinzu, damit die Pipeline offenkundig fehlerhafte Zeilen ablehnen kann.

Entity-Detailseite mit Schema und Regeln

Beispielregel, in der Ausdruckssprache (was Sie in den Regel-Editor eingeben):

len(konto) == 6 and matches(konto, '^[0-9]+$')

Meldung:

{"en": "Konto must be 6 digits", "de": "Konto muss 6 Ziffern sein"}

Die Plattform übersetzt das im Hintergrund in eine DuckDB-Abfrage zur Suche von Verstößen; siehe Ausdruckssprache (Coming soon.) für die vollständige Operatorenliste und eingebaute Funktionen.

Äquivalent per API. Regeln sind ihrer Entity untergeordnet, daher steht die Entity-ID im Pfad (exportieren Sie sie als ENTITY_ID aus der angelegten Entity). Das Feld expression ist ein vorkompiliertes DuckDB SELECT, das die verletzenden Zeilen zurückgibt:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "konto_6_digits",
    "level": "error",
    "expression": "SELECT * FROM data WHERE LENGTH(TRIM(konto)) != 6 OR konto !~ '\''^[0-9]+$'\''",
    "message": {"de": "Konto muss 6 Ziffern sein"}
  }' \
  "$EXPECTO_BASE_URL/api/entities/$ENTITY_ID/rules" | jq .

Schritt 3 — DataContract verfassen¶

Ein DataContract beschreibt, was ein bestimmter Lieferant zu liefern zusagt — Dateitypen, erwartete Spalten, Rolle jeder Datei. Es ist die Vereinbarung mit dem Lieferanten, unabhängig davon, wie Sie die Daten später transformieren.

In der Konsole: Öffnen Sie im Projekt den Tab Data Contracts und wählen Sie New Data Contract. Vergeben Sie einen Namen wie Hausverwaltung X — FIBU v1 und setzen Sie die Supplier-ID.

Dialog „New Data Contract“

Öffnen Sie den Vertrag und fügen Sie Quellen (Sources) hinzu — eine pro Datei-Rolle. Für FIBU sind das typischerweise zwei:

buchungsdatei (CSV, Semikolon-getrennt, deutsche Kodierung) mit Spalten wie Konto, Betrag, Buchungstext, Belegdatum.
saldendatei (CSV) mit Konto, Saldo.

Die Vertrags-Detailseite hat die Tabs Sources, Revisions und Transformers; die aktuelle Revision ist zunächst ein Entwurf, bis Sie sie aktivieren.

Vertrags-Detailseite mit Tabs Sources, Revisions und Transformers

Hängen Sie pro Quelle ein Frictionless-Table-Schema mit Spaltennamen und Typen an, damit strukturelle Fehler bereits vor der Transformation erkannt werden.

Oder per API:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hausverwaltung X — FIBU v1",
    "supplier_id": "hv-x",
    "project_id": "'"$PROJECT_ID"'"
  }' \
  "$EXPECTO_BASE_URL/api/data-contracts" | jq .

Speichern Sie die id als CONTRACT_ID. Über die Source-Endpunkte unter dem Vertrag (/api/data-contracts/{id}/sources) fügen Sie jede Datei-Rolle hinzu.

Bis Sie ihn aktivieren, bleibt der Vertrag im Zustand draft. Die Aktivierung sperrt ihn als Revision 1 und führt eine Kompatibilitäts- prüfung gegen alle damit verbundenen Transformer aus.

Schritt 4 — Transformer bauen¶

Ein Transformer bildet die Quellen eines Vertrags auf eine Entity ab. Jede Spalte der Entity bekommt einen Mapping-Ausdruck — einen DuckDB-Ausdruck, der auf ein Quellfeld zeigt, mit der Möglichkeit, ihn zu bereinigen (TRIM, LPAD, Type-Cast, Wörterbuch-Lookups).

In der Konsole: Im Projekt unter Transformer → Neuer Transformer. Wählen Sie die Entity (Buchung) und die DataContract-Revision. Dann geben Sie pro Quellrolle die Mappings für jede Zielspalte ein:

Zielspalte (Entity)	Mapping (DuckDB-Ausdruck auf die Quelle)
`konto`	`LPAD(TRIM("Konto"), 6, '0')`
`betrag`	`CAST(REPLACE("Betrag", ',', '.') AS DECIMAL(18,4))`
`buchungstext`	`TRIM("Buchungstext")`
`belegdatum`	`STRPTIME("Belegdatum", '%d.%m.%Y')`

Aktivieren Sie den Transformer, sobald seine Mappings jede erforderliche Entity-Spalte abdecken.

Per API sind Transformer ihrem DataContract untergeordnet. Die Mappings stehen in mappings_per_role, geschlüsselt nach Quellrolle:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buchung von Hausverwaltung X v1",
    "data_contract_id": "'"$CONTRACT_ID"'",
    "data_contract_revision": 1,
    "entity_id": "'"$ENTITY_ID"'",
    "mappings_per_role": {
      "buchungsdatei": { "...": "RoleMapping-Objekt" }
    }
  }' \
  "$EXPECTO_BASE_URL/api/data-contracts/$CONTRACT_ID/transformers"

Schritt 5 — Exportformat konfigurieren¶

Setzen Sie im Projekt output_format auf das, was Ihr nachgelagertes System erwartet. Eingebaute Formate: sap_v46 (SAP Interface V4.6), zip_csv (eine CSV pro Entity in einem ZIP), excel_workbook. Das ist der Output, der erzeugt wird, sobald eine Session approved ist.

In der Konsole: in der Projekt-Overview unter Output Format auf Configure klicken. Wählen Sie Formattyp und Optionen (Trennzeichen, Kodierung, Kopfzeile bei CSV-basierten Formaten).

Dialog zur Konfiguration des Output-Formats

Schritt 6 — Datenlieferanten einladen¶

Bevor Sie einem Lieferanten Zugang gewähren, kann niemand Daten einreichen.

In der Konsole: Öffnen Sie im Projekt den Tab Providers und laden Sie einen Lieferanten ein. Wählen (oder erstellen) Sie die Lieferanten-Organisation und gewähren Sie Zugriff auf dieses Projekt und diesen konkreten Vertrag. Der Lieferant erhält eine Einladungs-E-Mail und sieht beim Login eine zweckgebundene Einreichungsansicht.

Projekt-Tab „Providers“

Schritt 7 — Erste Session prüfen¶

Sobald der Lieferant Dateien hochlädt, erscheint eine Session im Tab Sessions des Projekts, verfolgt nach Health und Pipeline-Stufe. Die Pipeline durchläuft automatisch parse → transform → check (oder per Trigger, je nach Projektkonfiguration).

Projekt-Tab „Sessions“ mit Spalten Health und Stage

Öffnen Sie eine Session und prüfen Sie:

status und health — in welcher Phase befinden wir uns und ist irgendetwas blockiert?
Tab Verstöße (Violations) — Liste der abgelehnten Zeilen je Regel.
Vorschau — die transformierten Entity-Zeilen, so wie sie nachgelagert ankommen würden.

Wenn alles passt, bestätigen Sie die Session und dann freigeben. Die Freigabe erzeugt das Exportpaket im konfigurierten Format.

Wenn etwas nicht passt, können Sie:

Die Session kommentieren, sodass der Lieferant es sieht.
Sie ablehnen und eine erneute Einreichung verlangen.
Ein Mapping im Transformer korrigieren (erzeugt eine neue Revision) und die Pipeline gegen dieselben Dateien neu laufen lassen.

Wohin als Nächstes¶

Wenn Sie…	Hier weitermachen
Mehr Validierungsregeln sicher verfassen wollen	Golden Sessions für sichere Regeländerungen nutzen — Coming soon.
Abstimmung (Reconciliation) über Dateien hinweg hinzufügen wollen	Abstimmung einrichten — Coming soon.
Einen reicheren Transformer mit Wörterbuch-Lookups bauen wollen	Transformer bauen — Coming soon.
Mehrere Vertragsrevisionen verwalten wollen	Vertrags-Revision aktivieren — Coming soon.
Das Domain-Modell durchgehend verstehen wollen	Konzepte