Zum Hauptinhalt springen

Einreichungen empfangen

Diese Dokumentation beschreibt, wie Sie mit dem FIT‑Connect .NET SDK Submissions empfangen und Replies abrufen können.

Überblick​

Der Receiver‑Teil des SDK ist dafür zuständig, bereits versendete oder bereitgestellte Inhalte aus FIT‑Connect abzuholen und lokal zu verarbeiten.

Typische Anwendungsfälle sind:

  • eine konkrete Submission anhand von SubmissionId und CaseId abrufen
  • eine konkrete Reply anhand ihrer ReplyId abrufen
  • alle verfügbaren Replies sammeln
  • empfangene Anhänge lesen, auch wenn sie ursprünglich in Chunks übertragen wurden
  • empfangene Inhalte validieren und bei Fehlern entsprechend reagieren

Der typische Ablauf beim Empfangen einer Submission ist:

  1. IFitConnectClient per Dependency Injection beziehen
  2. sicherstellen, dass die Submission serverseitig bereitsteht
  3. ReceiverService.FetchSubmission(submissionId, caseId) aufrufen
  4. Ergebnisobjekt weiterverarbeiten

Voraussetzungen​

Bevor Sie Inhalte empfangen, sollten Sie Folgendes vorbereitet haben:

  • eine gültige appsettings.json-Konfigurationsdatei (siehe Konfiguration)
  • korrekt konfigurierte Receiver‑Zugangsdaten (Receiver.ClientId, Receiver.ClientSecret)
  • passende Umgebung über EnvironmentTag
  • bei verschlüsselten Inhalten: Receiver.DecryptionKeys in der Konfiguration hinterlegt
  • bei Validierung mit automatischer Ablehnung:
    • aktivierte Validierungskonfiguration
    • ggf. einen konfigurierten Receiver.SignatureKey

Client initialisieren​

Das SDK wird über Dependency Injection eingebunden:

using Fitko.FitConnect.Sdk.Client;
using Fitko.FitConnect.Sdk.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var client = new ServiceCollection()
    .AddSingleton<IConfiguration>(configuration)
    .AddFitConnect()
    .BuildServiceProvider()
    .GetRequiredService<IFitConnectClient>();

var receiver = client.ReceiverService;

In einer ASP.NET Core- oder Generic-Host-Anwendung injizieren Sie IFitConnectClient direkt per Konstruktor-Injektion, nachdem Sie AddFitConnect() in Program.cs registriert haben.

Für regulär empfangene Submissions verwendet der Receiver automatisch die in Receiver.DecryptionKeys konfigurierte Schlüsselreihenfolge. Dadurch können neue und alte Schlüssel während eines Key-Rollovers parallel akzeptiert werden.

Eine Submission empfangen​

Wenn Sie SubmissionId und CaseId kennen, können Sie die Submission direkt abrufen.

var received = await receiver.FetchSubmission(submissionId, caseId);
Console.WriteLine(received);

Was FetchSubmission(...) zurückliefert​

Ein erfolgreich empfangenes Submission‑Objekt enthält typischerweise:

  • SubmissionId – die ID der Submission
  • CaseId – die zugehörige Fall‑ID
  • DestinationId – die Ziel‑Destination
  • PublicService – die fachliche Servicebeschreibung
  • Attachments – die rekonstruierten Anhänge
  • die entschlüsselten bzw. verarbeiteten Daten der Submission
var received = await client.ReceiverService.FetchSubmission(submissionId, caseId);
Console.WriteLine(received.SubmissionId);
Console.WriteLine(received.CaseId);
Console.WriteLine(received.DestinationId);
Console.WriteLine(received.PublicService?.Name);
Console.WriteLine(received.Attachments.Count);

Warten, bis eine Submission bereit zur Abholung ist​

In End‑to‑End‑Szenarien ist eine Submission oft nicht sofort nach dem Versand abrufbar. Darum ist es üblich, zunächst auf den passenden Status zu warten, bevor FetchSubmission(...) aufgerufen wird.

Ein gängiges Muster ist das Polling der Case Event Logs, bis der Status Submitted erreicht wurde.

Große Anhänge empfangen​

Das SDK kann große Anhänge wieder korrekt zusammensetzen, auch wenn sie beim Versand gechunked wurden.

Typischer Ablauf​

  1. Eine Submission wird mit großem Anhang gesendet
  2. Der Sender fragmentiert den Anhang in mehrere Teile
  3. Beim Abruf setzt der Receiver die Fragmente wieder zu einem logischen Anhang zusammen

Beispiel: empfangenen Anhang lesen​

var received = await client.ReceiverService.FetchSubmission(submissionId, caseId);
var attachment = received.Attachments[0];
long totalRead = 0;
var buffer = new byte[1024 * 1024];

await using (var stream = attachment.OpenStream())
{
    int read;
    while ((read = await stream.ReadAsync(buffer, 0, buffer.Length)) > 0)
    {
        totalRead += read;
    }
}

Console.WriteLine($"Empfangene Bytes: {totalRead}");

Erwartetes Verhalten​

Auch wenn beim Versand intern mehrere Fragmente übertragen wurden, liefert der Receiver nach dem Abruf wieder einen zusammenhängenden Anhang. Das ist besonders wichtig für:

  • große PDF‑Dateien
  • Binärdateien
  • strukturierte Fachanhänge
  • Uploads über Chunking‑Konfiguration

Konkrete Reply abrufen​

