.NET-SDK
Onlinedienst implementieren
Einen Onlinedienst mit .NET-SDK entwickeln
Onlinedienste 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 Onlinedienst
Das folgende Beispiel zeigt, wie Sie mit dem .NET-SDK eine Einreichung (Submission) erzeugen und an einen Zustellpunkt senden.
1. Schritt: Onlinedienst erstellen
Sie erstellen einen Onlinedienst 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 FeldFitConnectEnvironment.Test
des .NET-SDKs die FIT-Connect-Endpunkte zur Verfügung, die aufgerufen werden sollen. - ClientId, ClientSecret
Onlinedienste 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 Verwaltungssystem (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()
bereits 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 Onlinedienstes 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-Connect 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);
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 Verwaltungssystem (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.
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 Onlinedienstes 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 Onlinedienst.
Nachfolgend sind die Methoden der Klasse SendableSubmission
und SendableEncryptedSubmission
beschrieben.
Bidirektionale Kommunikation (BiDiKo)
Dialog zwischen Onlinedienst und Verwaltungssystem
Nach dem Versenden der ersten Submission ist in FIT-Connect
ein direkter Dialog zwischen Onlinedienst und Verwaltungssystem möglich,
wenn Sie die Bidirektionale Kommunikation (BiDiKo) verwenden.
Bei BiDiKo tauschen Onlinedienst und Verwaltungssystem direkt Übermittlungen miteinander aus:
- Der Onlinedienst 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 Onlinedienst wird im SDK auch Onlinedienst-Client genannt.
- Der Empfänger antwortet auf diese Einreichung, indem er eine Übermittlung über FIT-Connect an den Onlinedienst 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 Onlinedienst 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 Übermittlungen 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 Verwaltungssystem) 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 Onlinedienst (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 (Verwaltungssystem) genutzt um den Reply zu verschlüsseln
var publicReplyEncryptionKey = keySet.EncryptionPublicKey;
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 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;
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 Onlinedienst entsprechende Events an das Event-Log (siehe folgende Beispiele fürs Akzeptieren und Ablehnen).
Weitere Details finden Sie in der Dokumentation zu Events und zum Erzeugen von Security Event Tokens.
Reply akzeptieren
Nach der Prüfung durch den Onlinedienst (Onlinedienst-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()});
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 Onlinedienst (Onlinedienst-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
:
Die folgende Grafik zeigt die Reihenfolge der Aufrufe bei der Klasse 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 (Verwaltungssystem oder virtuelle Poststelle).
Ein Zustellpunkt wird auch Destination genannt und ist durch seine DestinationId eindeutig bestimmt. Die DestinationId besitzt den Datentyp Guid.
Eine Möglichkeit, die DestinationId zu ermitteln, geht über die Methode FindDestinationId()
des Onlinedienstes.
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 Übermittlung an den adressierten Zustellpunkt im Datenformat JavaScript Object Notation (JSON).
Tragen Sie die Übermittlung 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 Übermittlungen 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 Übermittlungen 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 Onlinedienst, 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 Beispiel99400048079000
. 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 EndpunktGET /areas
der Routing-API von FIT-Connect nutzen. Eine Beschreibung dazu finden Sie hier. Sie können den EndpunktGET /areas
mithilfe der MethodeGetAreas
der KlasseRouter
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.