Zum Hauptinhalt springen

Einstellungen beim Onlinedienst

Angebotene Rückkanäle abrufen​

Nachfolgend wird beschrieben, wie ein Onlinedienst die vom Verwaltungssystem angebotenen Rückkanäle auswählt.

Rückkanäle eines Verwaltungssystems abrufen​

Die unterstützten Rückkanäle eines Verwaltungssystems sind pro Verwaltungsleistung angegeben. Diese können beim Abrufen der Zustellpunktinformationen gelesen werden:

Der obige Aufruf einer Destination könnte also z.B. folgendes Ergebnis liefern:

{
  // ...
  "replyChannels": {
    "fink": {},
    "elster": {}
  },
  "services": [{
    // ...
    "replyChannels": {
      "fitConnect": {
        "processStandards": [ "urn:xoev-de:bmk:standard:xbau_2.3" ]
      },
      "fink": {},
      "elster": {}
    }
  }, {
    // ...
    "replyChannels": {
      "fitConnect": {
        "processStandards": [ "urn:xoev-de:bmk:standard:xbau_2.4" ]
      },
      "fink": {},
      "elster": {}
    }
  }]
}
Hinweis

Das Attribut replyChannels eines Zustellpunktes (Destination) wurde zugunsten des gleichnamigen Attributs innerhalb des services-Array in Version 1.3.0 der Submission API als deprecated markiert. Derzeit wird das Attribut nur ausgegeben, wenn in allen services identische Rückkanäle vorhanden sind (Schnittmenge der replyChannels aus allen services).

Eine ausführliche Erklärung findet sich auf der Seite der Zustellpunktverwaltung.

Der obige Zustellpunkt (nicht alle Felder sind abgebildet) unterstützt für alle seine Verwaltungsleistungen (services) die Rückkanäle FINK und Elster. Die erste Verwaltungsleistung unterstützt den Prozessstandard XBau in Version 2.3, die zweite in Version 2.4. Da diese nicht identisch sind, werden diese nicht direkt am Zustellpunkt im Feld replyChannels zurückgegeben.

Rückkanäle eines Verwaltungssystems per Routing-API abrufen (nicht mehr empfohlen)​

Hinweis

Es ist geplant diese Variante als deprecated zu markieren. Eine Verwendung wird daher nicht mehr empfohlen.

Die Konfiguration eines Zustellpunktes können Onlinedienste über die Routing-API erfragen. Die Schnittmenge der Rückkanäle aus allen Services des Zustellpunktes (s.o.) findet sich dort im Feld destinationParameters.replyChannels:

{
  "count": 1,
  "offset": 0,
  "totalCount": 1,
  "routes": [
    {
      // ...
      "destinationParameters": {
        // ...
        "replyChannels": {
          "elster": {},
          "eMail": {
            "usePgp": false
          },
          "fitConnect": {
            "processStandards": [ "urn:xoev-de:bmk:standard:xbau_2.4" ]
          }
        }
      }
    }
  ]
}

Im obigen Beispiel (nicht alle Felder sind abgebildet) gibt es nur einen Zustellpunkt für die angegebene Leistung im angegebenen Gebiet. Der Zustellpunkt des Verwaltungssystems bietet Onlineservices an, über Elster, E-Mail oder FIT-Connect zu antworten.

Da es in diesem Beispiel keine replyChannels gibt, stellt das Verwaltungssystem Antworten auf dem Postweg zu.

Direkter Zugriff auf die Submission API​

Falls die Destination ID bekannt ist (z.B. über die Routing-API), können die Rückkanäle auch über die Submission API abgerufen werden. Gehen Sie dabei wie auf der Seite Einstellungen beim Onlinedienst beschrieben vor.

Es gibt auch die Möglichkeit, nur die destinationId und die submissionUrl aus der Routing-API zu lesen. Damit können die Daten direkt an der Submission API abgerufen werden. Hier ein Beispiel:

$ DESTINATION_ID=".destinationid aus der Routing-API"
$ SUBMISSION_URL = ".submissionUrl aus der Routing-API"
$ http get "$SUBMISSION_URL/v1/destinations/$DESTINATION_ID"

Rückkanalauswahl​

Erforderliche Einträge in den Metadaten​

Im obigen Beispiel bietet ein Zustellpunkt den Rückkanal FINK und Elster für alle Verwaltungsleistungen an. Die beiden Verwaltungsleistungen besitzen darüber hinaus noch weitere Rückkanaloptionen. Onlineservices können diesen dann auswählen.

Das Auswählen passiert technisch durch Angabe des gewählten Rückkanals in den Metadaten. Dort ist derzeit nur die Angabe eines einzigen Rückkanals zulässig. Der gewählte Rückkanal muss darüber hinaus vom adressierten Zustellpunkt unterstützt werden.

Beispiel: Auswahl des Rückkanals fitConnect​

Das folgende Beispiel für die Metadaten einer Einreichung zeigt FIT-Connect als Rückanalauswahl. Die Version des Metadatenschemas (Feld $schema) ist dabei natürlich auszufüllen.

{
  "$schema": "https://schema.fitko.de/fit-connect/metadata/<VERSION>/metadata.schema.json",
  // ...
  "replyChannel": {
    "fitConnect": {
      "processStandards": [
        "urn:xoev-de:bmk:standard:xbau_2.4"
      ],
      "encryptionPublicKey": {
        "kty": "RSA",
        "key_ops": [
          "wrapKey"
        ],
        "alg": "RSA-OAEP-256",
        "kid": "……(Key ID)……",
        "n": "……(Modulus Parameter)……",
        "e": "AQAB"
      }
    }
  }
}