Zum Hauptinhalt springen

.NET-SDK

Sender implementieren​

Ein sendendes System mit .NET-SDK entwickeln​

Sendende Systeme senden Anträge über FIT-Connect an einen Empfänger. Das Senden von Anträgen (Einreichungen) ist hier im Detail beschrieben. Wenn Sie das .NET-SDK nutzen, dann können Sie sich auf den Aufruf der Schnittstelle zum SDK konzentrieren, weil das SDK viele Details intern automatisch umsetzt.

Beispiel für einen Sender​

Das folgende Beispiel zeigt, wie Sie mit dem .NET-SDK eine Einreichung (Submission) erzeugen und an einen Zustellpunkt senden.

1. Schritt: Sender erstellen​

Sie erstellen einen Sender mit der Methode GetSenderClient(...) der SDK-Klasse ClientFactory.

var sender = ClientFactory
            .GetSenderClient(FitConnectEnvironment.Test, clientId, clientSecret, logger)

Parameter der Methode ClientFactory.GetSenderClient()​

  • FitConnectEnvironment
    Im Beispiel oben stellt das Feld FitConnectEnvironment.Test des .NET-SDKs die FIT-Connect-Endpunkte zur Verfügung, die aufgerufen werden sollen.
  • ClientId, ClientSecret
    Sender benötigen eine ClientId und ein ClientSecret. Hier ist beschrieben, wie Sie eine ClientID und ein ClientSecret erhalten.
  • Logger
    Dieser Parameter ist optional.

2. Schritt: Submission erstellen​

Sie erstellen eine Submission mit den SDK-Methoden SendableSubmission.Builder() und SendableEncryptedSubmission.Builder().
Mit diesen Methoden erstellen Sie Submissions, die Sie senden können, d. h., die Submissions sind "versendbar".

Zwei Varianten​

Das .NET-SDK kann im Umfeld einer Webapplikation im Backend eingesetzt werden. Bei diesem Anwendungsfall können die Daten sowohl verschlüsselt (zum Beispiel über das JavaScript-SDK, noch in Entwicklung) als auch unverschlüsselt vom Browser an das .NET-SDK im Backend übergeben werden. Überträgt das Frontend Antragsdaten unverschlüsselt an das Backend, dann verschlüsselt das .NET-SDK intern die Daten und überträgt diese über FIT-Connect an das adressierte Fachverfahren (Zustellpunkt).

Beim Erstellen einer versendbaren Submission gibt es daher zwei Varianten:

  • Bei der ersten Variante verwenden Sie die Methode SendableEncryptedSubmission.Builder() und übergeben dieser Methode bereits verschlüsselte Daten. Diese Variante ist im Abschnitt Vorverschlüsselte Daten übergeben beschrieben.
  • Bei der zweiten Variante verwenden Sie die Methode SendableSubmission.Builder() und übergeben dieser Methode unverschlüsselte Daten, die dann intern verschlüsselt werden. Diese Variante ist im Abschnitt Unverschlüsselte Daten übergeben beschrieben.

Vorverschlüsselte Daten übergeben​

Sie übergeben der SDK-Klasse SendableEncryptedSubmission.Builder() bereis verschlüsselte Daten:
Werden die Antragsdaten bereits vom Endgerät der Anwender:in verschlüsselt, so ist eine Ende-zu-Ende-Verschlüsselung möglich und die Antragsdaten liegen im Backend des Senders (Onlinedienst) lediglich verschlüsselt vor. Der Server des Onlinedienstes hat keinen Einblick in die Klardaten.
Zur Verschlüsselung von Antragsdaten im Frontend eines Onlinedienstes (im Browser der Antragsteller:in) kann das JavaScript-SDK von FIT-Connect genutzt werden.
Das JavaScript-SDK verschlüsselt die Antragsdaten im Webbrowser und das .NET-SDK im Backend des Onlinedienstes sendet die verschlüsselten Daten an den Zustelldienst weiter.
Das JavaScript-SDK benötigt für die Verschlüsselung der Antragsdaten den PublicKey des Zustellpunktes, an den der Antrag über FIT-Connnect gesendet werden soll. Der öffentliche Schlüssel des Zustellpunktes MUSS vom .NET-SDK im Backend des Onlinedienstes entsprechend der kryptographischen Vorgaben validiert werden.
Um den PublicKey des Zustellpunktes abzurufen und zu validieren, kann die Methode GetPublicKeyForDestinationAsync des .NET-SDK verwendet werden:

