Zum Hauptinhalt springen

Zustellpunkte

Verwalten per API-Aufrufe​

Diese Seite zeigt, wie Sie per API-Aufrufe Zustellpunkte ändern, abfragen und löschen (verwalten). Sie können Zustellpunkte auch im Self-Service-Portal (SSP) verwalten. Die Seite Zustellpunkte erstellen beschreibt, wie Sie einen Zustellpunkt im SSP anlegen. Die Seite Zustellpunkte löschen zeigt, wie Sie im SSP einen Zustellpunkt löschen.

Voraussetzungen​

Um einen Zustellpunkt per API-Aufruf zu verwalten, müssen die folgenden Voraussetzungen erfüllt sein.

  • Subscriber-Client
    Sie haben im Self-Service-Portal einen Client des Typs Subscriber angelegt. Die Seite Accountregistrierung und Client-Verwaltung beschreibt, wie Sie einen Client des Typs Subscriber erzeugen.
  • Destination Management API autorisiert
    Beim Anlegen eines Clients haben Sie das optionale Feature aktiviert: Diesen Subscriber-Client zur Erstellung von Zustellpunkten über die Destination Management API autorisieren.
  • Client-ID und Client-Secret
    Beim Anlegen des Subscriber-Clients wird die ID und das Secret des Clients angezeigt. Das Client-Secret wird nur beim Anlegen des Zustellpunktes gezeigt, danach nicht mehr. Sie müssen also das Client-Secret kopieren und speichern.
  • Access-Token
    Die ID und das Secret dieses Clients benötigen Sie für den Aufruf des OAuth-Servers, um ein Access-Token zu erhalten, das Sie dazu berechtigt, per API-Aufruf auf diesen Client zuzugreifen. Sie erhalten das Token vom OAuth-Server, der für die jeweilige Umgebung von FIT-Connect zuständig ist. Die Seite Betriebsumgebungen der FIT-Connect-Infrastruktur beschreibt die Umgebungen und enthält für jede Umgebung die URLs für die einzelnen Dienste. Die Seite Authentifizierung beschreibt den Aufruf des OAuth-Servers, um ein Access-Token zu erhalten.
  • JWK-Token
    Beim Aufruf des OAuth-Servers sendet der Server ein JSON-Object zurück, das unter der Eigenschaft access_token ein Token im Format JWT (JSON Web Token) enthält. Speichern Sie das Token in einer Variablen. Die folgenden Beispiele verwenden dafür die Variable JWT_Token. Ein JWT-Token beginnt zum Beispiel mit "eyJraWQiOiJHb2JOIi..."
Hinweis

Token sind nur für 30 Minuten gültig und müssen dann erneuert werden.

Die folgenden Beispiele für den Aufruf von API-Endpunkten verwenden das Kommandozeilen-Programm cURL.

Zustellpunkt abfragen​

Um die Eigenschaften eines Zustellpunkts zu erfragen, steht der folgende API-Endpunkt zur Verfügung:

Diesen Endpunkt ruft das folgende Beispiel auf, um die Eigenschaften (Parameter) eines Zustellpunkts zu erfragen, der im Zustelldienst der Testumgebung angelegt wurde. Dem Zustellpunkt des Beispiels ist die ID bbc2f369-0644-4e77-b23f-9fd679cd9fd6 zugewiesen. Der Beginn des JWT-Tokens ist im Beispiel "eyJraWQiOiJHb2JOIi...". Die vollständige URL des Endpunkts lautet in der Testumgebung: https://submission-api-testing.fit-connect.fitko.dev/v1/destinations/bbc2f369-0644-4e77-b23f-9fd679cd9fd6 

 $ SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
 $ JWT_TOKEN=eyJraWQiOiJHb2JOIi...
 $ DESTINATION_ID=bbc2f369-0644-4e77-b23f-9fd679cd9fd6

 # Eigenschaft einer Destination erfragen
 $  curl -X GET \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $JWT_TOKEN" \
       $SUBMISSION_API/v1/destinations/$DESTINATION_ID

Die Antwort des Endpunktes lautet:

{
   "destinationId":"bbc2f369-0644-4e77-b23f-9fd679cd9fd6",
   "status":"active",
   "services":[
      {
         "identifier":"urn:de:fim:leika:leistung:99001001000000",
         "submissionSchemas":[
            {
               "schemaUri":"https://schema.fitko.de/fim/s00000096_1.0.schema.json",
               "mimeType":"application/json"
            }
         ],
        "regions": [
            "DE01001"
          ],
        "replyChannels": {
          "eMail": {
          "usePgp": false
        }
}
      }
   ],
   "encryptionKid":"JXu78OPVZ4Vw3lRTnbotySG65n3JRyO3vlJZuywJzmo",
   "contactInformation":{
      "legalName":"Meine Gemeinde",
      "address":"Meine Straße 1,82284,MeineStadt",
      "phone":"0880762242",
      "email":"info@meineemail.de",
      "unit":"Standesamt"
   },
   "metadataVersions":[
      "1.1.0"
   ]
}
Mit Postman die Eigenschaften erfragen

