Kommandozeile & Beispielprojekte

Beide SDKs bringen etwas Lauffähiges mit, um Anträge ohne eigenen Code zu senden, abzuholen und zu prüfen — für Smoke-Tests, für die Gegenseite beim Entwickeln und für Operations. Java liefert eine echte Kommandozeile, deren Kommandobaum der SDK-Fassade folgt; .NET liefert ein Beispielprojekt mit CLI-Einstieg, das gleichzeitig Code-Vorlage ist.

Nicht für den Produktivbetrieb

Beide Werkzeuge dienen zum Testen und zum Anbinden. Sie sind kein Ersatz für ein Fachverfahren.

Einsatzszenarien

Die Gegenseite simulieren: Wer ein Verwaltungssystem entwickelt, sendet mit fit-connect online-service send Testanträge; wer einen Onlinedienst entwickelt, holt mit fit-connect organisation receive ab und nimmt an.
Vor dem ersten Antrag prüfen: fit-connect doctor durchleuchtet Credentials, Zustellpunkt, Schlüssel und Netz — dieselbe Diagnose wie sdk.diagnose(…) im Java-SDK.
Skripte und Pipelines: Alle Ergebnisse gehen nach stdout, mit --json maschinenlesbar; Diagnostik nach stderr. Exit-Codes: 0 Erfolg, 1 Plattform-/SDK-Fehler, 2 Bedienfehler, 3 Konfigurationsproblem.

Java: `fit-connect`

Das Java-CLI (Modul cli im Repository egov-modules) wird als runnable JAR fit-connect-cli.jar ausgeliefert; die Version entspricht dem SDK (4.0.0-rc.1). Der Kommandobaum folgt den Rollen des SDKs — was Sie hier lernen, gilt genauso in der Java-API:

fit-connect [-c config.yml] [--json] [-v]
  organisation     als Zustellpunkt einer Verwaltung handeln (Typ A/B)
      awaiting · receive · reject · send · batch · cases {list, events, log}
  online-service   als Zustellpunkt eines Onlinedienstes handeln (Typ C)
      send · batch · awaiting-replies · receive · cases {list, events, log}
  directory        Zustellpunkte finden, ohne Authentifizierung
      for-service · for-process-message · key · routes · areas
  destinations     die Zustellpunkte dieses Clients einsehen
      show · list · limits · keys
  keygen           JWK-Schlüsselpaare für TEST erzeugen (und eine config.yml)
  doctor           Selbstdiagnose: Token, Scopes, Status, Schlüssel, Netz, Limits
  generate-completion   Shell-Completion (bash, zsh)

Voraussetzungen

Java Runtime 21+
Eine config.yml mit Credentials, Umgebung und dem CLI-eigenen identity-Block

Aufruf und Konfiguration

# Standard: liest config.yml aus dem aktuellen Verzeichnis
java -jar fit-connect-cli.jar organisation awaiting

# Mit explizitem Pfad, JSON-Ausgabe und INFO-Log auf stderr
java -jar fit-connect-cli.jar -c /etc/fit-connect/config.yml --json -v organisation awaiting

# Shell-Alias, wie im Rest dieser Seite verwendet
alias fit-connect='java -jar /opt/fit-connect/fit-connect-cli.jar'

Neben den üblichen SDK-Einstellungen braucht die config.yml den Block identity, der den Zustellpunkt benennt, als der das CLI handelt:

credentials:
  clientId: "your-client-id"
  clientSecret: "your-client-secret"
environment: "TEST"   # TEST | STAGE | PROD

identity:
  destinationId: "1b7d1a24-a6c8-4050-bb71-ae3749ec432f"
  keys:                              # weglassen, um nur zu senden
    decryptionKey: "/path/to/decryption-private.jwk"    # oder decryptionKeys: [neu, alt]
    signatureKey:  "/path/to/signature-private.jwk"

keygen --with-config schreibt genau diese Datei. Pro Aufruf lässt sich identity mit --as-destination-id, --as-decryption-key und --as-signature-key überschreiben. Die Datei hat dasselbe Format wie die YAML für FitConnectSdk.fromConfigYaml(…) — nur der Block identity ist CLI-spezifisch; im SDK übergeben Sie Zustellpunkt und Schlüssel stattdessen an sdk.organisation(…)/sdk.onlineService(…). Einen Builder gibt es für die CLI naturgemäß nicht; sdkSettings (Timeouts, Retries, Chunking) wirkt aber auch hier.

Das Java-SDK nimmt Schlüssel am Aufruf entgegen, nicht in der SDK-YAML (Regel 4 des Rollenmodells). Das CLI braucht sie aber irgendwo — deshalb hat es einen eigenen identity-Block, der nur das CLI kennt. Ihre eigene Anwendung übernimmt diesen Teil aus dem Vault; DestinationKeysDeserializer.fromNode(…) ist derselbe Baustein, falls Sie ein solches YAML-Element auch selbst anbieten wollen.

Organisation Verwaltung

