Zum Hauptinhalt springen

.NET-SDK

Destinations verwalten​

Das .NET SDK ermöglicht das Erstellen, Bearbeiten und eventuelle Löschen von Zustellpunkte (auch Destinations genannt).

Für die Verwaltung von Destinations braucht man:​

  • Credentials: Um einen Destination zu erstellen, braucht man eine Client-ID (Zugangs-Kennung) und ein Client-Secret (Zugangs-Geheimnis). Hier ist beschrieben, wie man diese Credentials erhält.
  • Schlüssel zum Entschlüsseln und Signieren: Empfangende Systeme benötigen ein Zertifikat der Verwaltungs-PKI. Dazu findet man hier eine Beschreibung. Aus diesem Zertifikat generieren man dann JSON Web Keys (JWKs). Eine Beschreibung dazu ist auch hier.

DestinationClient erstellen​

Man kann einen DestinationClient erstellen mit der Methode CreateDestinationClient(...) der SDK-Klasse ClientFactory:

string clientId = "YOUR CLIENT ID";
string clientSecret = "YOUR CLIENT SECRET";

destinationClient = ClientFactory.CreateDestinationClient(
                FitConnectEnvironment.Test,
                clientId,
                clientSecret,
                Logger
            );

Parameter der Methode ClientFactory.CreateDestinationClient()​

  • FitConnectEnvironment
    Das Beispiel oben verwendet die Umgebung Test der FIT-Connect-Infrastruktur.
  • Client-ID, Client-Secret
    Das Beispiel enthält Platzhalter für die Werte in clientId und clientSecret. Hier ist beschrieben, wie man eine Client-ID und ein Client-Secret erhält.
  • Logger
    Wird ein Logger übergeben, dann muss er das Interface Microsoft.Extensions.Logging.ILogger implementieren.

Zustellpunkt erstellen​

  destinationService.CreateDestination(CreateDestinationDto createDestinationDto);

Um einer Destination zu erstellen, verwendet man die Methode .CreateDestination(CreateDestinationDto createDestinationDto) der DestinationClient.