var publicKey = await ClientFactory
            .GetSenderClient(FitConnectEnvironment.Test, clientId, clientSecret, logger)
            .GetPublicKeyForDestinationAsync(destinationId);

Mit diesem PublicKey sind die Metadaten, die Fachdaten und die Anlagen im JavaScript-SDK zu verschlüsseln.
Weitere Informationen finden sich im Artikel Verschlüsselte Übertragung von Antragsdaten der FIT-Connect-Dokumentation.

Nachdem die verschlüsselten Daten vom Browser an das Backend des Onlinedienstes übermittelt wurden, können diese mit der Methode SendableEncryptedSubmission.Builder zu einer Submission verbunden werden, die dann versendet werden kann.


var sendableEncryptedSubmission = SendableEncryptedSubmission.Builder()
            .SetDestination(destinationId)
            .SetServiceType(serviceIdentifier, "FIT Connect Demo")
            .SetEncryptedMetadata(encryptedMetadata)
            .SetEncryptedData(encryptedData)
            .AddEncryptedAttachments(encryptedAttachments)
            .Build();
var sentSubmission = await ClientFactory
            .GetSenderClient(FitConnectEnvironment.Test, clientId, clientSecret, logger)
            .SendAsync(sendableEncryptedSubmission);
Wichtiger Hinweis

Bei der Übernahme der Destination-ID und des Service-Identifiers aus dem Frontend MUSS im Backend geprüft werden, ob ein Versand von Einreichungen dieser Leistung an den angegebenen Zustellpunkt zulässig ist. Wenn Sie das SDK verwenden, dann wird diese Überprüfung automatisch durch das SDK durchgeführt.

Unverschlüsselte Daten übergeben​

Sie übergeben der Methode SendableSubmission.Builder() unverschlüsselte Daten, die dann intern verschlüsselt werden:
Wenn das Frontend Antragsdaten unverschlüsselt an das Backend sendet, dann können Sie im Backend mit SendableSubmission.Builder() die Antragsdaten in ein verschlüsseltes Submission-Objekt umwandeln und verschlüsselt über FIT-Connect an das adressierte Fachverfahren (Subscriber) übertragen. Diese Umsetzungsvariante bietet eine geringere Sicherheit als die Umsetzung der Ende-zu-Ende-Verschlüsselung ab dem Endgerät (Webbrowser) der Antragsteller:in. Zudem steigen bei dieser Umsetzungsvariante die Anforderungen an die IT-Sicherheit und den Datenschutz, da Antragsdaten im Klartext durch das Backend des Onlinedienstes verarbeitet werden.
Eine Alternative stellt die Verschlüsselung von Antragsdaten im Frontend des Onlinedienstes dar (siehe Abschnitt Vorverschlüsselte Daten übergeben).

var sender = ClientFactory
            .GetSenderClient(FitConnectEnvironment.Test, clientId, clientSecret, logger)

var sendableSubmission = SendableSubmission.Builder()
            .SetDestination(destinationId)
            .SetServiceType(serviceIdentifier, "FIT Connect Demo")
            .SetJsonData("{\"message\":\"Hello World\"}")
            .AddAttachments(
                Attachment.FromPath("./Attachments/Test.pdf","application/pdf", description: "Test Attachment"),
                Attachment.FromPath("./Attachments/Test.pdf", "application/pdf",description: "Test Attachment #2"),
                Attachment.FromString("{\"message\":\"Hello World\"}",
                    MediaTypeNames.Application.Json, "data.json")
            )
            .SetAuthenticationInformation(new AuthenticationInformation("12345",
                AuthenticationInformationType.IdentificationReport, "1.3.5"))
            .SetPaymentInformation(new PaymentInformation(PaymentMethod.Creditcard,
                PaymentStatus.Booked, "12345445", "2345566"))
            .SetReplyChannel(ReplyChannel.FromEMail("a@example.com"))
            .Build();

Die Methoden der Klasse SendableSubmission sind hier beschrieben.

Hinweis

Wenn Ihnen die destinationId nicht vorliegt, dann können Sie sie mithilfe der Methode FindDestinationsAsync(...) der Klasse Router erfragen. Hier finden Sie eine Beschreibung dazu.