fit-connect organisation awaiting                                        # was liegt an?
fit-connect organisation receive <submission-id> --target /srv/inbox --accept
fit-connect organisation receive --all --target /srv/inbox               # alles abholen, nicht annehmen
fit-connect organisation reject <submission-id> --detail "Leistung wird hier nicht bearbeitet"
fit-connect organisation reject --all                                    # ohne herunterzuladen
fit-connect organisation send --to <destination-id> \
  --leika urn:de:fim:leika:leistung:99400048079000 --service-name Test \
  --data antrag.json --schema-uri https://schema.fitko.de/fim/s00000114_1.1.schema.json
fit-connect organisation batch --data batch_data.csv                     # eine Zeile pro Antrag
fit-connect organisation cases list
fit-connect organisation cases events <case-id>                          # geprüftes Ereignisprotokoll
fit-connect organisation cases log --submission-id <id> --case-id <id>

receive schreibt Fachdaten und Anhänge entschlüsselt in --target; mit --accept folgt das signierte Accept-Event, sobald die Dateien geschrieben sind. Ohne --accept bleibt der Antrag unbestätigt — so wie das SDK selbst nie automatisch annimmt oder ablehnt (siehe Der Prüfbericht). reject funktioniert auch ohne Entschlüsselung, etwa wenn der Schlüssel fehlt.

Online service Onlinedienst

fit-connect online-service send --to <destination-id> \
  --leika urn:de:fim:leika:leistung:99400048079000 --service-name Test \
  --data antrag.json --schema-uri https://schema.fitko.de/fim/s00000114_1.1.schema.json \
  --attachments nachweis.pdf,foto.jpg --large-attachments bauplan.pdf
fit-connect online-service awaiting-replies
fit-connect online-service --reply-key <case-id>=keys/reply-private.jwk \
  receive --reply-id <id> --case-id <case-id> --target /srv/replies --accept
fit-connect online-service cases log --case-id <id> --submission-id <id> --sent-to <destination-id>

Antworten sind pro Vorgang verschlüsselt — der Schlüssel, der eine öffnet, wird zusammen mit seinem Vorgang übergeben (--reply-key <case-id>=<jwk-file>, mehrfach möglich). Das ist die CLI-Form von ReplyKeys.

Senden im Detail

send gibt es für beide Rollen mit denselben Optionen:

Option	Bedeutung
`--to <destination-id>`	Empfänger (Pflicht) — z. B. aus `directory for-service`
`--leika <urn>` + `--service-name <name>`	Adressierung über eine Verwaltungsleistung
`--process-model-id <id>` + `--message-id <id>`	Alternative: Adressierung über eine Prozessnachricht (API v3)
`--region <ars>`	Region, auf die sich der Antrag bezieht
`--in-case <case-id>`	In einen bestehenden Vorgang senden statt einen neuen zu öffnen
`--data <file>` + `--schema-uri <uri>`	Fachdaten (JSON oder XML) und Schema (Pflicht); `--mime json\|xml`, sonst aus der Dateiendung
`--attachments <files>`	Anhänge, kommagetrennt, im Speicher gehalten
`--large-attachments <files>`	Anhänge, die gestreamt und in Stücken hochgeladen werden

batch liest eine CSV mit den Spalten destinationId, serviceName, leikaKey, dataPath, schemaUri, mimeType (optional attachments, largeAttachments); eine fehlerhafte Zeile wird gemeldet, bricht den Lauf aber nicht ab.

Directory und Zustellpunkte

fit-connect directory for-service --leika <urn> --service-name Test --ars 05315000 [--all]
fit-connect directory for-process-message --process-model-id <id> --message-id <id> --region <ars>
fit-connect directory key <destination-id>                       # aktiver öffentlicher Schlüssel
fit-connect directory routes --leika <urn> --ars 05315000        # oder --ags / --area-id
fit-connect directory areas Musterstadt 05315000                 # Namen oder Schlüssel

fit-connect destinations list --status ACTIVE,CREATED --search Amt
fit-connect destinations show <destination-id>                   # Typ, Status, Leistungen, Schlüssel, Kontakt
fit-connect destinations limits <destination-id>
fit-connect destinations keys <destination-id>

directory ist unauthentifiziert und entspricht sdk.directory(); destinations braucht Credentials mit dem Scope manage-destinations und entspricht sdk.manage().destinations().

Schlüssel, Diagnose, Completion

fit-connect keygen --out-dir ./keys --with-config    # 2 Paare (4 JWKs) + fertige config.yml
fit-connect doctor                                   # die konfigurierte Identität durchleuchten
fit-connect doctor <destination-id> --decryption-key keys/decrypt.jwk
source <(java -jar fit-connect-cli.jar generate-completion)

doctor prüft Token und Scopes, Status und Typ des Zustellpunkts, ob die lokalen Schlüssel zum aktiven öffentlichen Schlüssel passen, Vertrauenskette, Netz, Anhang-Limits und Abkündigungen — und endet mit Exit-Code 3, wenn etwas nicht stimmt. In der Java-API ist das sdk.diagnose(destinationId, keys).

