Zum Hauptinhalt springen

Einreichung anlegen

Eine neue Einreichung anlegen​

Das Anlegen einer neuen Einreichung erfolgt über den Endpunkt POST /v2/submissions der Submission API. Hierbei legt das sendende System fest, an welchen Zustellpunkt die Einreichung versendet werden soll und welche Anlagen übermittelt werden sollen.

Hinweis

Eine Übermittlung von Einreichungen an einen Zustellpunkt ist nur möglich, wenn sich dieser im Status active befindet.

Anlagen werden dabei über UUIDs eindeutig identifiziert. Die UUIDs der Anlagen müssen eindeutig sein und werden vom sendenden System festgelegt.

Der Endpunkt erwartet folgende Parameter:

  • Eine Destination-ID. Dies ist die eindeutige UUID des Zustellpunktes, an den die Einreichung vermittelt werden soll (destinationId). Die Seite Zustellpunkt Ermitteln beschreibt, wie diese ermittelt werden kann.
  • Die Liste der angekündigten Anlagen (announcedAttachments). Dies ist eine Liste der Attachment-IDs aller Anlagen, die mit der Einreichung hochgeladen werden sollen. Die Liste enthält eine UUIDv4 für jedes Attachment. Die UUIDs müssen vom sendenden System selbst generiert werden. Für alle announcedAttachments muss anschließend das jeweilige Attachment hochgeladen werden (siehe Anlagen hochladen, bevor sich die Einreichung im Schritt Einreichung versenden abschließen lässt.
  • Der Typ der Verwaltungsleistung (publicService). Dies ist eine Beschreibung der Art der Verwaltungsleistung. Die Verwaltungsleistung muss eine der angebotenen Verwaltungsleistungen des Zustellpunkts sein. Wenn Sie das .NET- oder Java-SDK von FIT-Connect verwenden, um eine Einreichung anzulegen, dann überprüft das SDK automatisch, ob die angegebene Verwaltungsleistung vom adressierten Zustellpunkt angeboten wird (zudem überprüft das SDK, ob der Zustellpunkt das Fachdatenschema der Einreichung unterstützt). Für die jeweilige Verwaltungsleistung muss immer sowohl ein Name (name), als auch ein eindeutiger Identifier (identifier) angegeben werden. Der Identifier besteht aus einem Leistungsschlüssel und dem Präfix urn:de:fim:leika:leistung:. Ist für die gegebene Verwaltungsleistung kein Leistungsschlüssel vorhanden, kann die Verwaltungsleistung übergangsweise über die Angabe einer anderen eindeutigen Schema-URN beschrieben werden. Bestehende Leistungsschlüssel können über das FIM-Portal oder über die LeiKa-Suche (inoffiziell) ermittelt werden.
  • Optional kann hier auch ein Callback hinterlegt werden, um Benachrichtigungen über neue Events der Einreichung zu erfahren. Näheres dazu wird im Artikel Verwendung von Callbacks beschrieben.
  • Das optionale Feld region kann ähnlich wie der Leistungsidentifikator (service-type) verwendet werden, um im empfangenden Verwaltungssystem ein internes nachgelagertes Routing zu steuern. Unterstützt ein Zustellpunkt z.B. eine Verwaltungsleistung mit mehreren zugeordneten Regionen, kann das Verwaltungssystem beim Abrufen einer Einreichung anhand der Region erkennen, wie sie verarbeitet werden muss. Beispielsweise durch übergabe an den passenden internen Mandanten. Bitte beachten Sie: Wenn Sie dieses optionale Feld verwenden, prüft der FIT-Connect-Zustelldienst, ob es beim empfangenden Zustellpunkt eine Übereinstimmung mit Leistung und Region der Einreichung gibt und gibt ggf. beim Versenden der Einreichung schon beim Anlegen derselben eine Fehlermeldung zurück. Eine Übereinstimmung besteht, wenn folgende Bedingungen zutreffen:
    • Der Zustellpunkt unterstützt eine Verwaltungsleistung, deren Kennung mit dem Leistungs-Identifikator der Einreichung übereinstimmt.
    • Der in der Region der Einreichung angegebene Regionalschlüssel stimmt mit einem der dieser Verwaltungsleitung zugeordneten Regionalschlüssel überein oder beginnt mit ihm.
Hinweis

Die für das Anlegen von Einreichungen notwendige Struktur von Einreichungen und die Referenzierung von Fachdatenschemata ist im Artikel Aufbau einer Einreichung näher beschrieben.

Hinweis

Die URL der Submission API findet sich im Artikel Betriebsumgebungen.

Verhalten bei vorliegender Absenderbeschränkung im adressierten Zustellpunkt​

Mit Hilfe der Destination-API können Behörden eine Liste von erlaubten Sendern pflegen. Sollte eine solche Liste in einem Zustellpunkt gepflegt und die Prüfung aktiv geschaltet sein, wird bei Adressierung der Einreichung an diesen Zustellpunkt vom Zustelldienst eine Prüfung vorgenommen. Bei dieser Prüfung wird die Client-ID des Senders mit der Liste der erlaubten Sender abgeglichen. Sollte der Sender nicht in der Liste enthalten sein, wird mit HTTP 403 Forbidden geantwortet. Somit können nur explizit berechtigte Onlinedienste erfolgreich Einreichungen an einen Zustellpunkt mit aktiver Absenderbeschränkung senden. Alle Einreichungen unberechtigter Onlinedienste werden abgelehnt.

Fehlermeldung
{
    "type": "https://schema.fitko.de/fit-connect/submission-api/problems/access-forbidden",
    "title": "Forbidden",
    "status": 403,
    "instance": "/submission-api/v2/submissions",
    "errorcode": "b07c88fc-79ac-4be7-a272-fa2d95ab7e28"
}

Das untenstehende Flussdiagramm soll den Prozess nochmal veranschaulichen.

Flussdiagramm Absenderbeschränkung

Konfigurieren einer Absenderbeschränkung via Self-Service-Portal​

Zunächst muss im gewünschten Zustellpunkt der Menüpunkt "Absenderbeschränkung" durch einen Klick auf die zugehörige Checkbox aktiviert werden:

Absenderbeschränkungen aktivieren

Bei aktivierter Checkbox ist die Absenderbeschränkung aktiv, d.h. nicht ausdrücklich authorisierte Onlinedienste dürfen keine Einreichungen übermitteln. Darunter werden zwei Sektionen zur Verwaltung der Absenderbeschränkungen angezeigt. Diese können jeweils durch einen Klick auf das Chevron (Dreieck) rechts oben aufgeklappt werden.

Absenderbeschränkungen konfigurieren

Unter "Eigene Onlinedienste" werden die vom aktiven Benutzer verwaltbaren Onlinedienste aufgelistet. Durch Aktivierung der jeweiligen Checkbox wird dem Onlinedienst erlaubt, Einreichungen an den Zustellpunkt vorzunehmen.

Unter "Fremde Onlinedienste" können durch Eingabe der zugehörigen Onlinedienst-ID auch solche Onlinedienste zur Einreichung berechtigt werden, die nicht durch den aktiven Benutzer verwaltet werden. Um die Berechtigung zu widerrufen, muss der Eintrag wieder gelöscht werden.

Beispiele für Absenderbeschränkungen

Prüfung auf vorhandene Absenderbeschränkungen​

Es kann vor Anlage einer Einreichung abgefragt werden, ob eine Beschränkung bei einem Zustellpunkt vorliegt. Dazu kann als Sender über den öffentlichen Destination-Endpunkt die Liste der erlaubten Sender abgefragt werden. Zusätzlich lässt sich feststellen, ob die Sender-Prüfung aktiv ist.

Abruf der Sender-Beschränkungen
$ SUBMISSION_API=https://test.fit-connect.fitko.dev/submission-api
$ DESTINATION_ID=645e8bbe-1fde-45d9-8d97-2bdc4918e275
$ curl -X GET "$SUBMISSION_API/v2/destinations/$DESTINATION_ID"

{
    "destinationId": "645e8bbe-1fde-45d9-8d97-2bdc4918e275",
    "status": "active",
    # der restliche Response-Body wurde der Übersicht halber abgeschnitten
    "senderAccessRestricted": {
        "enabled": true, # die Sender-Prüfung ist aktiv
        "allowedSenders": [
            "ecde9720-2b34-4d53-a523-c11256eed1e5",
            "ac5202ff-ce25-4528-ae9a-e971f9469678"
        ]
    }
}

Code-Beispiele​

Das folgende Beispiel zeigt, wie Sie das .NET-SDK nutzen, um eine Einreichung (Submission) anzulegen. Auf der Seite Einreichung versenden finden Sie ein Beispiel, wie Sie die hier angelegte Submission senden.
Um eine Einreichung anzulegen, stellen Sie zunächst die Werte bereit, die für den Aufruf der Methoden der Klasse SendableSubmission erforderlich sind:

var destinationId = "aa3704d6-8bd7-4d40-a8af-501851f93934";
var serviceIdentifier = "urn:de:fim:leika:leistung:99400048079000";

Anschließend erzeugen Sie eine sendbare Submission. Dazu rufen Sie die Methoden der Klasse SendableSubmission in der folgenden Reihenfolge auf:

var sendableSubmission = SendableSubmission.Builder()
            .SetDestination(destinationId)
            .SetServiceType(serviceIdentifier, "FIT Connect Demo")
            .SetJsonData("{\"message\":\"Hello World\"}")
            .AddAttachments(new Attachment("./Attachments/Test.pdf", "Test Attachment"),
                new Attachment("./Attachments/Test.pdf", "Test Attachment #2"),
                new Attachment(null, "Json Text Attachment", MediaTypeNames.Application.Json,
                    Encoding.UTF8.GetBytes("{\"message\":\"Hello World\"}"))
            )
            .SetAuthenticationInformation(new AuthenticationInformation("12345",
                AuthenticationInformationType.IdentificationReport, "1.3.5"))
            .SetPaymentInformation(new PaymentInformation(PaymentMethod.Creditcard,
                PaymentStatus.Booked, "12345445", "2345566"))
            .SetReplyChannel(
                new ReplyChannel {
                    DeMail = new DeMail(address: "klaus.fischer@trash.de-mail.de")
                })
            .Build();

Mit der Klasse SendableSubmission erzeugen Sie eine sendbare Einreichung, der Sie unverschlüsselte Daten übergeben. Die Daten werden dann intern verschlüsselt. Wenn Sie bereits verschlüsselte Daten einer Submission hinzufügen wollen, dann verwenden Sie die Klasse SendableEncryptedSubmission. Die Klassen SendableSubmission und SendableEncryptedSubmission sind im Hauptmenü unter "SDKs > .NET-SDK > Sender entwickeln" beschrieben.
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".