Zum Hauptinhalt springen

Einrichten

TL;DR – Abhängigkeit eintragen, Credentials und Umgebung konfigurieren, SDK-Instanz erzeugen, Rolle wählen. Wählen Sie oben rechts Ihre Sprache; die Auswahl bleibt auf allen Seiten erhalten.

1. Voraussetzungen prüfen​

  • JDK 21+ (LTS). Prüfen mit java --version.
  • Maven 3.6+ (oder der mitgelieferte mvnw-Wrapper).

2. SDK installieren​

Das Java-SDK steht auf Maven Central zur Verfügung. Für die meisten Integrationen genügt das Modul sdk-client — es enthält Organisation-, OnlineService-, Routing- und Destination-Clients.

<dependency>
  <groupId>dev.fitko.fitconnect</groupId>
  <artifactId>sdk-client</artifactId>
  <version>4.0.0-rc.1</version>
</dependency>

Wenn Sie mehrere Module nutzen (z. B. zusätzlich virus-scanner oder zbp-client), bietet sich das BOM an, um die Versionen synchron zu halten:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.fitko.fitconnect</groupId>
      <artifactId>sdk-bom</artifactId>
      <version>4.0.0-rc.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Anschließend können Sie die einzelnen Module ohne <version> einbinden:

<dependencies>
  <dependency>
    <groupId>dev.fitko.fitconnect</groupId>
    <artifactId>sdk-client</artifactId>
  </dependency>
  <dependency>
    <groupId>dev.fitko.fitconnect</groupId>
    <artifactId>virus-scanner</artifactId>
  </dependency>
</dependencies>

3. Credentials beschaffen​

Beide SDKs nutzen das OAuth-2.0-Verfahren mit clientId und clientSecret. Diese erhalten Sie im Self-Service-Portal der jeweiligen Umgebung:

  • Onlinedienst-Client für sendende Systeme
  • Verwaltungssystem-Client für empfangende Systeme

Empfangende Systeme benötigen zusätzlich:

  • den privaten Entschlüsselungs-Schlüssel als JWK (eine Liste – mehrere Versionen sind für den Rollover erlaubt)
  • den privaten Signatur-Schlüssel als JWK

Eine Anleitung zum Erzeugen der JWKs finden Sie auf der Seite Zertifikate.

Regel 4 des Rollenmodells: Schlüssel bestimmen, was Sie öffnen können, nicht was Sie senden dürfen. Ein reiner Sender braucht deshalb keinen einzigen Schlüssel. Im Java-SDK sind Schlüssel kein Teil der config.yml — Sie übergeben sie beim Erzeugen der Rolle (Schritt 4) und können sie damit aus einem Vault oder HSM laden. Im .NET-SDK stehen sie in der Konfiguration unter FitConnect.Client, die Sie aus einem Secret-Store befüllen.

4. SDK konfigurieren​

Beide SDKs unterstützen sowohl programmatische als auch datei-basierte Konfiguration. Wählen Sie unten Ihre Sprache, um den passenden Weg zu sehen.

Programmatisch (empfohlen für kleine Setups):

FitConnectSdk sdk = FitConnectSdk.fromConfigBuilder()
    .credentials("client-id", "client-secret")
    .environment(FitConnectEnvironment.TEST)
    .build();

Mit YAML-Datei:

FitConnectSdk sdk = FitConnectSdk.fromConfigYaml(Path.of("config.yml"));

Beispiel-YAML:

credentials:
  clientId: "your-client-id"
  clientSecret: "your-client-secret"

environment: "TEST"   # alternativ: STAGE, PROD

sdkSettings:
  httpConfig:
    timeoutConfig: { readTimeout: 30, writeTimeout: 30, connectionTimeout: 30, callTimeout: 30 }
    retryConfig:
      allowRetries: true
      maxRetryCount: 5
      initialDelayInMs: 500
      retryableStatusCodes: [408, 429, 500, 502, 503, 504]
  attachmentChunkingConfig:
    chunkAllAttachments: false
    chunkSizeInMB: 10
    attachmentStoragePath: "/tmp/fit-connect-attachments"
  validationConfig:
    validateMetadata: true
    validateData: true
    validateAttachments: true

Alles, was in sdkSettings steht, können Sie statt in der Datei auch am Builder setzen — die Schlüssel heißen wie die Builder-Methoden (Ausnahme: timeoutConfig → timeouts(…)):

FitConnectSdk sdk = FitConnectSdk.fromConfigBuilder()
    .credentials(vault.clientId(), vault.clientSecret())      // z. B. aus einem Vault
    .environment(FitConnectEnvironment.TEST)
    .settings(SdkSettings.builder()
        .httpConfig(HttpConfig.builder()
            .timeouts(TimeoutConfig.builder().readTimeout(30).callTimeout(30).build())
            .retryConfig(RetryConfig.builder().maxRetryCount(5).initialDelayInMs(500).build())
            .build())
        .attachmentChunkingConfig(AttachmentChunkingConfig.builder()
            .attachmentStoragePath(Path.of("/tmp/fit-connect-attachments")).build())
        .build())
    .build();