Das folgende Bild zeigt, wie Sie die Eigenschaften eines Zustellpunktes erfragen, indem Sie den API-Endpunkt GET /v1/destinations/{destinationId} mit dem Programm Postman aufrufen. Im Bild oben ist der Aufruf zu sehen, im Bild unten die Antwort des Zustelldienstes:

Kontaktdaten eintragen

Zustellpunkt anlegen​

Um einen neuen Zustellpunkt anzulegen, verwenden Sie das Self-Service-Portal (SSP). Die Seite Zustellpunkte erstellen zeigt, wie Sie im SSP einen Zustellpunkt anlegen. Zukünfig können Sie auch mithilfe eines eigenen Programms einen Zustellpunkt erstellen, indem Sie den folgenden Endpunkt aufrufen:

In der Dokumentation der API ist angegeben, welche Daten für das Anlegen eines Zustellpunktes erforderlich sind. Zudem ist dort ein Beispiel für die Daten zu sehen, unter REQUEST > EXAMPLE.

Hinweis

Zurzeit ist das Anlegen von Zustellpunkten nur im Self-Service-Portal möglich. Es wird aber in Zukunft möglich sein, Zustellpunkte auch über den Aufruf des API-Endpunkts POST /v1/destinations zu erstellen.

Zustellpunkte ändern​

Zum Ändern und Aktualisieren eines Zustellpunktes stehen die folgenden Endpunkte zur Verfügung:

Für die Aktualisierung der Schlüssel des Zustellpunktes gibt es den folgenden Endpunkt:

Die Details sind der API-Spec zu entnehmen. Eine Beschreibung der Parameter des Zustellpunkt-Objektes finden Sie auf der Seite Aufbau der Zustellpunkt-Informationen.

Aktualisierung des Verschlüsselungsschlüssels eines Zustellpunktes​

$ SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
$ JWT_TOKEN=eyJraWQiOiJHb2JOIiwidHlwIjoiYXQrand0...
$ DESTINATION_ID=d2bf7cf7-2625-4737-974f-0dd2054f8c6f

# 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"

Zustellpunkt löschen​

Sie können Zustellpunkte löschen, indem Sie den Endpunkt DELETE /v1/destinations/{destinationId} aufrufen. Das folgende Beispiel löscht den Zustellpunkt mit der ID c3f1ae54-3844-48a5-8ea3-42db8897120f:

$ SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
$ JWT_TOKEN=eyJraWQiOiJHb2JOIiwidHlwIjoiYXQrand0...
$ DESTINATION_ID=c3f1ae54-3844-48a5-8ea3-42db8897120f

# Löschen einer Destination
$ curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $JWT_TOKEN" \
  "$SUBMISSION_API/v1/destinations/$DESTINATION_ID"

Mit Postman einen Zustellpunkt löschen

Das folgende Bild zeigt, wie Sie einen Zustellpunkt löschen, indem Sie den API-Endpunkt DELETE /v1/destinations/{destinationId} mit dem Programm Postman aufrufen. Im Bild ist der Aufruf zu sehen (oben). Bei diesem Aufruf sendet der Zustelldienst im Erfolgsfall keine Antwort zurück.

Kontaktdaten eintragen

Hinweis

Die Seite Löschen beschreibt, wann Sie Zustellpunkte löschen können.

Status des Zustellpunkts ändern​

Der Status kann über den Endpunkt PATCH /v1/destinations/{destinationId} aktualisiert werden.

$ 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"
Mit Postman den Status ändern

Das folgende Bild zeigt, wie Sie die Eigenschaften eines Zustellpunktes ändern (aktualisieren), indem Sie den API-Endpunkt PATCH /v1/destinations/{destinationId} mit dem Programm Postman aufrufen.
Das folgende Beispiel aktiviert den Zustellpunkt mit der ID d2bf7cf7-2625-4737-974f-0dd2054f8c6f, d. h., der Status des Zustellpunktes soll auf activegesetzt werden. Im Bild ist der Aufruf zu sehen (oben). Die Antwort des Zustelldienstes sehen Sie unten im Bild: Der Status ist jetzt auf active gesetzt.

Kontaktdaten eintragen

Das folgende Bild zeigt das JSON-Objekt, das mit dem Aufruf des API-Endpunkts PATCH /v1/destinations/{destinationId} gesendet wurde, um den Status auf activezu setzen:

Kontaktdaten eintragen

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:

Fehlermeldung Statuswechsel

Ü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."
}