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.

$ export SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
$ export JWT_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA
$ curl \
    -H "Authorization: Bearer $JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -X GET "$SUBMISSION_API/v1/submissions"
{
  offset: 0,
  count: 3,
  totalCount: 3,
  submissions: [
    {
      destinationId: "879ee109-a690-4db8-ab32-424284184d7d",
      submissionId: "ce75a6b8-d72f-4b94-b09e-af6be35bc2ae"
    },
    {
      destinationId: "19c8489b-29b8-422f-b7db-919852cfb04b",
      submissionId: "e364430f-5a3b-4284-ba9a-f2867ba421e6"
    },
    {
      destinationId: "80a0aac3-148d-42bb-9366-516ce6355348",
      submissionId: "530ba588-2db9-4899-ab0d-0c0b57689271"
    }
  ]
}

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.