Zum Hauptinhalt springen

Einreichung überprüfen

Nachdem das empfangende System eine Einreichung empfangen hat, muss es diese überprüfen. Nach der Überprüfung muss entweder eine Empfangsbestätigung ("accept submission") oder eine Zurückweisung ("reject submission") gesendet werden (siehe Abschnitt Empfangsbestätigung). Die Prüfungen sind wichtig, um neben der Prüfung von technischen Fehlern auch einen bösartigen Austausch von einzelnen Anlagen zu verhindern.

Struktur einer Zurückweisung

Eine Rückweisung des empfangenden Systems aufgrund einer fehlgeschlagenen Prüfung könnte wie folgt aussehen:

{
"$schema": "https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json",
"jti": "4ac47caa-bce1-435a-b04f-3322b224b32e",
"iss": "40847c29-06aa-40e2-bf28-c29884c694c4",
"iat": 1622796532,
"sub": "submission:02bf1d9f-282d-4abf-810a-c4104baf0afe",
"txn": "case:452b5ee6-35df-441a-bd39-6141723cf914",
"events": {
"https://schema.fitko.de/fit-connect/events/reject-submission": {
"problems": [
{
"type": "https://schema.fitko.de/fit-connect/events/problems/an-example",
"title": "Nur ein Beispiel",
"detail": "Es darf kein Beispiel verwendet werden.",
"instance": "metadata"
}
]
}
}
}

Die grundsätzliche Struktur der Events ist auf der Seite Ereignisse beschrieben. Das reject-submission-Event enthält eine Liste von Problemen, die sich an RFC 7807 orientieren.

Das obigen Beispiel enthält folgendes Beispiel-Problem:

{
"type": "https://schema.fitko.de/fit-connect/events/problems/an-example",
"title": "Nur ein Beispiel",
"detail": "Es darf kein Beispiel verwendet werden.",
"instance": "metadata"
}

In der folgenden Liste der durchzuführenden Validierungen sind Beispiele für die im Rahmen der Zurückweisung zu verwendenden Problems inkl. der zu verwendenden Werte für type, title, detail und instance angegeben.

Die Angaben type und instance MÜSSEN vom Subscriber exakt übernommen werden. Die Angabe unter title SOLLTE wie dokumentiert übernommen werden. Die Angabe detail KANN ergänzt oder ersetzt werden, sofern zur Fehlerbehebung hilfreiche Informationen zur Verfügung stehen.

Hinweis

Die Informationen in den definierten Problemen werden über das Event Log vom Subscriber an das sendende System gesendet, das sie zur Fehlerbehebung speichert. Die Fehlermeldungen dürfen Antragssteller:innen nicht angezeigt werden!

Hintergrund ist, dass die Fehlermeldungen aus den APIs sehr technisch sind und Anwender:innen oft mehr verwirren als dass sie helfen. Aus Usability-Gründen sollte daher auf die direkte Anzeige der Fehlermeldungen verzichtet werden.

Stattdessen empfehlen wir, anhand des type-Attributs eine verständliche Fehlermeldung anzuzeigen, die Nutzenden weitere Hinweise und Handlungsoptionen mitgibt. Das type-Attribut gibt dabei jeweils eine eindeutige URL vor, die den Fehlertyp eindeutig identifiziert.

Durchzuführenden Validierungen

Überprüfung des Event-Logs

Zunächst MUSS eine Prüfung des Ereignisprotokolls der jeweiligen Einreichung erfolgen. Hierbei sind die folgenden Punkte zu beachten:

Struktur- und Signaturprüfung der Security Event Tokens

Rufen Sie das Event-Log unter GET /v1/cases/{caseId}/events ab. Prüfen Sie die Events gemäß der Seite Prüfung eines Security Event Token (SET).

{
"type": "https://schema.fitko.de/fit-connect/events/problems/invalid-event-log",
"title": "Inkonsistentes Event-Log",
"detail": "Das Event-Log ist inkonsistent.",
"instance": "submission"
}

Genau ein Submit-Event

Das Event-Log muss genau ein Event submit-submission für die betreffende Einreichung enthalten.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/invalid-event-log",
"title": "Inkonsistentes Event-Log",
"detail": "Das Event-Log ist inkonsistent, da es nicht genau ein Event 'submit-submission' enthält.",
"instance": "submission"
}

Authentication-Tags im Submit-Event

Das Submit-Submission-Event muss einen Payload authenticationTags enthalten.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/missing-authentication-tags",
"title": "Fehlende Authentication-Tags",
"detail": "Das Event 'submit-submission' enthält keine Authentication-Tags.",
"instance": "submission"
}

Liste der Anlagen im Submit-Event abgleichen

