Zustellpunkte verwalten

RolleVerwaltungssystem

SDK · ModulJava · sdk-client.NET · Fitko.FitConnect.Client

VoraussetzungenClient mit OAuth-Scope manage-destinations. Prüfen Sie das Setup Ihres Clients im Self-Service-Portal.

TL;DR – DestinationClient (Java) bzw. DestinationApiService (.NET) erlaubt CRUD-Operationen auf Zustellpunkten ohne Self-Service-Portal-Umweg: Anlegen, Aktualisieren, Auflisten, Schlüssel verwalten, Limits beantragen.

Client erstellen

Zustellpunkt-Verwaltung läuft über Management — den Einstiegspunkt für alles, was nicht an eine bestimmte Rolle (Organisation/OnlineService) gebunden ist. destinations() liefert daraus den DestinationClient:

Java

DestinationClient destClient = sdk.manage().destinations();

.NET (C#)

var destinationApi = client.DestinationApiService;

Zustellpunkt anlegen

Java

Zuerst die Bausteine — Kontaktdaten und die angebotene Verwaltungsleistung:

ContactInformation contact = ContactInformation.builder()
    .legalName("Stadt Sindelfingen")
    .email("it@sindelfingen.de")
    .build();

DestinationService service = DestinationService.builder()
    .identifier("urn:de:fim:leika:leistung:99400048079000")
    .regions(Set.of("DE080115"))
    .submissionSchemas(Set.of(/* … */))
    .build();

Daraus das vollständige DTO zusammensetzen — inklusive Callback-URL und den öffentlichen Schlüsseln, mit denen dieser Zustellpunkt künftig adressiert wird:

CreateDestination dto = CreateDestination.builder()
    .status(DestinationStatus.DRAFT)
    .name("Bauamt Sindelfingen")
    .contactInformation(contact)
    .services(Set.of(service))
    .callback(new Callback(
        URI.create("https://example.com/fit-connect/callback"),
        "32+characters-long-secret"))
    .encryptionKid("key-2026-01")
    .encryptionPublicKey(encryptionJwk)
    .signingPublicKey(signingJwk)
    .metadataVersions(Set.of("1.5.0"))
    .build();

Und anlegen:

Destination created = destClient.createDestination(dto);

.NET (C#)

CreateDestination und ContactInformation haben nur einen vollständigen (Positions-)Konstruktor — es gibt kein Object-Initializer-{ }-Kurzformat wie bei einer normalen C#-Klasse:

var contact = new ContactInformation(
    legalName: "Stadt Sindelfingen",
    address: "Rathausplatz 1, 71063 Sindelfingen",
    phone: "+49 7031 940",
    email: "it@sindelfingen.de",
    unit: "IT");

var service = new DestinationRelatedService(
    identifier: "urn:de:fim:leika:leistung:99400048079000",
    regions: new HashSet<string> { "DE080115" },
    submissionSchemas: [],
    replyChannels: null);

var dto = new CreateDestination(
    status: DestinationStatus.Draft,
    name: "Bauamt Sindelfingen",
    contactInformation: contact,
    services: new HashSet<DestinationRelatedService> { service },
    callback: new Callback(
        "https://example.com/fit-connect/callback",
        "32+characters-long-secret"),
    encryptionKid: "key-2026-01",
    encryptionPublicKey: encryptionJwk,
    signingPublicKey: signingJwk,
    metadataVersions: new HashSet<string> { "1.5.0" },
    replyChannel: null!);

var created = await destinationApi.CreateDestination(dto);

Zustellpunkt aktualisieren oder löschen

Java

Zwei Wege, um einen bestehenden Zustellpunkt zu ändern. Vollständiges Update — bauen Sie das DTO wie beim Anlegen, mit den neuen Werten; ausgelassene Felder werden serverseitig geleert:

UpdateDestination updated = UpdateDestination.builder()
    // … übrige Felder wie beim Anlegen, hier nur der geänderte Schlüssel …
    .encryptionKid("key-2026-02")
    .encryptionPublicKey(newEncryptionJwk)
    .build();

destClient.updateDestination(destinationId, updated);

Teiländerung — nur gesetzte Felder werden gesendet, alles andere bleibt unangetastet:

DestinationPatch patch = DestinationPatch.builder()
    .name("Bauamt Sindelfingen (neu)")
    .build();

destClient.patchDestination(destinationId, patch);

Löschen — nur erlaubt, solange der Status created ist:

destClient.deleteDestination(destinationId);

Patch statt Update für Teiländerungen

Bei updateDestination werden ausgelassene Felder serverseitig geleert, da die ganze Destination ersetzt wird. Wenn Sie nur einzelne Felder ändern wollen, verwenden Sie patchDestination mit einem DestinationPatch — dort werden ausgelassene Felder nicht mitgesendet.

.NET (C#)

Destination ist eine gewöhnliche Klasse mit settbaren Properties (kein Record) — Sie ändern sie direkt, statt eine Kopie per with zu erzeugen:

var dest = await destinationApi.GetDestination(destinationId);
dest.EncryptionKid = "key-2026-02";
await destinationApi.UpdateDestination(dest);

await destinationApi.DeleteDestination(destinationId);

Für eine Teiländerung, bei der ausgelassene Felder unangetastet bleiben, gibt es PatchDestination (Object-Initializer funktioniert hier, da ein parameterloser Konstruktor existiert):

var patch = new PatchDestination { Status = "active" };
await destinationApi.PatchDestination(destinationId, patch);

Stand .NET: Name noch nicht patchbar

PatchDestination deckt aktuell Callback, ContactInformation, EncryptionKid, MetadataVersions, ReplyChannels, Services und Status ab — Name fehlt (anders als im Java-DestinationPatch). Um den Namen zu ändern, bleibt aktuell nur der volle UpdateDestination-Weg.

Status-Voraussetzung

Löschen funktioniert nur, solange sich der Zustellpunkt im Status created befindet. Aktive Zustellpunkte müssen zuerst auf inactive oder decommissioned gesetzt werden.

Zustellpunkte auflisten

Java

DestinationFilter filter = DestinationFilter.builder()
    .statuses(List.of(Status.ACTIVE))
    .search("Hamburg")
    .minimal(true)
    .build();

Destinations page = destClient.listDestinations(0, 100, filter);

// Alle Seiten auf einmal
List<Destination> everything = destClient.listAllDestinations(DestinationFilter.none());

.NET (C#)

var page = await destinationApi.ListDestinations(offset: 0, limit: 100);

Schlüssel verwalten

Der aktive Schlüssel eines Zustellpunkts sowie die Historie aller hinterlegten Schlüssel:

Java

var currentKey = destClient.getActiveDestinationKey(destinationId);
var keys = destClient.getKeysForDestination(destinationId, 0, 10);

Für einen Schlüsselwechsel fügen Sie zunächst den neuen Public Key hinzu, ohne den alten zu entfernen — Details dazu unter Key-Rollover:

destClient.addKeyToDestination(destinationId, newPublicKey);

.NET (C#)

// Aktiven öffentlichen Schlüssel abrufen (der kid, den EncryptionKid referenziert)
ApiJwk currentKey = await destinationApi.GetActiveEncryptionKey(destinationId);
// … für fremde Zustellpunkte unauthentifiziert: client.Directory.GetActiveEncryptionKey(id)

// Alle historisch hinterlegten Schlüssel eines Zustellpunkts:
var keys = await destinationApi.ListKeys(destinationId, offset: 0, limit: 10);

// Neuen Schlüssel hinzufügen, ohne den alten zu entfernen (Vorbereitung Key-Rollover):
await destinationApi.AddKey(destinationId, newPublicKey);

Stand .NET: kein GetKeyForDestination am DestinationApiService

Anders als im Java-SDK gibt es (noch) keine Methode, die gezielt einen Schlüssel eines Zustellpunkts anhand seiner kid direkt am DestinationApiService liefert. Verfügbar sind GetPublicKeys(destinationId) (alle aktuell hinterlegten Schlüssel als ApiJwks), ListKeys(destinationId, offset, limit) (paginierte Historie) und — für den konkreten Sende-Anwendungsfall — SubmissionApiService.GetPublicKeyFromDestination(destinationId, kid).

Attachment-Limits abrufen und ändern

Pro Zustellpunkt sind Limits für Anhang-Größen und -Anzahl konfigurierbar.

Java

DestinationLimits limits = destClient.getAttachmentLimits(destinationId);

// Erhöhung der Limits beantragen
destClient.requestLimitChange(
    destinationId,
    newLimits,
    "Begründung für die Erhöhung",
    "contact@example.com");

.NET (C#)

var limits = await destinationApi.GetDestinationAttachmentLimit(destinationId);

// Erhöhung der Limits beantragen
var changeRequest = await destinationApi.RequestAttachmentLimitChange(
    destinationId,
    new AttachmentLimitChangeRequest
    {
        Values = newLimits,
        RequestReason = "Begründung für die Erhöhung",
        ContactEmail = "contact@example.com"
    });

Validierung und Fehlerbehandlung

Wenn das Create-DTO unvollständig oder inkonsistent ist, antwortet die API mit einer fachlichen Exception, die genau benennt, welche Felder korrigiert werden müssen. Prüfen Sie die Exception-Message bzw. das errors-Feld auf das oder die problematischen Felder.

Weiterführende Themen

• Destination-API (REST)
• Zustellpunkte im Self-Service-Portal
• Key-Rollover