Zum Hauptinhalt springen

Erste Schritte

Diese Seite zeigt den kürzesten sicheren Weg von einer Eingabe-CSV zu einer Ergebnis-CSV.

Die CLI ist für Systeme gedacht, die CSV-Dateien exportieren können, aber keine direkte API-Verbindung herstellen können. Nach der Einrichtung kann Ihr ERP oder Job-Scheduler Dateien exportieren, die CLI kann sie automatisch validieren, und die Ergebnis-CSV kann wieder in Ihren Prozess importiert werden.

Voraussetzungen​

Sie benötigen:

  • Den Befehl optimus, installiert und in Ihrem Terminal verfügbar.
  • Ein Optimus API Token.
  • Eine CSV-Datei mit einer USt-IdNr.-Spalte.
  • Eine Mapping-Datei, die der CLI sagt, welche CSV-Spalten verwendet werden sollen.

Prüfen Sie, ob die CLI verfügbar ist:

optimus --version

Mapping-Datei Erstellen​

Erstellen Sie mapping.yml neben Ihrer CSV-Datei:

columns:
  vatId: "VatId"
  name: "CompanyName"
  street: "Street"
  zip: "PostalCode"
  city: "City"

customColumns:
  customer_number: "CustomerNumber"

input:
  delimiter: ";"
  encoding: "utf-8"
  hasHeader: true

output:
  delimiter: ";"
  encoding: "utf-8"
  bom: true

defaults:
  checkType: standard
  retryDuration: None

Nur columns.vatId ist erforderlich. Wenn Name, Straße, PLZ und Stadt angegeben sind, prüft Optimus jede Komponente gegen die zuständigen staatlichen Stellen.

customColumns werden in die Ergebnis-CSV kopiert. Sie werden nicht an die Validierungs-API gesendet.

CSV-Datei Vorbereiten​

Für das Mapping oben kann die Eingabe-CSV so aussehen:

VatId;CompanyName;Street;PostalCode;City;CustomerNumber
DE284700631;Optimus Software GmbH;Tal 44;80331;München;C-1001
DE000000000;Example GmbH;Main Street 1;10115;Berlin;C-1002

Token Konfigurieren​

Verwenden Sie eine Umgebungsvariable, damit das Token nicht in der Befehlshistorie erscheint:

export OPTIMUS_TOKEN="<token>"

Unter Windows PowerShell:

$env:OPTIMUS_TOKEN = "<token>"

Zuerst Einen Dry Run Ausführen​

Dry-run-Modus validiert Datei und Mapping, ohne die API aufzurufen:

optimus check customers.csv --map mapping.yml --standard --dry-run

Verwenden Sie dies vor echter Validierung, wenn Sie eine Mapping-Datei erstellen oder ändern. Die Ausgabe zeigt die ersten 5 prüfbaren Zeilen, die an die API gesendet würden. So können Sie bestätigen, dass die Spaltenzuordnungen die erwarteten CSV-Werte auswählen.

Validierung Ausführen​

Führen Sie eine Standardprüfung aus:

optimus check customers.csv --map mapping.yml --standard

Führen Sie eine qualifizierte Prüfung aus:

optimus check customers.csv --map mapping.yml --qualified

Der Prüftyp kann auch aus defaults.checkType in der Mapping-Datei stammen. Wenn weder der Befehl noch die Mapping-Datei ihn setzt, meldet die CLI einen Konfigurationsfehler.

Ergebnis Prüfen​

Für customers.csv ist der Standard-Ergebnispfad:

customers_result.csv

Das Ergebnis enthält die eingegebene USt-IdNr., Validierungsstatus, Feldabgleich-Status, von der API zurückgegebene ermittelte Werte, Custom Columns aus Ihrem Mapping und checked_at.

Beispielergebnis:

row;customer_number;vat_id;vat_id_status;name;name_status;name_determined;street;street_status;street_determined;zip;zip_status;zip_determined;city;city_status;city_determined;checked_at
1;C-1001;DE284700631;Valid;Optimus Software GmbH;Match;;Tal 44;Match;;80331;Match;;München;Match;;2026-05-13T09:15:00Z
2;C-1002;DE000000000;Invalid;Example GmbH;;;Main Street 1;;;10115;;;Berlin;;;2026-05-13T09:15:01Z

Der Lauf schreibt außerdem ein Support-Log, sofern Sie nicht --no-log verwenden.