Die UUIDs der Anlagen in der Submission müssen den Attributen (UUIDs) des authenticationTags.attachments-Objektes im Submit-Event entsprechen.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/attachments-mismatch",
"title": "Fehlerhafte Anlagen-Liste",
"detail": "Die Liste der Anlagen in Submission und Event-Log stimmt nicht überein.",
"instance": "submission"
}

Überprüfung des Metadatensatzes

Nach der Prüfung des Ereignisprotokolls muss der vom sendenden System erzeugte Metadatensatz (submission/encryptedMetadata) geprüft werden. Dazu MÜSSEN nach der Entschlüsselung des Metadatensatzes die folgenden Prüfungen durchgeführt werden:

Authentication-Tag prüfen

Stimmt der Authentication-Tag des verschlüsselten Metadatensatzes mit dem im Submit-Submission-Event (authenticationTags/metadata) überein?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/incorrect-authentication-tag",
"title": "Authentication-Tag ungültig",
"detail": "Das Authentication-Tag des Metadatensatzes ist ungültig.",
"instance": "metadata"
}

Entschlüsselung

Kann der Metadatensatz entschlüsselt werden?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/encryption-issue",
"title": "Entschlüsselungs-Fehler",
"detail": "Die Entschlüsselung des Metadatensatzes ist fehlgeschlagen.",
"instance": "metadata"
}

Sofern ein falscher oder veralteter Schlüssel verwendet wurde, der Metadatensatz aber dennoch entschlüsselt werden konnte, sollte Verarbeitung fortgesetzt werden, aber eine entsprechende Meldung erfolgen.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/encryption-issue",
"title": "Entschlüsselungs-Fehler",
"detail": "Der Schlüssel {kid} ist nicht der zu diesem Zweck vorgesehene Schlüssel.",
"instance": "metadata"
}

Syntax-Validierung

Ist der Metadatensatz valides JSON?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/syntax-violation",
"title": "Syntax-Fehler",
"detail": "Der Metadatensatz ist kein valides JSON.",
"instance": "metadata"
}

Schema-Referenz

Enthält der Metadatensatz einen Eintrag $schema?

Hinweis zum $schema-Attribut in der Version 1.x.y des Metadatenschemas

In der Version 1.x.y des Metadatenschemas ist das Attribut $schema nicht verpflichtend (siehe Dokumentation zum Metadatensatz). Sofern kein $schema-Attribut im Metadatensatz enthalten ist, kann davon ausgegangen werden, dass es sich um ein Metadatenschema gemäß Major-Version 1 (1.x.y) des Metadatenschemas handelt. In diesem Fall DARF die Einreichung vom empfangenden System NICHT alleine aufgrund des fehlenden $schema-Attributs zurückgewiesen werden.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/missing-schema",
"title": "Schema-Referenz fehlt",
"detail": "Die Schema-Referenz fehlt im Metadatensatz.",
"instance": "metadata"
}

Metadatenschema

Entspricht die angegebene URI einem gültigen Metadatenschema? Wird die verwendete Version des Metadatenschemas unterstützt?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/unsupported-schema",
"title": "Metadatenschema nicht unterstützt",
"detail": "Die angegebene Metadatenschema-URI ('$schema') ist keines der unterstützten Metadatenschemas.",
"instance": "metadata"
}

Schema-Prüfung

Ist der Metadatensatz valide bezüglich des verwendeten Metadatenschemas?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/schema-violation",
"title": "Schema-Fehler",
"detail": "Der Metadatensatz ist nicht schema-valide.",
"instance": "metadata"
}

Sicherstellen der Integrität einer Submission

Es muss sichergestellt sein, dass Zwischensysteme, wie z. B. auch FIT-Connect selbst, Fachdaten oder Anhänge von Submissions nicht austauschen können. Hierfür wird eine Hashfunktion verwendet, welche die Integrität der Datensätze prüfbar macht. Die so berechneten Hashes werden vom sendenden System in den Metadaten verschlüsselt abgelegt und können bei Abruf vom empfangenden System validiert werden.

Nur wenn sowohl der Sender als auch der Subscriber Ihre Aufgaben übernehmen, ist die Integrität einer Submission sichergestellt. Wie diese Aufgaben für den Subscriber im Detail aussehen, wird im Folgenden beschrieben. Eine Beschreibung der Aufgaben des Senders findet sich im Artikel Metadatensatz erstellen.

Aufgaben des Subscribers