Migration von der 4.0.0-alpha-Kommandozeile

Vorher	Jetzt
`list --destinationId X`	`organisation awaiting`
`get --submissionId X --accept=true --target D`	`organisation receive X --accept --target D`
`get-all --destinationId X --target D`	`organisation receive --all --target D`
`purge --destinationId X`	`organisation reject --all`
`send --destinationId X --leikaKey … --serviceName … --data …`	`organisation send --to X --leika … --service-name … --data …`
`batch --data f.csv`	`organisation batch --data f.csv`
`status subscriber/sender …`	`organisation cases log --submission-id S --case-id C [--sent-to X]`
`keygen --outDir D --withConfig=true`	`keygen --out-dir D --with-config`
`--actingDestinationId`, `--actingDecryptionKey(s)`, `--actingSignatureKey`	`--as-destination-id`, `--as-decryption-key`, `--as-signature-key`

Ergebnisse gehen jetzt nach stdout, nicht ins Log; --json liefert sie maschinenlesbar.

Selbst bauen

./mvnw clean package -DskipTests -pl cli -am -P '!e2e-tests'
# → cli/target/fit-connect-cli.jar

.NET: `Fitko.FitConnect.Examples`

Im .NET-SDK übernimmt das Beispielprojekt Fitko.FitConnect.Examples im Repository meta-sdk-dotnet die Rolle einer Kommandozeile. Sie bauen es selbst und führen es mit dotnet run aus; jedes Kommando ist gleichzeitig eine lauffähige Demo und eine Code-Vorlage.

Voraussetzungen

.NET SDK 10.0+

Je nach Kommando eine oder mehrere appsettings.*.json mit Credentials — diese Dateien sind nicht im Repository enthalten und werden selbst angelegt (Struktur siehe Konfiguration):

Kommando	Benötigte Dateien	Beispieldatei
`submission`	`appsettings.e2e.json`	`SubmissionExample.cs` — senden, abholen, Prüfbericht, annehmen
`reply`	`appsettings.bidiko.json`	`ReplyExample.cs` — BiDiKo komplett, erzeugt Rückkanalschlüssel zur Laufzeit
`process`	`appsettings.e2e.json`	`ProcessCommunicationExample.cs` — API v3: Prozessnachricht suchen, Vorgang anlegen, senden
`zbp`	`appsettings.e2e.json` + `appsettings.zbp.json`	`ZbpExample.cs` — ZBP-Nachricht über den Adapter
`virusscanning`	`appsettings.e2e.json` + `appsettings.virusscanning.json`	`VirusScanningExample.cs` — senden mit Virenscan
`callback`	keine (offline)	`CallbackValidationExample.cs` — Callback-Signatur prüfen

Aufruf

dotnet run --project Fitko.FitConnect.Examples -- submission
dotnet run --project Fitko.FitConnect.Examples -- reply
dotnet run --project Fitko.FitConnect.Examples -- process
dotnet run --project Fitko.FitConnect.Examples -- zbp
dotnet run --project Fitko.FitConnect.Examples -- virusscanning
dotnet run --project Fitko.FitConnect.Examples -- callback

Die Beispiele nutzen dieselben Rollen-Clients wie Ihre Anwendung (client.AsOrganisation() / client.AsOnlineService()) — der Weg vom Beispiel zum eigenen Code ist Kopieren und Konfiguration austauschen.

Wann welches Werkzeug?

Sie wollen …	Greifen Sie zu
die Gegenseite simulieren, ohne zu bauen	`fit-connect-cli.jar` — Rollen-Kommandos für beide Seiten
vor dem Go-Live Credentials, Schlüssel und Zustellpunkt prüfen	`fit-connect doctor`
Batch-Versand aus CSV	`fit-connect organisation batch` / `online-service batch`
ein Skript oder eine Pipeline anbinden	`fit-connect --json`
eine eigene .NET-Anwendung als Vorlage	`Fitko.FitConnect.Examples`

Weiter geht's

Konfiguration — die SDK-Einstellungen, die auch das CLI liest
Spickzettel Java · Spickzettel .NET
Tutorial: Empfangen und antworten — nutzt keygen

Einsatzszenarien​

Java: fit-connect​

Voraussetzungen​

Aufruf und Konfiguration​

Organisation Verwaltung​

Online service Onlinedienst​

Senden im Detail​

Directory und Zustellpunkte​

Schlüssel, Diagnose, Completion​

Selbst bauen​

.NET: Fitko.FitConnect.Examples​

Voraussetzungen​

Aufruf​

Wann welches Werkzeug?​

Weiter geht's​

Einsatzszenarien

Java: `fit-connect`

Voraussetzungen

Aufruf und Konfiguration

Organisation Verwaltung

Online service Onlinedienst

Senden im Detail

Directory und Zustellpunkte

Schlüssel, Diagnose, Completion

Selbst bauen

.NET: `Fitko.FitConnect.Examples`

Voraussetzungen

Aufruf

Wann welches Werkzeug?

Weiter geht's