Alle Optionen beider Wege nebeneinander: Referenz: Konfiguration.

Es gibt kein enableAutoReject mehr: Eine empfangene Submission wird immer mit einem Prüfbericht zurückgegeben, den Sie explizit auswerten — siehe Konzept: Der Prüfbericht.

Eine Credential-Paarung für Senden und Empfangen — die frühere Trennung in senderConfig/subscriberConfig gibt es nicht mehr. Ein Client kann mit mehreren Destinations verbunden sein; welche davon eine Codestelle als "sich selbst" verwendet, entscheiden Sie erst beim Erzeugen von Organisation/OnlineService — nicht in der Konfiguration.

Die handelnde Destination erzeugen. sdk allein reicht für Aufrufe noch nicht — Sie brauchen dafür eines von vier Objekten, je nachdem in welcher Rolle Sie gerade handeln. myDestinationId ist dabei immer die UUID Ihrer eigenen Destination — jede Partei in FIT-Connect ist selbst eine Destination, auch ein reiner Sender.

Empfangen Sie Anträge (Verwaltungssystem, Typ A/B), erzeugen Sie eine Organisation mit den Schlüsseln zum Entschlüsseln und Signieren:

DestinationKeys keys = new DestinationKeys(decryptionJwk, signatureJwk);
Organisation organisation = sdk.organisation(myDestinationId, keys);

Senden Sie Anträge (Onlinedienst, Typ C), erzeugen Sie einen OnlineService. ReplyKeys ordnet dabei jedem Case den Schlüssel zu, mit dem später eintreffende Antworten geöffnet werden:

ReplyKeys replyKeys = ReplyKeys.of(Map.of(caseId, replyDecryptionJwk));
OnlineService onlineService = sdk.onlineService(myDestinationId, replyKeys);

Wer nur sendet bzw. nur empfängt, kommt ganz ohne Schlüssel aus — DestinationKeys.none() bzw. ReplyKeys.none().

Für Suche und Verwaltung — unabhängig von einer bestimmten Destination — gibt es zwei weitere Einstiegspunkte. Beide stellen ihrerseits Sub-Clients für die jeweiligen Aufgaben bereit:

Directory  directory  = sdk.directory();   // Routing- und Destination-Suche, unauthentifiziert
Management management = sdk.manage();      // Destinations pflegen, Anhänge verwalten

Routing           routing      = directory.routing();
DestinationClient destinations = management.destinations();
AttachmentManager attachments  = management.attachments();

Vollständige Methodenlisten aller vier Einstiegspunkte: Spickzettel (Java).

Programmatische Anpassung

Über .customization() können Sie eigene HTTP-Clients oder Storage-Provider einhängen (z. B. für Datenbank-basierte Anhang-Persistenz). Siehe sdk-client/README.md.

5. Umgebung auswählen​

Für FIT-Connect stehen drei produktiv-relevante Umgebungen zur Verfügung:

UmgebungZweckInsecure Keys erlaubt
TESTTests, lokale Entwicklung✅
STAGEReferenz-, Integrations-Umgebung❌
PRODProduktivbetrieb❌

Eine ausführliche Beschreibung finden Sie unter Betriebs-Umgebungen.

Die Umgebung übergeben Sie als Enum oder benutzerdefiniert:

// Vordefiniert
.environment(FitConnectEnvironment.TEST)

// Custom Environment (z. B. lokale Entwicklung gegen einen eigenen Endpoint)
FitConnectEnvironment env = FitConnectEnvironment.builder()
    .name("LOCAL")
    .authUrl("https://my-auth-server/token")
    .routingUrl("https://my-routing-server")
    .submissionApiUrl("https://my-api-host/submission-api")
    .portalUrl("https://my-portal")
    .destinationApiUrl("https://my-api-host/destination-api")
    .allowInsecureKeys(true)
    .build();

6. Verbindung testen​

Mit dem fertigen SDK können Sie eine erste Probe machen, indem Sie den öffentlichen Verschlüsselungs-Schlüssel eines bekannten Zustellpunkts abrufen. Der Aufruf läuft über die Directory-Suche und ist unauthentifiziert — er eignet sich damit unabhängig vom OAuth-Scope Ihres Test-Clients als einfache Erreichbarkeitsprobe. Ihre Credentials selbst werden beim ersten echten Senden oder Empfangen geprüft.

UUID destinationId = UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14");
EncryptionKey publicKey = sdk.directory().activeEncryptionKeyOf(destinationId);
System.out.println("Verbindung OK – keyId=" + publicKey.keyId());

Wenn Sie eine Antwort erhalten, sind Sie startklar. Weiter geht's mit Antrag senden oder, falls Sie ein Verwaltungssystem entwickeln, mit Anträge abholen und prüfen.

Vor dem ersten echten Antrag lohnt die Selbstdiagnose: Credentials, Zustellpunkt, Schlüssel und Umgebung in einem Durchlauf.

Diagnosis d = sdk.diagnose(MY_DESTINATION_ID, keys);
System.out.println(d.describe());
if (!d.healthy()) System.exit(3);

Weiterführende Themen​