Zustellpunktverwaltung
Bearbeiten eines Zustellpunktes
Für die Aktualisierung eines Zustellpunktes existieren aktuell folgende Endpunkte:
- Vollständige Aktualisierung eines Zustellpunktes:
PUT /v1/destinations/{destinationId}
- Partielle Aktualisierung eines Zustellpunktes:
PATCH /v1/destinations/{destinationId}
Für die Aktualisierung der Schlüssel des Zustellpunktes gibt es folgenden Endpunkt:
Die Details sind der API Spec zu entnehmen. Eine Beschreibung der Parameter des Zustellpunkt-Objektes findet sich im Artikel Aufbau der Zustellpunkt-Informationen.
Beispiele
- curl
- Self-Service-Portal
Aktualisierung des Verschlüsselungsschlüssels eines Zustellpunktes
$ SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
$ JWT_TOKEN=...
$ DESTINATION_ID=...
# Hinzufügen eines Schlüssels zu einer Destination
$ curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $JWT_TOKEN" \
--data '{"kty": "RSA", "kid": "new-encryption-key", "alg": "RSA-OAEP-256", "key_ops": ["wrapKey"], "x5c": ["..."], "e": "AQAB", "n": "..."}' \
"$SUBMISSION_API/v1/destinations/$DESTINATION_ID/keys"
# Setzen der Schlüssel-ID als Verschlüsselungsschlüssel
$ curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $JWT_TOKEN" \
--data '{"encryptionKid": "new-encryption-key"}' \
"$SUBMISSION_API/v1/destinations/$DESTINATION_ID"
Über das Self-Service-Portal können Zustellpunkte aktuell noch nicht aktualisiert werden.
Statusmodell eines Zustellpunktes
Bis auf den automatischen Löschvorgang sind alle Statusübergänge manuell, d.h. über die Submission API oder das Self-Service-Portal vorzunehmen.
Status | Beschreibung |
---|---|
created | Die Destination wurde erzeugt. Sie kann vorbereitet werden und sollte erst bei fertig aufgesetzter Fachanwendung in den Status active wechseln. |
active | Die Destination ist ab jetzt aktiv und kann Anträge annehmen. |
inactive | Wenn die Destination in den Status inactive versetzt wird, können keine neuen Anträge mehr angelegt werden. Alle anderen Optionen bleiben möglich. Eine inaktive Destination kann jederzeit wieder in den Status active versetzt werden. Nach einer Wartefrist von 30 Tagen kann die Destination in den Status decommissioned versetzt werden. |
decommissioned | Wenn eine Destination in den Status decommissioned versetzt wird, ist weder das Anlegen von Anträgen möglich, noch ist es möglich, neue Antworten zu versenden. Status-Updates können allerdings noch gesetzt werden. Eine Destination im Status decommissioned kann nicht wieder aktiviert werden. |
deleted | Eine Destination kann im Status created manuell gelöscht werden. Nach zwei Jahren im Zustand decommissioned wird sie automatisiert gelöscht. |
Wartefrist vor dem Wechsel von inactive
zu decommissioned
Wird ein Zustellpunkt in den Status decommissioned
versetzt, so kann er nicht mehr reaktiviert werden.
Daher wurde eine Wartefrist von 30 Tagen im Status inactive
vorgesehen.
Erst nach Ablauf dieser Zeit kann er in den Status decommissioned
versetzt werden.
Sofern Sie den Statuswechsel zu früh versuchen, erhalten Sie über das Self-Service-Portal folgende Fehlermeldung:
Über die Submission API erhalten Sie folgende Meldung.
{
"type": "https://schema.fitko.de/fit-connect/submission-api/problems/destination-state-invalid",
"title": "Destination State invalid",
"status": 422,
"detail": "Destination df7fb66a-8c25-45a7-8325-793e42822eac has the wrong state for this operation."
}
Status des Zustellpunkts ändern
Der Status kann über den Endpunkt PATCH /v1/destinations/{destinationId}
oder über die Oberfläche des Self-Service-Portal aktualisiert werden.
- curl
- Self-Service-Portal
$ SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
$ JWT_TOKEN=...
$ DESTINATION_ID=...
# Aktivieren einer Destination
$ curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $JWT_TOKEN" \
--data '{"status": "active"}' \
"$SUBMISSION_API/v1/destinations/$DESTINATION_ID"
Nach dem Erstellen eines Zustellpunktes kann dieser im Self-Service-Portal durch nochmaliges Editieren des Zustellpunktes aktiviert werden.
Anbieten von Rückkanaloptionen als Zustellpunkt
Bei der Migration auf die bidirektionale Kommunikation wurden alle Rückkanaloptionen vom Zustellpunkt auf die zuständigen Verwaltungsleistungen (services
) kopiert.
Bietet ein Zustellpunkt z.B. die Rückkanaloption FIT-Connect (fitConnect
) an, so müssen sämtliche Verwaltungsleistungen diesen anbieten.
Kann eine angebotene Verwaltungsleistung den Rückkanal nicht anbieten, so muss die Option dort entfernt werden.
Bestehende Clients bekommen bei Abruf eines Zustellpunktes im veralteten Feld replyChannels
die größtmögliche Untermenge der Rückkanäle der Verwaltungsleistungen.
Wurden die Rückkanäle der Verwaltungsleistungen unter Verwendung der Submission API in Version 1.3.0 verändert (Feld services.*.replyChannels
), so ist ein Ändern der Rückkanäle (Feld replyChannels
) im Zustellpunkt nicht mehr möglich.
Das verhindert, dass Clients die angepassten Rückkanäle von Verwaltungsleistungen (Feld services.*.replyChannels
) pauschal überschreiben.
Zustellpunkt löschen
Das Löschen von Zustellpunkten kann über den API Endpunkt DELETE /v1/destinations/{destinationId}
oder im Self-Service-Portal (SSP) durchgeführt werden.
Im SSP löschen
Im Self-Service-Portal (SSP) klicken Sie in der linken Navigation auf den Menüpunkt "Zustellpunkte", um eine Auflistung der vorhandenen Zustellpunkte zu erhalten. Im folgenden Beispiel ist ein Zustellpunkt angelegt:
Um einen Zustellpunkte zum Löschen auszuwählen, klicken Sie bei diesem Zustellpunkt auf das folgende Symbol:
Das SSP zeigt nun ein weiteres Fenster an. In dieses Fenster müssen Sie den Namen des zu löschenden Zustellpunktes eintragen, erst dann kann dieser Zustellpunkt gelöscht werden. Im Beispiel ist der Name "TestZustellpunkt" einzutragen:
Klicken Sie zum Löschen auf die Schaltfläche "Ja, Zustellpunkt löschen":
Sie können nur Zustellpunkte löschen, die noch nicht aktiviert wurden. Zudem können Zustellpunkte gelöscht werden, die nicht mehr verwendet werden (Status decommissioned).