Optimus CLI

Die CLI kennt zwei Hauptbefehle: check prüft USt-IDs gegen die Optimus API und schreibt eine Ergebnis-CSV. import legt Stammdaten in der WebApp an oder aktualisiert bestehende Einträge.

Voraussetzungen

optimus.exe ist als self-contained Single-File publiziert - die .NET 8 Runtime ist direkt in die EXE eingebettet. Auf dem Zielrechner muss nichts installiert werden. Einfach die EXE in einen beliebigen Ordner legen und ausführen.

Betriebssystem

Die CLI ist für Windows x64 gebaut. Windows 10 / Windows Server 2019 oder neuer wird empfohlen.

Netzwerk

Die CLI benötigt ausgehenden HTTPS-Zugriff (Port 443) auf:

Authentifizierung

Alle API-Aufrufe benötigen einen Bearer-Token. Den Token erstellt ihr in der WebApp unter Einstellungen → API-Token generieren.

Den Token könnt ihr auf drei Wegen übergeben - am sichersten ist die Umgebungsvariable:

Konfigurationspriorität

Wenn dieselbe Option an mehreren Stellen definiert ist, gilt diese Reihenfolge - links gewinnt immer:

check - USt-IDs prüfen

Liest eine CSV-Datei (oder alle CSVs in einem Ordner), prüft jede USt-ID über die Optimus API und schreibt eine Ergebnis-CSV mit Status und optionalen Korrekturen.

optimus check <pfad> [optionen]

# Einfache Prüfung
optimus check kunden.csv --map mapping.yml --token eyJ...

# Mit PDF-Prüfbericht (digital signiert)
optimus check kunden.csv --map mapping.yml --token eyJ... --pdf --sign --pdf-dir ./evidence

import - Stammdaten importieren

Liest eine CSV und legt für jede Zeile einen Stammdateneintrag in der WebApp an (POST) oder aktualisiert bestehende Einträge (PUT) - abhängig vom gewählten Duplikat-Modus.

optimus import <pfad> [optionen]

# Import mit Overwrite, matchKey aus ustId + PLZ
optimus import C:\optimus\import --map mapping.yml --token eyJ...

Allgemeine Optionen

Diese Optionen gelten für beide Befehle: check und import.

Basis

Ausgabe & Debugging

Spalten-Mapping (alternativ zur YAML)

CSV-Format (Eingabe)

CSV-Format (Ausgabe)

Optionen - nur check

PDF-Prüfbericht

Prüfverhalten

Benachrichtigung

Optionen - nur import

YAML - columns

Mappt die Spaltennamen eurer CSV auf die internen Felder der Optimus API. Gilt für check und import. Nur ustId ist Pflicht.

# mapping.yml
columns:
  ustId:              "UStIdNr"        # Pflicht
  name:               "Bezeichnung"
  street:             "Strasse"
  zip:                "PLZ"
  city:               "Ort"
  externalReference:  "Kontonummer"   # z.B. Kunden-Nr. aus ERP

YAML - input

Steuert wie die Eingabe-CSV eingelesen wird. Alle Felder optional - Auto-Detection greift wenn nichts definiert ist.

input:
  delimiter:        ";"          # ";" | "," | "\t" | "|"
  encoding:         "utf-8"      # oder "windows-1252" für Windows-Exporte
  hasHeader:        true
  skipRows:         0
  trimWhitespace:   true         # Leerzeichen an Feldrändern entfernen

YAML - output (nur check)

Steuert Format und Inhalt der Ergebnis-CSV.

output:
  delimiter:        ";"
  encoding:         "utf-8"
  bom:              true         # Empfohlen für Excel-Kompatibilität
  columns:                       # Welche Spalten sollen ausgegeben werden?
    - row
    - ust_id
    - ust_id_status
    - name
    - name_status
    - name_corrected
    - overall
    - checked_at
    - external_ref

Verfügbare Spalten-Shortcuts: all (alle Spalten), all_originals, all_statuses, all_corrections.

YAML - import (nur import)

Duplikat-Verhalten und Standardwerte für neu angelegte Einträge.

import:
  onDuplicate:      "overwrite"  # "append" | "overwrite" | "skip"
  matchKey:                      # Schlüssel für Duplikat-Erkennung
    - ustId                        # Pflicht
    - zip                          # optional: + PLZ, Straße, Stadt, ext. Ref.
  defaults:
    checkEnabled:     true        # Monitoring in der WebApp aktivieren
    emailNotification: false
    note:             "CLI Import"

YAML - folder

Konfiguration für den Ordner-Modus. Wird automatisch aktiv wenn <pfad> ein Ordner ist.

folder:
  pattern:              "*.csv"
  minAge:               0            # Min. Dateialter in Sekunden vor Verarbeitung
  onDuplicate:          "skip"       # Wenn Ergebnis-CSV schon existiert
  retryFromProcessing:  true         # Abgebrochene Läufe automatisch fortsetzen
  cleanupDoneAfterDays: null         # null = done-Ordner nie leeren

YAML - filter

Zeilen aus der CSV herausfiltern bevor sie verarbeitet werden.

filter:
  skipEmptyUstId:   true    # Zeilen ohne USt-ID werden übersprungen (SKIPPED)
  skipPattern:      "^#"    # Regex auf das USt-ID-Feld - hier: Kommentarzeilen

Duplikat-Logik (import)

Der matchKey bestimmt wie ein „Duplikat" erkannt wird - ein vorhandener Eintrag in der WebApp gilt als Treffer wenn alle matchKey-Felder übereinstimmen (case-insensitive).

Ordner-Modus

Wenn <pfad> ein Ordner ist, verarbeitet die CLI alle CSVs darin automatisch nacheinander. Die Dateien werden dabei in Unterordner verschoben:

Exit-Codes

Nützlich für Scripting und automatisierte Pipelines.

Beispiele

USt-ID Prüfung - minimal

optimus check kunden.csv --map mapping.yml --token eyJ...

USt-ID Prüfung - mit PDF und Signierung

optimus check kunden.csv --map mapping.yml --token eyJ... \
  --pdf --sign --pdf-dir ./evidence

Testumgebung mit detailliertem Output

optimus import C:\optimus\import --map mapping.yml --token eyJ... --env test -v

Import im Ordner-Modus (Token via Umgebungsvariable)

set OPTIMUS_TOKEN=eyJ...
optimus import C:\optimus\import --map mapping.yml

Dry-Run - nur Mapping testen, kein API-Call

optimus import kunden.csv --map mapping.yml --dry-run -v

Minimale YAML für Import (Overwrite, matchKey: ustId + PLZ)

columns:
  ustId:             "UStIdNr"
  name:              "Bezeichnung"
  street:            "Strasse"
  zip:               "PLZ"
  city:              "Ort"
  externalReference: "Kontonummer"

input:
  delimiter: ";"

import:
  onDuplicate: overwrite
  matchKey: [ustId, zip]
  defaults:
    checkEnabled: true