FIT-Connect .NET SDK User Guide

Vorteile (Pros)

• Einfache Integration: Klare .NET-API zur Erstellung und Übermittlung von ZBP-Nachrichten.
• Starke Typisierung: Vermeidung von Laufzeitfehlern durch strukturierte Klassen wie CreateMessage und SubmissionBuilder.
• Flexibler Aufbau von Submissions: Unterstützung für Attachments, Zertifikatsbasierte Signatur und manuelle Kontrolle über Token.
• Getrennte Modulstruktur: Ermöglicht Wiederverwendbarkeit von ZBP-spezifischer Logik unabhängig vom restlichen System.
• Kompatibilität mit FIT-Connect Spezifikation: Erfüllt die Vorgaben für den Versand über den ZBP-Brückenkopf vollständig.
• Testfreundlich: Unterstützt die Testumgebung (FitConnectEnvironment.Test) und erlaubt das einfache Austauschen von Konfigurationen.
• Moderne .NET-Technologien: Nutzung asynchroner Aufrufe (SendAsync) und Integration mit Standardkryptografie.

Einführung

Dieses SDK ermöglicht den Versand von Nachrichten über das Zentrale Bürgerpostfach (ZBP) im Rahmen von **FIT-Connect **. Es abstrahiert die technische Komplexität der Schnittstelle und erlaubt eine einfache Integration in bestehende .NET-Anwendungen.

Installation

Das SDK besteht typischerweise aus zwei Projekten:

• FitConnect: Hauptprojekt mit FIT-Connect Schnittstellen zur übermittlung von Anträgen.
• FitConnect.Zbp: SDK mit der Implementierung der ZBP-spezifischen Schnittstellen

Einbindung via ProjectReference oder als NuGet-Paket (in Planung).

Architekturüberblick

FitConnect
 └── uses FitConnect.Zbp
      ├── ZbpClient
      ├── ZbpServiceAdapter
      ├── ZbpApiAttachment / SubmissionAttachment
      ├── SubmissionBuilder
      └── Helper (Certificate, Logging, etc.)

• ZbpClient ist der Einstiegspunkt für den Versand.
• SubmissionBuilder kapselt die komplexe Logik zur Erstellung gültiger Submissions.
• Trennung von internen (ZBP) und externen Attachments.

Nachricht erstellen und versenden

1. Nachricht erzeugen

var createMessage = new CreateMessage {
    MailboxGuid = Guid.Parse(_config.ZbpTestSettings.TargetMailboxHandle),
    Content = "
Test
Nachricht über das ZBP
",
    Sender = "FIT-Connect .NET SDK",
    Service = "Test of ZBP-Adapter DEV",
    Title = $"E2E test via Adapter {DateTime.Now:yyyy-MM-dd HH:mm:ss}",
    StorkQaaLevel = (int)AuthenticationLevel.One,
    Reference = "ref - HK",
    SenderUrl = new Uri("https://example.net")
};

createMessage.Attachments.Add(ZbpApiAttachment.FromFile("Test.pdf", "application/pdf"));

2. Zertifikate laden

var authorCertPath = "IntCerts/zbp_keypair/Zertifikat_FITConnect_int.cer";
var privateKeyPath = "IntCerts/zbp_keypair/priv.key";

var authorCredentials =
    LoadCertificatesHelper.LoadAuthorCredentials(authorCertPath, privateKeyPath);

3. Submission erstellen

var submission = SubmissionBuilder.Builder()
    .SetDestination(Guid.Parse("b21c51d0-324b-4df4-ae6c-c0568a2bb067"))
    .SetServiceType("urn:schema-fitko-de:fit-connect:id.bund.de:message_v6",
        "Message Test Service")
    .SetZbpMessage(
        createMessage,
        authorCertificateContent, authorPrivateKeyContent)
    .Build();

4. Nachricht senden

var sender = ClientFactory.CreateSenderClient(FitConnectEnvironment.Test,
    _config.Sender.ClientId,
    _config.Sender.ClientSecret);

var sentSubmission = await sender.SendAsync(submission);

Zertifikatsverwaltung

• Zertifikate werden nicht im Systemstore abgelegt, sondern direkt aus .cer und .key-Dateien geladen.
• Der private Key muss PEM-kodiert vorliegen.
• Aktuell wird RSA unterstützt (kein EC- oder PFX-Support in der Basisversion).
• Authentifizierungs-Token (JWT) müssen bei Bedarf mit ausgeliefert werden (authorToken).

Beispielkonfiguration (appsettings.json)

{
  "ZbpTestSettings": {
    "TargetMailboxHandle": "b3500e62-347c-4553-93f6-9149fd71d9db"
  },
  "Sender": {
    "ClientId": "sdk-client",
    "ClientSecret": "topsecret"
  }
}

Fehlerbehandlung

• Der Client wirft bei Netzwerk- oder Zertifikatsfehlern HttpRequestException.
• ZBP-spezifische Fehler werden in Zbp.RestApiException verpackt.
• Innerhalb der Submission können Validierungsfehler auftreten, z. B. fehlende Pflichtfelder.

Beispiel:

try {
    await sender.SendAsync(submission);
} catch (RestApiException ex) {
    Console.Error.WriteLine("ZBP-Fehler: " + ex.Message);
}