3. Schritt: Submission senden​

Sie senden eine Submission mit der Methode SendAsync(...) der SDK-Klasse Sender. 

await sender.SendAsync(sendableSubmission);

Async-Aufrufe vermeiden​

Um async/await Aufrufe zu vermeiden, können Sie Result verwenden:

ClientFactory.GetSenderClient(FitConnectEnvironment.Test, clientId, clientSecret, logger)
            .SendAsync(sendableSubmission)
            .Result;

Rückgabewerte​

Nach der Übertragung eines Antrags (einer Einreichung) liefert Ihnen die Methode SendAsync(...) des Senders ein Objekt des Typs SentSubmission zurück. Dieses Objekt enthält unter anderem die SubmissionId des übertragenen Antrags. Die SubmissionId besitzt den Datentyp Guid und ist das eindeutige Kennzeichen des gesendeten Antrags. Zudem enthält der Typ SentSubmission auch die AuthenticationTags, die zum Prüfen des Status des Antrags (der Submission) benötigt werden.


SentSubmission mySub = ClientFactory.GetSenderClient(FitConnectEnvironment.Test, clientId, clientSecret, logger)
            .SendAsync(sendableSubmission)
            .Result;

string SubmissionId = mySub.SubmissionId;

4. Schritt: Status überprüfen​

Den Status der Submission vom Zustelldienst abrufen​

Nach dem Senden rufen Sie den Status der gesendeten Submission vom Zustelldienst ab. Dazu dient die Methode GetStatusForSubmissionAsync() der Klasse Sender:

var (status, problems) = await sender.GetStatusForSubmissionAsync(sentSubmission);

Die Methode GetStatusForSubmissionAsync(...) ist hier beschrieben.

SendableSubmission und SendableEncryptedSubmission​

Die Klassen SendableSubmission und SendableEncryptedSubmission sind für die Erstellung einer Submission zuständig, die gesendet werden kann. Das Senden der Submission an FIT-Connect übernimmt dann der Sender. Nachfolgend sind die Methoden der Klasse SendableSubmission und SendableEncryptedSubmission beschrieben.

Bidirektionale Kommunikation (BiDiKo)​

Dialog zwischen Sender und Empfänger​

Nach dem Versenden der ersten Submission ist in FIT-Connect ein direkter Dialog zwischen Sender und Empfänger möglich, wenn Sie die Bidirektionale Kommunikation (BiDiKo) verwenden.

Bei BiDiKo tauschen Sender und Empfänger direkt Nachrichten miteinander aus:

  • Der Sender sendet einen Antrag (auch Einreichung oder Submission genannt) über FIT-Connect an den Empfänger mit den für die Bidirektionale Kommunikation notwendigen Informationen. Der Sender wird im SDK auch Sender-Client genannt.
  • Der Empfänger antwortet auf diese Einreichung, indem er eine Nachricht über FIT-Connect an den Sender zurücksendet. Diese Rücksendung kann zum Beispiel ein Bescheid oder eine Rückfrage zum eingereichten Antrag sein. Die Rücksendung des Empfängers wird als Antwort oder Reply bezeichnet. Der Empfänger wird im SDK auch Subscriber oder Subscriber-Client genannt.
  • Der Sender kann nun auf die Antwort reagieren und eine neue Einreichung an den Empfänger senden. Alle Einreichungen als auch alle dazugehörigen Antworten (Replies) werden über dieselbe Vorgangsnummer (Case-ID) identifiziert. Über diesen Bezug auf diese Case-ID können nun beide Parteien beliebig oft und in beliebiger Reihenfolge Nachrichten versenden.

Um die BiDiKo zu nutzen, verwenden Sie FIT-Connect als Rückkanal (ReplyChannel):
Rufen Sie am SendableSubmission.Builder() die Methode SetReplyChannel(...) auf und setzen Sie den ReplyChannel auf ReplyChannel.FromFitConnect() (siehe Beispiel weiter unten zum SendableSubmission.Builder).

Schlüsselpaar erzeugen​