Nachdem ein Antrag empfangen wurde und vor dessen Weiterverwendung, muss die Integrität der Fachdaten und Anhänge sichergestellt werden. Starten wir mit den Fachdaten:

  1. Prüfen, ob Fachdaten vorhanden sind. Wenn nein, können die Schritte 2. und 3. übersprungen werden.

  2. Berechnen eines mit dem Metadatenschema kompatiblen Hashes (aktuell: SHA-512) der entschlüsselten Fachdaten.

  3. Prüfen, ob dieser Hash mit dem aus den Metadaten übereinstimmt (Feld contentStructure.data.hash.content).

    a. Wenn ja: Die Integrität der Fachdaten ist sichergestellt.

    b. Wenn nein: Die Integrität der Fachdaten ist nicht sichergestellt. Die Fachdaten wurden durch ein Zwischensystem verändert! In diesem Fall wird ein Reject-Event gemäß Abschnitt Überprüfung des Fachdatensatzes > Hash-Prüfung erzeugt.

Nun zu den Anhängen*:

  1. Prüfen, ob Anhänge vorhanden sind. Wenn nein, können die Schritte 2. und 3. übersprungen werden.

  2. Für jeden Anhang: Berechnen eines mit dem Metadatenschema kompatiblen Hashes (aktuell: SHA-512) der entschlüsselten Anhänge.

  3. Für jeden Anhang: Prüfen, ob dieser Hash mit dem aus den Metadaten übereinstimmt (Feld contentStructure.attachments.*.hash.content).

    a. Wenn ja: Die Integrität des Anhangs ist sichergestellt.

    b. Wenn nein: Die Integrität des Anhangs ist nicht sichergestellt. Der Anhang wurde durch ein Zwischensystem verändert! In diesem Fall wird ein Reject-Event gemäß Abschnitt Überprüfung der Anlagen > Hash-Prüfung erzeugt.

Code-Beispiel zur Prüfung eines Hashwertes

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch einen Aufruf der Methode RequestSubmissionAsync(...) der SDK-Klasse Subscriber automatisch mit abgedeckt:

var receivedSubmission = await subscriber.RequestSubmissionAsync(submission.Id);

Das Beispiel ruft die Methode RequestSubmissionAsync(submission.Id) am Subscriber-Objekt auf. Der Methode wird die Id der Submission übergeben, die vom Zustelldienst geladen werden soll. Das Beispiel weist die erhaltene Submission der Variablen receivedSubmission zu. Der Quellcode ist ein Auszug aus einem Beispiel, das zeigt, wie Sie mit dem .NET-SDK Submissions vom Zustelldienst laden. Dieses Beispiel finden Sie auf der Seite Einreichung herunterladen.
Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".


Verwaltungsleistung abgleichen

Stimmt der Identifier serviceType/identifier im Endpunkt GET /v1/submissions/{submissionId} mit einem der Identifier services[]/identifier der Destination im Endpunkt GET /v1/destinations/{destinationId} überein?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/unsupported-service",
"title": "Verwaltungsleistung nicht unterstützt",
"detail": "Die angegebene Verwaltungsleistung wird nicht unterstützt.",
"instance": "metadata"
}

Fachdatensatz

Enthält die Einreichung einen Fachdatensatz?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/missing-data",
"title": "Fachdatensatz fehlt",
"detail": "Der Fachdatensatz fehlt.",
"instance": "metadata"
}

Fachdatenschema

Stimmt das ausgewählte Fachdatenschema mit einem der angebotenen überein? Die Angabe contentStructure/data/schema muss mit einem Eintrag unter submissionSchemas[] des ausgewählten Services (siehe oben) übereinstimmen.

Die Verarbeitung sollte ohne Prüfung des Fachdatenschemas fortgeführt werden.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/unsupported-schema",
"title": "Fachdatenschema nicht unterstützt",
"detail": "Das angegebene Fachdatenschema wird nicht unterstützt.",
"instance": "metadata"
}

Liste der Anlagen abgleichen

Stimmt die Liste der Anlagen in der Submission mit den Anlagen im Metadatensatz überein?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/attachments-mismatch",
"title": "Fehlerhafte Anlagen-Liste",
"detail": "Die Liste der Anlagen in Submission und Metadatensatz stimmt nicht überein.",
"instance": "metadata"
}

Rückkanal

Subscriber definieren die von ihnen unterstützten Rückkanaloptionen im Self-Service-Portal oder über die Self-Service API.

Ist im Metadatensatz einer Einreichung kein Rückkanal hinterlegt oder ein Rückkanal hinterlegt, der vom Subscriber nicht unterstützt wird, hat der Subscriber zwei Möglichkeiten:

  • a) Fallback auf den postalischen Rückkanal
  • b) Zurückweisung der Einreichung über ein Reject-Event mit folgendem problem:
{
"type": "https://schema.fitko.de/fit-connect/events/problems/unsupported-reply-channel",
"title": "Rückkanal nicht unterstützt",
"detail": "Der gewählte Rückkanal wird nicht unterstützt.",
"instance": "metadata"
}

Überprüfung des Fachdatensatzes