Neben Submissions kann der Receiver auch eine bestimmte Reply anhand ihrer ReplyId abrufen.

var replyId = Guid.Parse("<reply-id>");
var privateJwkJson = "<private-jwk-json>";

var reply = await client.ReceiverService.FetchSpecificReply(replyId, privateJwkJson);

Console.WriteLine($"SubmissionId: {reply.SubmissionId}");
Console.WriteLine($"CaseId: {reply.CaseId}");
Console.WriteLine($"Anzahl Anhänge: {reply.Attachments.Count}");

Bedeutung der Parameter​

  • replyId – die eindeutige ID der Reply
  • privateJwkJson – der private Schlüssel zum Entschlüsseln der Reply

Wenn die Reply verschlüsselt vorliegt, ist der passende private Schlüssel zwingend erforderlich. Für FetchSpecificReply(...) bleibt dies bewusst ein einzelner Schlüssel aus dem Reply Channel; die Receiver.DecryptionKeys-Liste wird für diesen expliziten Reply-Abruf nicht verwendet.

Alle verfügbaren Replies abrufen​

Wenn Sie nicht nur eine einzelne Reply, sondern alle aktuell verfügbaren Antworten laden möchten, können Sie die Sammelabfrage verwenden.

var replies = await client.ReceiverService.FetchAvailableReplies();

foreach (var reply in replies)
{
    Console.WriteLine($"ReplyId: {reply.ReplyId}");
    Console.WriteLine($"CaseId: {reply.CaseId}");
}

Diese Methode ist sinnvoll, wenn Sie:

  • einen Inbox‑ähnlichen Polling‑Mechanismus bauen
  • regelmäßig neue Replies einsammeln wollen
  • serverseitig verfügbare Antworten batchweise verarbeiten möchten

Die Methode listet nur verfügbare Replies auf. Eine Entschlüsselung erfolgt erst beim späteren Abruf der konkreten Reply.

Validierung beim Empfang​

Der Receiver kann empfangene Inhalte validieren. Das betrifft insbesondere Metadaten, Nutzdaten und Anhänge.

Die Konfiguration erfolgt über den Validation‑Block in der appsettings.json:

"Validation": {
  "Metadata": true,
  "Data": true,
  "Attachments": true,
  "AutoReject": false
}

Bedeutung​

  • Metadata – validiert Metadaten
  • Data – validiert den eigentlichen Payload
  • Attachments – validiert Anhänge
  • AutoReject – legt fest, ob bei Validierungsfehlern automatisch abgelehnt wird

Verhalten bei Validierungsfehlern​

Wenn empfangene Daten gegen das erwartete Schema verstoßen, kann der Abruf fehlschlagen.

Beispielhafte Fehlerbehandlung​

using Fitko.FitConnect.Core.Validation;

try
{
    var received = await client.ReceiverService.FetchSubmission(submissionId, caseId);
}
catch (ValidationProblemsException ex)
{
    Console.WriteLine("Validierung fehlgeschlagen.");
    Console.WriteLine(ex.Message);
}

Automatische Ablehnung​

Wenn die Konfiguration und das Signaturszenario es zulassen, kann eine Submission bei Validierungsfehlern automatisch abgelehnt werden.

Dafür sind in der Praxis relevant:

  • aktivierte Validierung
  • passende Receiver‑Konfiguration
  • gegebenenfalls ein gesetzter Receiver.SignatureKey

Rejected‑Status über Event Logs prüfen​

Wenn eine Submission aufgrund eines Validierungsfehlers abgelehnt wird, kann sich das in den Event Logs als Rejected widerspiegeln.

var caseEventLogs = await client.CaseApiService.GetCaseEventLog(caseId);
// Danach können die Event Logs ausgewertet werden, um auf "Rejected" zu prüfen.

Das ist besonders nützlich für technische Nachvollziehbarkeit, Monitoring, Fehleranalyse und automatisierte Tests.

Typische Fehlerquellen​

1. Falsche Receiver‑Credentials​

Wenn die Receiver‑Zugangsdaten nicht stimmen, schlägt der Abruf fehl.

Prüfen: Receiver.ClientId, Receiver.ClientSecret, richtige Umgebung, Netzwerk/Proxy.

2. Fehlende oder falsche DecryptionKeys​

Wenn verschlüsselte Inhalte empfangen werden, aber kein passender Schlüssel in Receiver.DecryptionKeys konfiguriert ist, kann der Receiver die Daten nicht entschlüsseln.

Bei Key-Rollover muss der neue Schlüssel an erster Stelle stehen. Ältere Schlüssel können vorübergehend als weitere Listeneinträge hinterlegt bleiben.

3. Falscher privater Schlüssel für Replies​

Beim Abruf einer konkreten Reply mit FetchSpecificReply(...) muss der Schlüssel zur verwendeten Verschlüsselung passen. Andernfalls schlägt die Entschlüsselung fehl.

4. Abruf zu früh​

Wenn eine Submission oder Reply noch nicht serverseitig bereitsteht, kann der Abruf zu früh erfolgen.

Empfehlung: vor dem Abruf Event Logs oder Verfügbarkeitsstatus prüfen und Polling mit Retry/Wait verwenden.

5. Validierungsfehler​

Ungültige Daten können beim Abruf Exceptions auslösen.

Prüfen: Schema korrekt? Datentypen korrekt? Validierungskonfiguration passend? AutoReject bewusst gesetzt?