Um dem Empfänger (z. B. einem Fachverfahren) die Möglichkeit zu geben, Antworten (Replies) zu verschlüsseln, müssen Sie im ReplyChannel einen öffentlichen Verschlüsselungsschlüssel übergeben. Der Empfänger muss diesen öffentlichen Schlüssel verwenden, um die Antworten zu verschlüsseln.
Sie können den öffentlichen Schlüssel mit der Utility-Klasse ReplyChannelKeyGenerator erzeugen (Für den Rückkanal ist kein V-PKI Zertifikat notwendig). Der Key-Generator generiert ein Schlüsselpaar mit einem öffentlichen Verschlüsselungsschlüssel und dem dazugehörigen privaten Entschlüsselungsschlüssel. Der private Schlüssel diese Schlüsselpaars wird vom Sender (z. B. einem Onlinedienst) benötigt, um die Replies des Empfängers zu entschlüsseln. Sie sollten ein Schlüsselpaar für die Dauer eines Vorgangs (Case) beibehalten. Das Schlüsselpaar sollte nur bei sicherheitskritischen Vorfällen geändert werden.

// Onlinedienst erzeugt Schlüsselpaar (einmal pro Case)
var keySet = ReplyChannelKeyGenerator.GenerateKeyPair();
// Der private Schlüssel wird vom Onlinedienst sicher verwahrt
var privateReplyDecryptionKey = keySet.DecryptionPrivateKey;
// Der öffentliche schlüssel wird vom Empfänger (Fachverfahren) genutzt um den Reply zu verschlüsseln
var publicReplyEncryptionKey = keySet.EncryptionPublicKey;
Einsatz der generierten Keys

Sie können Schlüssel, die Sie mit ReplyChannelKeyGenerator erzeugen, nicht bei der Einrichtung eines Zustellpunktes verwenden, da sie nicht auf einem Zertifikat der V-PKI basieren. Es handelt sich hierbei um sogenannte Ephemeral Keys, die nur zum Ver- und Entschlüsseln von Replies innerhalb eines Vorgangs eingesetzt werden.

Nachdem Sie ein Schlüsselpaar erzeugt haben, fügen Sie den öffentlichen Schlüssel dem ReplyChannel hinzu: ReplyChannel.FromFitConnect(JsonConvert.SerializeObject(publicReplyEncryptionKey), ...) (siehe folgendes Beispiel).

Submission einem Vorgang zuordnen​

Sie setzen bei allen Einreichungen (Submissions), die zu einem Vorgang gehören, dieselbe Vorgangsnummer (Case-ID) aus der ersten Vorgangsübermittlung. Das folgende Beispiel verwendet die Vorgangsnummer existingCaseId eines bestehenden Vorgangs, um eine neue Submission diesem Vorgang (Case) hinzuzufügen.

Sie müssen dem replyChannel den zuvor generierten publicKey mitgeben und auch den zulässigen Prozessstandard für den Rückkanal definieren. Im Anschluss kann die Submission über den SenderClient gesendet werden: 

var replyChannel = ReplyChannel.fromFitConnect(JsonConvert.SerializeObject(publicReplyEncryptionKey), new[] {"urn:xoev-de:bmk:standard:xbau_2.3"})

// Die caseId für einen bestehenden Vorgang kann von einer bereits gesendeten Submission bezogen werden
var existingCaseId = sentSubmission.CaseId;

var sendableSubmission = SendableSubmission.Builder()
        .SetDestination(Guid.Parse("d2d43892-9d9c-4630-980a-5af341179b14"))
        .SetServiceType("urn:de:fim:leika:leistung:99900000000000", "FIT Connect Demo")
        .SetJsonData("{\"message\":\"Hello World\"}", new URI("urn:xoev-de:bmk:standard:xbau_2.2#baugenehmigung.antrag.0200"))
        // hinzufügen der neuen Submission zu einem bestehenden Vorgang
        .SetCaseId(existingCaseId)
        // wird für die FIT-Connect Reply-Channel Kommunikation benötigt
        .SetReplyChannel(replyChannel)
        .Build();

var senderClient = ClientFactory.GetSenderClient(_environment, senderConfig.ClientId, senderConfig.ClientSecret, Logger);

var sentSubmission = senderClient.SendAsync(sendableSubmission).Result;

Abholbereite Replies erfragen​

Das Laden von Replies erfolgt in zwei Schritten.

  • Erfragen, ob abholbereite Replies vorliegen
  • Abholen eines bestimmten Replys