public class CreateDestinationDto
    {
        /// <summary>
        /// Status of the destination.
        /// Allowed values: draft, created, active, inactive, decommissioned.
        /// </summary>
        [JsonProperty("status")]
        public DestinationStatus Status { get; set; }

        /// <summary>
        /// Name of the destination. This is an optional field.
        /// Constraints: 0 to 128 characters.
        /// </summary>
        [JsonProperty("name")]
        public string Name { get; set; }

        /// <summary>
        /// Information regarding the contact person of the destination.
        /// This must either specify detailed contact information or be null.
        /// </summary>
        [JsonProperty("contactInformation")]
        public ContactInformationDto ContactInformation { get; set; }

        /// <summary>
        /// Supported services provided by the destination.
        /// Each service includes an identifier, supported regions, and submission schemas.
        /// </summary>
        [JsonProperty("services")]
        public HashSet<DestinationServiceDto> Services { get; set; }

        /// <summary>
        /// Object specifying configuration for callback notifications to the destination.
        /// Includes a publicly accessible callback URL and an optional callback secret for HMAC validation.
        /// </summary>
        [JsonProperty("callback")]
        public CallbackDto Callback { get; set; }

        /// <summary>
        /// Identifier of the encryption key for the destination.
        /// Constraints: Max 64 characters. Must match the "kid" of the encryptionPublicKey.
        /// </summary>
        [JsonProperty("encryptionKid")]
        public string EncryptionKid { get; set; }

        /// <summary>
        /// JSON Web Key (JWK) containing details of the encryption key used by the destination.
        /// </summary>
        [JsonProperty("encryptionPublicKey")]
        public ApiJwk EncryptionPublicKey { get; set; }

        /// <summary>
        /// JSON Web Key (JWK) containing details of the signing key used by the destination for digital signatures.
        /// </summary>
        [JsonProperty("signingPublicKey")]
        public ApiJwk SigningPublicKey { get; set; }

        /// <summary>
        /// List of metadata schema versions that the destination supports.
        /// Format of each version adheres to Semantic Versioning (e.g., 1.0.0).
        /// </summary>
        [JsonProperty("metadataVersions")]
        public HashSet<string> MetadataVersions { get; set; }

        /// <summary>
        /// Specifies the supported reply channels for submissions to this destination.
        /// If none are specified, it is assumed that the authority only communicates via physical mail for responses.
        /// </summary>
        [JsonProperty("replyChannels")]
        public DestinationReplyChannelsDto ReplyChannels { get; set; }

1. Destination Status - Zustellpunkt-Status​

Definiert den aktuellen Status des Zustellpunktes. Mögliche Werte:

  • draft – Im Entwurfsstatus.

  • created – Erstellt, aber noch nicht aktiv.

  • active – Bereits aktiv und im Einsatz.

  • inactive – Deaktiviert, nicht mehr nutzbar.

  • decommissioned – Stillgelegt.

2. Name​

Der interne Name des Zustellpunktes.

Constraints:

  • Typ: string
  • Länge: 0–128 Zeichen

3. Contact Information - Kontaktinformationen​

Informationen zur Organisation oder Person, die für den Zustellpunkt verantwortlich ist.

Felder:

  • legalName – Juristischer Name

  • address – Adresse

  • phone – Telefonnummer

  • email – E-Mail-Adresse (gültig)

  • unit – Abteilung (optional)

4. services – Unterstützte Leistungen​

Liste der Verwaltungsleistungen, die der Zustellpunkt anbietet.

Struktur: DestinationServiceDto

  • identifier – URN der Leistung (z. B. urn🇩🇪fim:leika:leistung)

  • regions – Liste unterstützter Regionen (z. B. DE012345)

  • submissionSchemas – unterstützte Fachdatenschemata

  • replyChannels – unterstützte Rückkanäle (z. B. DE-Mail)

5. callback – Rückmeldungskonfiguration​

Konfiguration, wohin Benachrichtigungen gesendet werden sollen.

Felder:

  • url – HTTPS-Adresse für Callback

  • secret – Geheimnis zur Absicherung (min. 32 Zeichen)

6. encryptionKid – Verschlüsselungs-Schlüssel-ID​

Eindeutige ID für den verwendeten Verschlüsselungsschlüssel.

  • Typ: string
  • Constraints: max. 64 Zeichen

7. encryptionPublicKey – Öffentlicher Verschlüsselungsschlüssel​

JSON Web Key (JWK) zur Datenverschlüsselung.

  • Typ: ApiJwk
  • Algorithmus: RSA-OAEP-256

8. signingPublicKey – Öffentlicher Signierschlüssel​

JWK zur digitalen Signierung.

  • Typ: ApiJwk
  • Algorithmus: PS512

9. metadataVersions – Unterstützte Metadatenschemaversionen​

Versionen des unterstützten Metadatenschemas gemäß Semantic Versioning.

  • Typ: ICollection string
  • Beispiel: "1.5.0"

replyChannels – Rückkanäle für Kommunikation​

Kommunikationskanäle, über die Antworten vom Zustellpunkt empfangen werden können.

Mögliche Kanäle:

  • De-Mail

  • FINK

  • E-Mail (optional mit PGP)

  • ELSTER

  • FIT-Connect

Validation​

Falls das Erstellungsobjekt falsche oder ungültige Informationen enthält, erhält man vom Endpunkt eine fachliche Exception, die angibt, welche Felder korrigiert werden müssen.

Vorhandenes Destination aktualisieren oder patchen​

Es gibt zwei Möglichkeiten, eine bestehende Destination zu aktualisieren: Man kann diese entweder vollständig (Update) oder nur einen Teil (Patch) der Informationen aktualisieren.

Update​

  destinationService.UpdateDestination(DestinationDto destination);

Vergleichbare Verwendung wie bei der Erstellung eines Destinations.

Patch​

  destinationService.PatchDestination(PatchDestinationDto patchOnDestination, Guid destinationId);

Das PatchDestinationDto ist vergleichbar mit dem DestinationDto, aber viele seiner Felder können null sein, so dass eine teilweise Aktualisierung möglich ist.

Destination löschen​

  destinationService.DeleteDestination(Guid destinationId);

Dieser Funktion ermöglicht es, eine Destination zu löschen, solange sich diese im status 'created' befindet.

Destination-Liste abrufen​

 destinationClient.ListDestinations(int offset, int limit);

Diese Methode ruft eine paginierte Liste von alle selbst angelegten Destinations ab.

Parameter:

  • offset (int) – Start-Offset für die Ergebnisseite.

  • limit (int) – Maximale Anzahl an Einträgen, die zurückgegeben werden sollen.

Öffentlichen Schlüssel eines Destinations abrufen​

 destinationClient.GetPublicKey(Guid destinationId);

Diese Methode ruft den öffentlichen Verschlüsselungsschlüssel (JWK) eines bestimmten Destinations ab.

Parameter:

  • destinationId (Guid) – Die eindeutige ID der Destination.

Rückgabe: Der öffentliche Schlüssel als string.

Fehler: ArgumentException, wenn kein EncryptionKid vorhanden ist.

Schlüssel für einer Destination auflisten​

 destinationClient.ListKeys(Guid destinationId, int offset, int limit;

Diese Methode listet alle zur Destination gehörenden Schlüssel auf (Signatur- und Verschlüsselungsschlüssel).

Parameter:

  • destinationId (Guid) – ID der Destination.

  • offset (int) – Startwert der Seitierung.

  • limit (int) – Maximale Anzahl an Ergebnissen.

Rückgabe: Ein Objekt vom Typ ApiJwks mit den enthaltenen Schlüsseln.

Fachausdrücke erklärt​

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