Authentication-Tag prüfen

Stimmt das Authentication-Tag mit dem im Submit-Submission-Event überein?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/incorrect-authentication-tag",
"title": "Authentication-Tag ungültig",
"detail": "Das Authentication-Tag des Fachdatensatzes ist ungültig.",
"instance": "data"
}

Entschlüsselung

Kann der Fachdatensatz entschlüsselt werden?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/encryption-issue",
"title": "Entschlüsselungs-Fehler",
"detail": "Der Fachdatensatz konnte nicht entschlüsselt werden.",
"instance": "data"
}

Sofern ein falscher oder veralteter Schlüssel verwendet wurde, der Fachdatensatz aber dennoch entschlüsselt werden konnte, sollte Verarbeitung fortgesetzt werden, aber eine entsprechende Meldung erfolgen.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/encryption-issue",
"title": "Entschlüsselungs-Fehler",
"detail": "Der Schlüssel {kid} ist nicht der zu diesem Zweck vorgesehene Schlüssel.",
"instance": "data"
}

Hash-Prüfung

Passt der Hash im Metadatensatz zu den entschlüsselten Daten?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/hash-mismatch",
"title": "Prüfsumme stimmt nicht",
"detail": "Die Prüfsumme des Fachdatensatzes stimmt nicht.",
"instance": "data"
}

Syntax-Validierung

Handelt es sich beim Fachdatensatz um valides JSON bzw. XML gemäß dem MIME-Type im Schema?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/syntax-violation",
"title": "Syntax-Fehler",
"detail": "Der Fachdatensatz ist kein valides JSON.",
"instance": "data"
}
{
"type": "https://schema.fitko.de/fit-connect/events/problems/syntax-violation",
"title": "Syntax-Fehler",
"detail": "Der Fachdatensatz ist kein valides XML.",
"instance": "data"
}

Schema-Prüfung

Ist der Fachdatensatz valide bezüglich des verwendeten Fachdatenschemas?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/schema-violation",
"title": "Schema-Fehler",
"detail": "Der Fachdatensatz ist nicht schema-valide.",
"instance": "data"
}

Überprüfung der Anlagen

Anlage laden

Kann das im Metadatensatz genannte Attachment geladen werden?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/missing-attachment",
"title": "Anlage fehlt",
"detail": "Die Anlage {attachmentId} konnte nicht geladen werden.",
"instance": "attachment:{attachmentId}"
}

Authentication-Tag prüfen

Stimmt das Authentication-Tag mit dem im Submit-Submission-Event überein?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/incorrect-authentication-tag",
"title": "Authentication-Tag ungültig",
"detail": "Das Authentication-Tag der Anlage {attachmentId} ist ungültig.",
"instance": "attachment:{attachmentId}"
}

Entschlüsselung

Kann die Anlage entschlüsselt werden?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/encryption-issue",
"title": "Entschlüsselungs-Fehler",
"detail": "Die Anlage {attachmentId} konnte nicht entschlüsselt werden.",
"instance": "attachment:{attachmentId}"
}

Sofern ein falscher oder veralteter Schlüssel verwendet wurde, die Anlage aber dennoch entschlüsselt werden konnte, sollte Verarbeitung fortgesetzt werden, aber eine entsprechende Meldung erfolgen.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/encryption-issue",
"title": "Entschlüsselungs-Fehler",
"detail": "Der Schlüssel {kid} ist nicht der zu diesem Zweck vorgesehene Schlüssel.",
"instance": "attachment:{attachmentId}"
}

Hash-Prüfung

Passt der Hash im Metadatensatz zu den entschlüsselten Daten?

{
"type": "https://schema.fitko.de/fit-connect/events/problems/hash-mismatch",
"title": "Prüfsumme stimmt nicht",
"detail": "Der Hash der Anlage {attachmentId} stimmt nicht.",
"instance": "attachment:{attachmentId}"
}

Inhaltliche Prüfung

Inhaltliche Prüfung, z.B. auf Viren oder Prüfung des Dateiformats: Wenn z.B. ein Word-Datei geschickt wurde, obwohl als Art „PDF“ angegeben wurde.

{
"type": "https://schema.fitko.de/fit-connect/events/problems/invalid-content",
"title": "Unzulässiger Inhalt",
"detail": "Der Inhalt der Anlage {attachmentId} ist nicht zulässig.",
"instance": "attachment:{attachmentId}"
}

Weitere Fehler

Technischer Fehler

Fehler bei der technischen Verarbeitung im empfangenden System

{
"type": "https://schema.fitko.de/fit-connect/events/problems/technical-error",
"title": "Technischer Fehler",
"detail": "Bei der Verarbeitung im empfangenden System trat ein technischer Fehler auf.",
"instance": "other"
}