Um zu erfragen, ob Replys auf FIT-Connect vorliegen, rufen Sie die Methode GetReplies auf:

var senderClient = ClientFactory.GetSenderClient(_environment, senderConfig.ClientId, senderConfig.ClientSecret, Logger);

// Abrufen der ersten 100 Replies für eine caseId
int offset = 0;
int limit = 100;
var availableReplies = senderClient.GetReplies(offset, limit);

Callback für Replies​

Alternativ zur Methode GetReplies können Sie einen Callback verwenden, eine Webadresse, die das Backend Ihres Senders (z. B. Onlinedienstes) bereitstellt. FIT-Connect ruft dann diesen Callback auf, um darüber zu informieren, dass eine Antwort (Reply) abgeholt werden kann.

Einen Reply abrufen​

Mit der Methode ReceiveReplyForCase (siehe folgendes Beispiel) laden Sie eine Liste abholbereiter Replies (IReceivedReply) inklusive der Fach- und Metadaten sowie der Anhänge (Attachments), falls Anhänge vorhanden sind. Sie übergeben dieser Methode die caseId der zu ladenden Replies und den privaten Entschlüsselungsschlüssel, den Sie vor dem Senden der zugehörigen Einreichung (Submission) erzeugt haben. Der private Schlüssel dient zum Entschlüsseln der Reply. Das Kapitel Schlüsselpaar erzeugen beschreibt das Erzeugen des öffentlichen Verschlüsselungsschlüssels und des privaten Entschlüsselungsschlüssels.

var caseId = sentSubmission.CaseId;
// Key zum Entschlüsseln wird vom Onlinedienst gespeichert und muss beim Abholen von Replies zur Verfügung stehen
var privateReplyDecryptionKey = KeySet.DecryptionPrivateKey.ToString();

var receivedReply = Sender.ReceiveReplyForCase(caseId, privateReplyDecryptionKey).Result;

Hinweis

Das SDK prüft beim Abruf von Replies die erhaltenen Daten.
Schlägt eine Prüfung fehl, dann wird der Reply automatisch vom SDK zurückgewiesen. Das bedeutet, dass ein REJECT-Event in das Event-Log eingetragen wird, mit der darauf folgenden Löschung des invaliden Replys.

Dieses Verhalten ist in den Umgebungen PROD, STAGE und TEST aktiv, kann jedoch über die Environment mit environment.ValidationSettings.DisableAutoReject = false deaktiviert werden.

Zugriff auf Fach- und Metadaten​

Sie können über den ReceivedReply auf die Fach- und Metadaten sowie auf die Attachments des Replys zugreifen, nachdem der Reply geladen, entschlüsselt und erfolgreich validiert wurde:

 // Zugriff auf Fachdaten
string data = receivedReply.Data;
URI dataSchemaUri = receivedReply.DataSchemaUri;
string mimeType = receivedReply.DataMimeType;

// Zugriff auf Metadaten
Metadata metadata = receivedReply.Metadata;

// Zugriff auf Rückkanal
ReplyChannel replyChannel = metadata.ReplyChannel;

// Zugriff auf Attachments
foreach (Attachment attachment in receivedReply.Attachments){
    string originalFilename = attachment.Filename;
    string attachmentMimeType = attachment.MimeType;
    // Rohdaten des Attachments als byte[]
    byte[] attachmentDataAsBytes = attachment.GetBytes();
    // Rohdaten des Attachments als String (per default UTF-8 encoded)
    string attachmentDataAsString = attachment.GetData();
}

// Zugriff auf IDs
GUID replyId  = receivedReply.ReplyId;
GUID caseId  = receivedReply.CaseId;
GUID submissionId  = receivedReply.SubmissionId;

Empfangsbestätigung für Replies​

Um einen Reply zu akzeptieren oder abzulehnen, sendet der Sender entsprechende Events an das Event-Log (siehe folgende Beispiele fürs Akzeptieren und Ablehnen).

Event Log

Weitere Details finden Sie in der Dokumentation zu Events und zum Erzeugen von Security Event Tokens.

Reply akzeptieren​

Nach der Prüfung durch den Sender (Sender-Client) können Sie den Reply mit einem accept-reply-Event annehmen. Sie können diesem Event Problems hinzufügen, die als Anmerkungen zu sehen sind, die nicht zur Zurückweisung des Replys führen:

