AS4 Receipt Service | Produktdokumentation

AS4 Receipt Service Dokumentation

Der Receipt Service validiert die Eingangsbestätigung des Marktpartners und erstellt Eingangsbestätigungen als Response für erhaltene AS Nachrichten.

Hardware Anforderungen

Eine Service-Instanz erfordert mindestens 1024 MB RAM.

Wir empfehlen 0,6 CPU-Kerne je Instanz.

Logs werden auf die Festplatte geschrieben, entsprechend muss genügend Speicherplatz vorhanden sein.

Abhängigkeiten

Der Service greift auf einen Message-Broker zu, um Nachrichten zu empfangen und zu versenden.

Einfache Konfiguration der as4-receipt-service.properties

Die Kommunikation zwischen den verschiedene AS4 Services erfolgt über einen Message-Broker.

#=== RabbitMQ Con
rabbitmq.host=localhost
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=guest

AMQP Routing Konfiguration

Falls Sie das Standard Routing nutzen, muss das Routing nicht weiter konfiguriert werden. Wenn Sie Ihr Routing anpassen möchten, lesen Sie die folgende Dokumentation.

Der Outbound Receipt

Über diesen Consumer werden eingehende Receipts vom Crypto Operations in der Queue as4.receipt.parse.default entgegengenommen, welche der AS4 Outbound Sender vom Marktpartner erhalten hat und diesen an den Crypto Operations weitergeleitet hat.

receiptParseExchangeName=as4.receipt.parse

Der Inbound Receipt

Dieser Consumer empfängt über die Queue as4.receipt.create.default die AS4 Nachricht (in diesem Kontext auch als Business Message bekannt) vom Crypto Operations, welcher diese vom AS4 Inbound Endpoint erhalten hat, um dafür eine Empfangsbestätigung zu generieren.

receiptCreateExchangeName=as4.receipt.create

Versenden der Empfangsbestätigung zur Persistierung

Mit dem Producer wird die vom AS4 Outbound Sender empfangene Bestätigung an den AS4 Message Service zum Speichern versendet. Der Name der Queue ist as4.receipt.default.

receiptExchangeName=as4.receipt

Versenden der Business Message

Der Producer versendet die vom Marktpartner eingegangene AS4 Nachricht als Business Message zum Speichern an den AS4 Message Service. Die Queue heißt as4.messages.default.

businessMessageExchangeName=as4.messages

Signieren der Empfangsbestätigung

Der Producer versendet über as4.sign.default die erstellte Bestätigung an den Crypto Operations zwecks Anbringung der Signatur.

createdReceiptExchangeName=as4.sign

Der Marktpartner bestätigt unsere Adressänderung

Mit dem Pathswitch Provider wird die Annahme der Adressänderung des Tenants vom Marktpartner bestätigt. Diese Bestätigung geht über die Queue as4.outbound.pathswitch.default an den AS4 Address Service.

pathswitchConfirmationExchangeName=as4.outbound.pathswitch

Validierung

Um zu einer eingehenden Nachricht ein Receipt zu erstellen, wird die Nachricht vorerst validiert. Zur Validierung sind die folgenden Parameter erforderlich. Wichtig ist hier, für die Variable expectedSystems die Receiver, also die Mandanten selbst einzutragen, damit geprüft werden kann, ob der Marktpartner auch an den richtigen Mandanten geantwortet hat. Um die Validierung auf den Receiver/Mandanten zu überspringen, kann der Wert leer gelassen, oder die Property entfernt werden.

Die weiteren Prüfungskategorien sind AS4 Protokoll spezifisch und sollten von einem Fachmann verändert werden. ServiceId gibt dabei den Service aus dem Header der AS4 Message an und ActionId die Action aus dem Header.

expectedSystems=9907647000008,9903111000003,9900051000002

expectedElectricityServiceIds=https://www.bdew.de/as4/communication/services/MP,https://www.bdew.de/as4/communication/services/pathSwitch,http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test
expectedElectricityActionIds=http://docs.oasis-open.org/ebxml-msg/as4/200902/action,https://www.bdew.de/as4/communication/actions/requestSwitch,https://www.bdew.de/as4/communication/actions/confirmSwitch,http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test

expectedGasServiceIds=A02
expectedGasActionIds=http://docs.oasis-open.org/ebxml-msg/as4/200902/action,http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test

Neben den fachlichen Paramtern, wird ebenfalls validiert, ob das Receipt einen negativen StatusCode hat, oder Probleme bei der Signierung, Ver- und Entschlüsselung vorliegen. Das Receipt wird mit der jeweiligen Fehlermeldung an den as4-message-service gesendet und dort persistiert. Vorliegende Fehler lassen sich im Nachrichtenmonitor einsehen.

Validierung Relation

Validierung Relation: Strom und Gas

Mit der Eigenschaft check-relation=true werden Marktnachrichten per negativem Receipt abgelehnt, wenn eine unbestätigte oder keine Beziehung vorliegt. Zudem werden Pathswitch- und Pingnachrichten per negativem Receipt abgelehnt, wenn keine Beziehung vorliegt.

Um eine Beziehung zu validieren, muss außerdem ein API-Aufruf beim as4-Adress-Service erfolgen, um zu prüfen, ob die Beziehung bereits bestätigt ist oder nicht. Standardmäßig ist AddressServiceUrl leer.

addressServiceUrl=http://as4-address-service:8080/aep-as4-address-service

Validierung Relation: Gas

