Zum Hauptinhalt springen

Vorhandensein neuer Einreichungen prüfen

Empfangende Systeme können sich über den Eingang neuer Einreichungen entweder durch periodische Anfragen informieren (Polling) oder vom Zustelldienst über Callbacks aktiv benachrichtigen lassen. Letzteres stellt die empfohlene Umsetzungsvariante dar, da hierdurch unnötige Anfragen vermieden werden können, was zu einer insgesamt besseren Performance und zu einer schnelleren Benachrichtigung empfangender Systeme führt.

Callback​

Wenn ein Callback im Zustellpunkt hinterlegt ist, kann der Zustelldienst den Zustellpunkt aktiv via Callback über neue Einreichungen informieren. Das Format, in welchem der Callback übertragen wird, ist im Endpunkt PUT /v1/destinations/{destinationId} definiert. Die Konfiguration und Prüfung von Callbacks ist im Artikel Verwendung von Callbacks beschrieben.

Callbacks zur Benachrichtigung über neue Einreichungen haben aktuell das folgende Format. Zu beachten ist, dass das Feld submissionIds als deprecated markiert wurde und durch das Feld submissions ersetzt werden soll.

POST /callbacks/fit-connect
callback-authentication: 2056b372b5bcec06d8f11ab79b84b42d6cbe1c8e1178cdfa36e4385dcf717758aaa7599f417d9ec3e079087884f4fd59680bf713621383e2d4414ef74fb10df3
callback-timestamp: 1672527599

{
  "type":"https://schema.fitko.de/fit-connect/submission-api/callbacks/new-submissions",
  "submissionIds":["f39ab143-d91a-474a-b69f-b00f1a1873c2"], 
  "submissions":[
    {
      "destinationId":"d12caea8-f372-4eb1-b102-b0a228253a11",
      "submissionId":"f39ab143-d91a-474a-b69f-b00f1a1873c2",
      "caseId":"9eec7d3e-dc66-4f82-9f52-1520bf96a32e"
    }
  ]
}
Warnung!

Da der Callback-Endpunkt des empfangenden Systems öffentlich über das Internet erreichbar ist, MÜSSEN angebundene Systeme prüfen, ob eingehende Callbacks von einem vertrauenswürdigen Zustelldienst stammen. Zu diesem Zweck MÜSSEN die im Artikel Prüfen von Callbacks beschriebenen Prüfungen durchgeführt werden.

Callbacks werden wiederholt, bis ein Accepted- oder Rejected-Event gesetzt wurde.

Wenn das empfangende System über den Eingang neuer Einreichungen benachrichtigt wurde, dann kann es diese wie im Artikel Einreichung herunterladen beschrieben herunterladen.

Polling​

Über Polling, d.h. regelmäßiges Abfragen des Endpunktes GET /v1/submissions, können alle Einreichungen abgefragt werden, die zum Abholen bereitstehen (Einreichungen im Status Submitted). Dies wird aus Performancegründen jedoch nicht empfohlen.

Die abgerufene Liste der Submissions kann über den Queryparameter destinationId auf einzelne Zustellpunkte eingeschränkt werden. In diesem Fall werden nur die Submissions zurückgegeben, die zum angegebenen Zustellpunkt gehören. Zusätzlich kann über die Queryparameter offset und limit das Gesamtergebnis in kleinere Teillisten der verfügbaren Submissions aufgeteilt werden. Die maximale Anzahl an Submissions in einer Teilliste (limit) sind 500 Submissions.

Das folgende Beispiel zeigt, wie Sie das .NET-SDK nutzen, um zu erfragen, ob abholbereite Einreichungen auf dem Zustelldienst vorliegen. Falls Einreichungen vorliegen, dann können Sie sie in einem weiteren Schritt vom Zustelldienst laden. Hier finden Sie ein Beispiel für das Herunterladen.

Liste abrufen​

Um die Liste der abholbereiten Einreichung zu erfragen, erzeugen Sie zunächst ein Objekt des Typs Subscriber. Dafür benötigen Sie die Endpunkte der jeweiligen Betriebsumgebungen der FIT-Connect-Infrastruktur. Eine Beschreibung der Umgebungen (Environments) finden Sie hier. Das folgende Beispiel nutzt FitConnectEnvironment.Testing.
Zudem benötigen Sie eine ClientId und ein ClientSecret. Hier ist beschrieben, wie Sie diese Credentials erhalten. Das Beispiel verwendet Platzhalter für die Werte in clientId und clientSecret.
Darüber hinaus benötigen Sie die privaten JSON Web Keys (JWKs) für das Entschlüsseln der Daten sowie für das Überprüfen der Signaturen. Im folgenden Beispiel sind die JWKs in den Dateien privateKeyDecryption und privateKeySigning gespeichert.
Der Parameter logger der Methode ClientFactory.GetSubscriberClient(...) ist optional.

var clientId = "YOUR CLIENT ID" 
var clientSecret = "YOUR CLIENT SECRET";

var subscriber = ClientFactory.GetSubscriberClient(FitConnectEnvironment.Testing, clientId,
            clientSecret,
            await File.ReadAllTextAsync(privateKeyDecryption),
            await File.ReadAllTextAsync(privateKeySigning),
            logger);

Rufen Sie nun am Subscriber-Objekt die Methode GetAvailableSubmissionsAsync() auf, um die Liste der abholbereiten Einreichung zu erfragen:

var submissionForPickups = await subscriber.GetAvailableSubmissionsAsync();

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples der FITKO hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

E-Mail​

Bei nicht erfolgter Abholung einer Einreichung durch ein empfangendes System (Fachverfahren) erfolgt eine Benachrichtigung des technischen Kontakts auf Empfängerseite 3 Tage nach Eingang der Einreichung.