var senderClient = ClientFactory.GetSenderClient(_environment, senderConfig.ClientId, senderConfig.ClientSecret, Logger);

// Akzeptieren des Replys ohne Angabe von Problems
senderClient.AcceptReplyAsync(receivedReply);

// Akzeptieren des Replys mit einer Liste von Problems
senderClient.AcceptReplyAsync(receivedReply, new []{ new MyCustomProblem()});
Hinweis

Nach dem Senden des accept-reply-Events wird der Reply in den Status deleted überführt und im Zustelldienst gelöscht.

Reply zurückweisen​

Wenn die Prüfung durch den Sender (Sender-Client) negativ ausfällt, zum Beispiel bei einer semantischen Unstimmigkeit in den Fachdaten (Städtename ist nicht real, Alter der Person ist nicht plausibel), dann kann der Reply zurückgewiesen werden.
Weitere Details finden Sie unter den verfügbaren (technischen) Problemen.

var senderClient = ClientFactory.GetSenderClient(_environment, senderConfig.ClientId, senderConfig.ClientSecret, Logger);
var replyId = receivedReply.ReplyId;

// Senden der Zurückweisung mit einer Liste von Problemen
senderClient.RejectReplyAsync(replyId, new []{ new MyCustomProblem()}, new []{ new AnotherCustomProblem()})));

Nach Senden des reject-reply-Events wird der Reply in den Status deleted überführt und im Zustelldienst gelöscht.

FluentAPI​

Die Methoden der Klassen SendableSubmission und SendableEncryptedSubmission lassen sich aufgrund der FluentAPI nur in einer bestimmten Reihenfolge aufrufen. Sie können aber optionale Parameter in beliebiger Reihenfolge setzen. Die folgenden Parameter sind optional:

  • attachments
  • auth
  • payment
  • reply

Die folgende Grafik zeigt die Reihenfolge der Aufrufe bei der Klasse SendableSubmission:

SendableSubmission


Die folgende Grafik zeigt die Reihenfolge der Aufrufe bei der Klasse SendableEncryptedSubmission:

SendableEncryptedSubmission

Methoden der Klasse SendableSubmission:​

Builder()​

Mit der Methode Builder() erhalten Sie den Builder für eine neue Submission, der Sie unverschlüsselte Daten übergeben. Die Daten werden verschlüsselt, wenn Sie die Methode Build() aufrufen. Diese Methode ist hier beschrieben.

SetDestination(destinationId)​

Mit der Methode SetDestination(...) übergeben Sie die DestinationId, die ID der Destination (des Zustellpunktes), an die die Submission gesendet werden soll.
Ein Zustellpunkt ist ein technisch eindeutig adressierbarer Endpunkt zur Einreichung von Anträgen oder Berichten an die für diese Verwaltungsleistung zuständige Behörde über die FIT-Connect-Übermittlungsinfrastruktur. Ein Zustellpunkt beschreibt die Konfiguration eines konkreten empfangenden Systems (Fachverfahren oder virtuelle Poststelle). Ein Zustellpunkt wird auch Destination genannt und ist durch seine DestintionId eindeutig bestimmt. Die DestintionId besitzt den Datentyp Guid. Eine Möglichkeit, die DestinationId zu ermitteln, geht über die Methode FindDestinationId() des Senders.

SetServiceType(serviceIdentifier, "FIT Connect Demo")​

Mit der Methode SetServiceType(...) übergeben Sie den Service-Identifier.
Service-Identifier besitzen die Form urn:de:fim:leika:leistung:99400048079000 und den Datentyp string. Zudem übergeben Sie mit dieser Methode den Namen der beantragten Leistung, im Beispiel oben "FIT Connect Demo".

SetJsonData("{"message":"Hello World"}", new Uri("https://schema.example.com"))​

Mit der Methode SetJsonData(...) übergeben Sie eine Nachricht an den adressierten Zustellpunkt im Datenformat JavaScript Object Notation (JSON). Tragen Sie die Nachricht direkt in die Methode ein (wie im Beispiel oben) oder übergeben Sie eine Variable mit dem Datentyp string. Um eine Prüfung der Daten zu ermöglichen wird das Schema der Daten mit übergeben.