Mit der Eigenschaft check-relation-gas=true werden Gas-Marktnachrichten per negativem Receipt abgelehnt, wenn eine unbestätigte oder keine Beziehung vorliegt. Stromnachrichten werden nicht abgelehnt.

addressServiceUrl=http://as4-address-service:8080/aep-as4-address-service

Vor dem 01.04.2025 empfehlen wir, check-relation-gas zu verwenden, da bis zu diesem Zeitpunkt für die Kommunikation von Gas-Nachrichten der Pathswitch-Prozess verpflichtend ist.

Beziehung automatisch bestätigen

Es ist möglich eine bisher unbekannte oder unbestätigte Beziehung automatisch während der Nachrichtenverarbeitung (Inbound außer ping/pathswitch) zu bestätigen. Nachdem die Beziehung bestätigt wurde, können Nachrichten dieser Beziehung verarbeitet werden.

Dieses Feature kann aktiviert werden, indem der folgende Parameter auf „true“ gesetzt wird. Standardmäßig ist er auf „false“ gesetzt.

autoConfirmRelation=true

Um eine Beziehung automatisch zu bestätigen, muss außerdem ein API-Aufruf beim as4-Adress-Service erfolgen, um zu prüfen, ob die Beziehung bereits bestätigt ist oder nicht. Standardmäßig ist AddressServiceUrl leer.

addressServiceUrl=http://as4-address-service:8080/aep-as4-address-service

Um eine Beziehung automatisch zu bestätigen, wird eine Warteschlange verwendet und die folgende Konfiguration muss hinzugefügt werden.

relationCreateExchangeName=as4.relation.create
relationCreateHeaderName=default
relationCreateHeaderValues=

Beziehung automatisch bestätigen: Strom

Um die automatische Bestätigung von Beziehungen nur für Strom-Nachrichten zu aktivieren, ist anstatt der Eigenschaft autoConfirmRelation, die Eigenschaft autoConfirmRelationElectricity auf true zu setzen.

Vor dem 01.04.2025 empfehlen wir, autoConfirmRelationElectricity zu verwenden, da bis zu diesem Zeitpunkt für die Kommunikation von Gas-Nachrichten der Pathswitch-Prozess verpflichtend ist und Beziehungen von Gas-Marktpartnern somit ohne Pathswitch nicht bestätigt werden dürfen.

Routing Konfiguration der as4-receipt-service.properties

Für die Aktivierung des Routings müssen der headerName und die headerValues gesetzt werden. Den headerName kann man sich als Filterkategorie vorstellen, während die headerValues den zu filternden Werten entsprechen. Nachrichten mit Werten, die nicht explizit als headerValues aufgelistet sind, laufen weiterhin über die default Route.

Als headerName werden folgende Parameter angeboten:

tenant: ILN Nummer des Senders
partner: ILN Nummer des Empfängers.
sector: GAS, ELECTRICITY

Es können mehrere Werte kommasepariert angegeben werden.

receiptExchangeName=as4.receipt
receiptHeaderName=tenant
receiptHeaderValues=

businessMessageExchangeName=as4.messages
businessMessageHeaderName=tenant
businessMessageHeaderValues=

createdReceiptExchangeName=as4.sign
createdReceiptHeaderName=tenant
createdReceiptHeaderValues=

pathswitchConfirmationExchangeName=as4.outbound.pathswitch
pathswitchConfirmationHeaderName=tenant
pathswitchConfirmationHeaderValues=

Wird der Producer für das Routing konfiguriert muss natürlich auch die Gegenstelle dafür eingerichtet werden. Dem Consumer wird über die Gruppe der Wert (Value) aus der HeaderValues Liste zugewiesen nach welchem gefiltert werden soll. Bitte den Default Wert nur ändern, wenn Routing verwendet werden soll.

receiptParseExchangeName=as4.receipt.parse
receiptParseGroup=default

receiptCreateExchangeName=as4.receipt.create
receiptCreateGroup=default

Max Concurrency - Parallelität

Für jeden Consumer ist es möglich die Eigenschaft max-concurrency zu setzen. Diese definiert die maximale Anzahl von gleichzeitigen Verarbeitungsthreads, die für einen Consumer gestartet werden können. Der Default steht für jeden Consumer auf 50.

receiptParseMaxConcurrency=50
receiptCreateMaxConcurrency=50

Keycloak

Bei Bedarf kann die REST-API per Keycloak abgesichert werden.

Zip Payload

Die Nutzlast/der Anhang im eingehenden Fluss wird genau dann gezippt, wenn zipPayload=true konfiguriert ist (Standardwert: false).

zipPayload=false

Falls dieses Feature genutzt wird, muss dies mit der technischen Mako abgestimmt werden. Falls Sie die B2B nutzen, können Sie die gleiche Property am B2B-Message-Service konfigurieren.

REST API Dokumentation

Die API bietet Server-Health Informationen an.

Der Port lässt sich über folgende Property konfigurieren: server.port=8080

Swagger

Die Beschreibung der REST API lässt sich, im Fall einer Docker Installation, unter

http://host.docker.internal:8095/aep-as4-receipt-service/swagger-ui/index.html

oder unter

http://localhost:8080/aep-as4-receipt-service/swagger-ui/index.html

finden.

Anhang: Gesamtkonfiguration

Folgende Konfiguration reicht in einem Standard-System aus: application.properties:

#=== Rabbitmq Configuration ===#
rabbitmq.host=rabbitmq3
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=${RABBITMQ_PASSWORD}

Allgemeine Hinweise zur Konfiguration finden Sie hier.

View Me Edit Me