AddAttachments(...)​

Mit der Methode AddAttachments(...) fügen Sie Ihrem Antrag (der Submission) einen oder mehrere Anhänge hinzu. Ein Anhang ist eine Instanz der Klasse Attachment, die erzeugt wird, wenn Sie die statische Methode Attachment.FromPath(...) aufrufen (siehe Beispiel oben). Zudem zeigt das Beispiel, wie Sie ein Attachment mit der Methode Attachment.FromString(..) erstellen.

SetAuthenticationInformation(...)​

Mit der Methode SetAuthenticationInformation(...) fügen Sie Ihrem Antrag Informationen zur verwendeten Authentifikationsmethode hinzu.

SetPaymentInformation(...)​

Mit der Methode SetPaymentInformation(...) fügen Sie Ihrem Antrag Informationen zur verwendeten Paymentmethode hinzu (Art der Bezahlung der Gebühren für den Antrag).

SetReplyChannel(...)​

Mit der Methode SetReplyChannel(replyChannel) fügen Sie dem Antrag einen Rückkanal (ReplyChannel) hinzu, über den Sie Nachrichten vom Empfänger des Antrags erhalten wollen. Im Beispiel oben wurde als Rückkanal "DeMail" gewählt: Die für den Antrag zuständige Behörde soll über De-Mail Bescheide oder Nachrichten zustellen. Sie übergeben der Methode SetReplyChannel(replyChannel) einen ReplyChannel, der dem Interface IReplyChannelType entspricht (DeMail, Elster, EMail oder Fink). Ein ReplyChannel kann nur von der Factory ReplyChannel.FromType(...) erstellt werden.

Build()​

Mit der Methode Build() erstellen Sie eine Submission, die an den adressierten Zustellpunkt gesendet werden kann. Im Beispiel oben ist der Antrag in der Variablen sendableSubmission nach dem Aufruf dieser Methode enthalten.

Methoden der Klasse SendableEncryptedSubmission:​

Builder()​

Mit der Methode Builder(...) erhalten Sie den Builder für eine neue Submission, der Sie vorverschlüsselte Daten übergeben.

SetDestination(destinationId)​

Die Methode SetDestination(...) ist hier beschrieben.

SetServiceType(serviceIdentifier, "FIT Connect Demo")​

Die Methode SetServiceType(...) ist hier beschrieben.

AddEncryptedMetadata(...)​

Mit der Methode AddEncryptedMetadata fügen Sie der Submission Metadaten hinzu, die bereits verschlüsselt sind.

AddEncryptedData(...)​

Mit der Methode AddEncryptedData fügen Sie der Submission Antragsdaten hinzu, die bereits verschlüsselt sind.

AddEncryptedAttachments(...)​

Mit der Methode AddEncryptedAttachments fügen Sie der Submission Anhänge hinzu, die bereits verschlüsselt sind.

Build()​

Die Methode Build() ist hier beschrieben.

Methoden der Klasse ClientFactory​

GetSenderClient(...)​

Mit der Methode GetSenderClient(...) erhalten Sie Zugriff auf den Sender, d. h., die Methode gibt die Referenz auf eine Instanz der Klasse Sender zurück. Sie übergeben der Methode das gewünschte FIT-Connect-Environment sowie die Credentials (clientId und clientSecret). Der Parameter logger ist optional. Wird er übergeben, dann muss er das Interface Microsoft.Extensions.Logging.ILogger implementieren.

GetSubscriberClient(...)​

Mit der Methode GetSubscriberClient(...) erhalten Sie Zugriff auf den Subscriber (Empfänger). Sie übergeben der Methode das gewünschte FIT-Connect-Environment und die Credentials (clientId und clientSecret) sowie die privaten Schlüssel zum Verschlüsseln (privateKeyDecryption) und Signieren (privateKeySigning). Der Parameter logger ist optional. Wird er übergeben, dann muss er das Interface Microsoft.Extensions.Logging.ILogger implementieren.

GetRoutingClient(...)​

Mit der Methode GetRoutingClient(...) erhalten Sie Zugriff auf den RoutingClient. Sie übergeben der Methode das gewünschte FIT-Connect-Environment. Der Parameter logger ist optional. Wird er übergeben, dann muss er das Interface Microsoft.Extensions.Logging.ILogger implementieren.

Methoden der Klasse Sender​

SendAsync(submission)​

Das Abschicken der Submission erfolgt mit diesem Aufruf.

GetStatusForSubmissionAsync()​

Mit der Methode GetStatusForSubmission(sentSubmission) fragen Sie vom Zustelldienst den aktuellen Status der gesendeten Submission ab. Sie übergeben der Methode den Rückgabewert der Methode SendAsync(...)der Klasse Sender (hier in der Variablen sentSubmission enthalten). Die Methode GetStatusForSubmission(sentSubmission) gibt die Werte für status und problems zurück. Der status beinhaltet den aktuellen Zustand der Submission. In den problems sind Rückmeldungen vom Subscriber enthalten. Der Aufruf der Methode wird hier gezeigt.

RoutingClient​

Client-Implementierung der Routing-API​

Über die Methode ClientFactory.GetRoutingClient(...) haben Sie Zugang zur Routing-API von FIT-Connect, um nach den zuständigen Zustellpunkten bei den zuständigen Zustelldiensten für eine bestimmte Verwaltungsleistung in einem bestimmten Gebiet zu suchen.

Router erhalten​

Der folgende Quellcode zeigt, wie Sie einen RoutingClient für die Suche nach den zuständigen Zustellpunkten erhalten:

 ClientFactory.GetRoutingClient(FitConnectEnvironment.Test, logger);

Methoden der Klasse Router​

FindDestinationsAsync(...)​

Parameter der Methode​

Mit der Methode FindDestinationsAsync(leikaKey, ars) ermitteln Sie die destinationID der zuständigen Zustellpunkte bei den zuständigen Zustelldiensten (submissionUrl).
Es können mehrere Zustellpunkte und auch mehrere Zustelldienste für eine bestimmte Verwaltungsleistung in einem bestimmten Gebiet zuständig sein. Die Methode führt intern eine Validierung durch und prüft unter anderem, ob wirklich die Routing-API von FIT-Connect die Angaben zu den zuständigen Zustellpunkten und zuständigen Zustelldiensten gesendet hat.
Die Methode besitzt die folgenden Parameter:

  • leikaKey
    Leistungsschlüssel, der Schlüssel für eine bestimmte Verwaltungsleistung, zum Beispiel 99400048079000. Eine Definition finden Sie hier.
  • ars
    Amtlicher Regionalschlüssel (ARS), zum Beispiel "081150045045" für die Stadt Sindelfingen.
  • ags (optional)
    Amtlicher Gemeindeschlüssel (AGS), zum Beispiel "08115045" für die Stadt Sindelfingen. Verwenden Sie im Aufruf der Methode entweder den Regionalschlüssel oder den Gemeindeschlüssel. ARS ist der Nachfolger des AGS. Eine Definition finden Sie hier.
  • areaId (optional)
    AreaId, liegen Ihnen weder der Regionalschlüssel noch der Gemeindeschlüssel vor, dann müssen Sie vor dem Aufruf der Methode die AreaId ermitteln. Dazu können Sie den Endpunkt GET /areas der Routing-API von FIT-Connect nutzen. Eine Beschreibung dazu finden Sie hier. Sie können den Endpunkt GET /areas mithilfe der Methode GetAreas der Klasse Router des .NET-SDKs aufrufen. Eine Beschreibung dazu finden Sie ebenfalls hier.

Sie müssen der Methode FindDestinationsAsync(...) den Parameter leikaKey übergeben sowie genau einen der folgenden Parameter ars, ags oder areaId.

Rückgabewert der Methode​

Die Methode FindDestinationsAsync(...) gibt eine Liste zurück mit Instanzen der Klasse Route. In der Eigenschaft destinationId dieser Klasse finden Sie die ID einer zuständigen Destination (eines zuständigen Zustellpunktes) für die beim Aufruf der Methode übergebene Leistung (leikaKey) in einem Gebiet (ars, ags oder areaId).
In der Eigenschaft DestinationParameters der Klasse Route finden Sie die submissionUrl, die URL-Adresse des zuständigen Zustelldienstes. Hier finden Sie ein Beispiel für den Aufbau der DestinationParameters.

Fachausdrücke erklärt​

Sie finden hier eine Übersicht über wichtige Fachausdrücke mit Erklärungen.