Vorwort

Die ePayBL bietet die Möglichkeit, die durch automatisierte Prozesse erzeugten Dateien (XFinanz und camt.054) über die Schnittstelle (REST-API, in der Hersteller-Dokumentation auch "Konnektor" oder genannt) herunterzuladen. Dieser Leitfaden soll dabei helfen ihr HKR-System an die Schnittstelle der ePayBL anzubinden. Dazu wird das Vorgehen für die Anbindung beschrieben und Hinweise für Testmöglichkeiten gegeben. 

Maßgeblich für die Anbindung an die ePayBL und Quelle für Detailinformationen ist das Integrationshandbuch ePayBL-Konnektor des Softwareherstellers in der jeweils neusten Version. Dieses ist auf Anfrage erhältlich. Bitte wenden Sie sich dazu per E-Mail (mit Angabe Ihres Namens und Ihrer Firma) an Ihren Auftraggeber zur Weiterleitung an die Berater oder das Produktmanagement ePayment. 

Vorgehen

Das Vorgehen wird nachfolgend Schritt für Schritt erläutert. Für Testzwecke stellt Dataport einen eigenen Mandanten in der Stage-Umgebung zur Verfügung. Dieser kann gerne genutzt werden. Die Infos zum Test-Mandanten sind in den entsprechenden Abschnitten in Infoboxen eingefügt.

Für eine reibungslose Integration wird die Integration in drei Schritten empfohlen:

Begriffe

In diesem und in verlinkten Dokumenten werden die Begriffe "Stage", "Stage-Umgebung", "Stage-System" und "Test-Umgebung" bedeutungsgleich genutzt. D.h. die Begriffe meinen dasselbe. Dies ist historisch entstanden, weil Dokumentationen teils für verschiedene Zielgruppen oder von verschiedenen Abteilungen erstellt wurden. 

Dasselbe gilt für die Begriffe "Live", "Live-Umgebung", "Produktion" und "Produktionsumgebung", die untereinander austauschbar sind.

Allgemeine Voraussetzungen

Vor dem Start der erstmaligen Integration mit dem Testmandanten sollten folgende Punkte geklärt sein:

• Die ePayBL-Schnittstelle (s. unten) ist technisch aus Ihrem Netzwerk erreichbar.

Vor dem Start der Integration eines kundenspezifischen Mandanten (Kommune/Behörde/Land) sollten zudem folgende Punkte geklärt sein:

• Mandantennummer und Bewirtschafternummer für den anzubindenden Mandanten sind Ihnen bekannt. Bitte erfragen Sie diese anderenfalls bei Ihrem Kunden oder Auftraggeber. (Zum Verständnis: Ein "Mandant" ist eine Organisationseinheit in der ePayBL (Kommune, Behörde, Verwaltungseinheit - z.B. "Amt Kellinghusen"), die Mandantennummer ist das interne Kürzel für diesen Mandanten (z.B. "SHAMTKHN" für das Amt Kellinghusen). Ein Bewirtschafter ist ein Online-Dienst (z.B. "Gewerbeanmeldung") des jeweiligen Mandanten. Die Bewirtschafternummer ist entsprechend das interne Kürzel für diesen Bewirtschafter (z.B. "GAN") für die Gewerbeanmeldung.
• Die Verwendung der Methoden - also der Features, die in diesem Dokument vorgestellt werden - muss am Bewirtschafter freigeschaltet sein. Dies sollte standardmäßig der Fall sein. Falls es zu einem Fehler (-0836 "Der Download von Dateien via RESTAPI ist beim Bewirtschafter nicht konfiguriert") kommt, ist es noch nicht freigeschaltet. In diesem Fall muss die verantwortliche Person des Mandanten bzw. Bewirtschafters über eine Supportanfrage in OSI Service Desk (OSI Service Desk - ePayment Supportanfrage) eine Freischaltung beauftragen.

Zertifikat

Für den Zugriff auf die ePayBL wird ein mandatenspezifisches Webservice-Zertifikat benötigt. Dieses stellt sicher, dass eine geschützte Verbindung aufgebaut werden kann. Falls noch nicht vorhanden, wird das Zertifikat so beantragt und eingesetzt:

1. Rufen Sie die Seite zur Beantragung eines neuen Zertifikats auf. Abhängig davon, ob es um einen Mandanten auf der Produktiv- oder Stage/Test-Plattform geht, müssen Sie eine der beiden Varianten wählen:
   1. Für Mandanten auf der Produktiv-Plattform: https://epayment.dataport.de/paycert/ 
   2. Für Mandanten auf der Stage/Test-Plattform: https://epayment-stage.dataport.de/paycert/
2. Tragen Sie die Mandantennummer für Ihren Mandanten ein und Klicken Sie auf „Weiter zum Antrag“
3. Folgen Sie bei Fragen dieser Anleitung: Beantragung eines Webservice-Zertifikats in der ePayBL (dataport.de)

Wichtig:

• • Geben Sie Ihren echten Vor- und Nachnamen als Antragsteller und in den Feldern "Vorname (Besitzer)" und "Nachname (Besitzer)" Ihre Firma an. Bitte verwenden Sie im Folgenden vor allem Ihre echte E-Mailadresse. Dies dient dazu, dass das Produktmanagement Payment Ihre Anfrage zuordnen und Sie bei Bedarf erreichen kann.
  • Geben Sie das Bundesland als Länderkürzel ein, z.B. "SH"  (Liste Länderkürzel beim BMBF)
  • Geben Sie als Land "DE" ein - und nicht z.B. "Deutschland"

Die Freischaltung passiert i.d.R. innerhalb von 1 bis 2 Arbeitstagen.

Für die Einrichtung mit dem Test-Mandanten gehen Sie entsprechend wie folgt vor:

1. Rufen Sie https://epayment-stage.dataport.de/paycert/ auf
2. Tragen Sie "DPEFA1" als Mandantennummer ein
3. Füllen Sie das Formular nach diesem Beispiel - mit Ihren echten Daten und unter Berücksichtigung der o.g. Hinweise - aus:

4. Folgen Sie weiter der o.a. Anleitung: Beantragung eines Webserver-Zertifikats in der ePayBL (dataport.de)

Die Freischaltung passiert i.d.R. innerhalb von 1 bis 2 Arbeitstagen.

Informationen zur Schnittstelle

Ablauf der Kommunikation

Für den Download von Dateien müssen die folgenden Schritte durchlaufen werden:

Basis-URL

Für den unten genutzten Parameter "Basis-URL" sind die folgenden Angaben zu nutzen

https://epayment-stage.dataport.de/konnektor

https://epayment.dataport.de/konnektor

Endpunkt: Abfrage einer Dateiliste mit Downloadlinks

Die Liste der Dateien wird wie folgt abgefragt:

GET {Basis-URL}/epayment/hkr/v1_0/mandanten/{mandantennummer}/bewirtschafter/{bewirtschafternummer}/von/{erstellungsdatumVon}/bis/{erstellungsdatumBis}

Die Methode gibt dabei eine Liste von Dateien zurück, deren Erstellungsdatum >= {erstellungsdatumVon} und <={erstellungsdatumBis} liegt

• Dateiname
• Name des Unterordners ("kanalname") im Bewirtschafterverzeichnis (z.B. „camt054-KK“)
• Erstellungsdatum der Datei (Zeitstempel im Format YYYY-MM-DD hh:mm:ss.f) 
• Dateigröße in Byte
• Downloadlink für die Datei
• HashKey

Das Format von {erstellungsdatumVon} und {erstellungsdatumBis} muss DD.MM.YYYY entsprechen.

Der Downloadlink hat die Form:

/epayment/hkr/v1_0/mandanten/{mandantennummer}/bewirtschafter/{bewirtschafternummer}/<hashkey>

Die Downloadlinks (HashKeys) sind nur eine begrenzte Zeit gültig. Die Standardeinstellung ist 60 Minuten.

Das von der Methode zurückgegebene Ergebnis sieht - beispielhaft - so aus:

{
	"ergebnis": {
		"rc": "+0000",
		"ergebnistext": "Die Aktion wurde fehlerfrei durchgeführt"
	},
	"date": "07.12.2023 16:37:44",
	"downloadlinkListe": [
		{
			"dateiname": "XFi326472023.xml",
			"kanalname": "XFinanz3",
			"erstellungsdatum": "2023-01-26 17:47:14.974767",
			"dateigroesse": 94192,
			"downloadlink": "/epayment/hkr/v1_0/mandanten/DPEFA1/bewirtschafter/EfA1/956ec7ee-239f-43df-85f3-b47ad99a7701",
			"hashkey": "956ec7ee-239f-43df-85f3-b47ad99a7701"
		},
		{
			"dateiname": "XFi318032023.xml",
			"kanalname": "XFinanz3",
			"erstellungsdatum": "2023-03-18 08:03:11.933068",
			"dateigroesse": 29632,
			"downloadlink": "/epayment/hkr/v1_0/mandanten/DPEFA1/bewirtschafter/EfA1/9da55598-accd-467a-9253-d72bcd3c625f",
			"hashkey": "9da55598-accd-467a-9253-d72bcd3c625f"
		}
	]
}

Endpunkt: Dateidownload

Eine Datei aus einer abgefragten Dateiliste kann wie folgt heruntergeladen werden:

GET {Basis-URL}/epayment/hkr/v1_0/mandanten/{mandantennr}/bewirtschafter/{bewirtschafternr}/<hashkey>

Der Aufruf liefert eine Rückmeldung (s. Beispiel unten) und im Erfolgsfall im Feld "base64File" die Datei Base-64-Encoded zurück.

Speichern Sie die Datei ggf. unter dem Namen im Feld "dateiname" aus der zuvor abgefragten Dateiliste.

Das von der Methode zurückgegebene Ergebnis sieht - beispielhaft - so aus:

{
	"ergebnis": {
		"rc": "+0000",
		"ergebnistext": "Die Aktion wurde fehlerfrei durchgeführt"
	},
	"date": "06.10.2023 17:05:55",
	"base64File": "JVBERi0xLjUKJeLjz9MKNSAwIG9iago8PC9GaWx0ZXIvR"
}

Optional: Endpunkt: Datei löschen 

Eine Datei aus einer abgefragten Dateiliste kann wie folgt gelöscht werden.

Die Datei wird direkt gelöscht. Es erfolgt keine weitere Abfrage. Nutzen Sie die Methode daher mit Vorsicht.

DELETE {Basis-URL}/epayment/hkr/v1_0/mandanten/{mandantennr}/bewirtschafter/{bewirtschafternr}/<hashkey>

Das von der Methode zurückgegebene Ergebnis sieht - beispielhaft - so aus:

{
    "ergebnis": {
        "rc": "+0000",
        "ergebnistext": "Die Aktion wurde fehlerfrei durchgeführt"
    },
    "date": "23.11.2023 11:55:09"
}

Parametrisierung & Testaccount

Mandantennummer und Bewirtschafternummer

Die Mandanten bekommen für den tatsächlichen Betrieb die jeweiligen Mandantennummer und Bewirtschafternummer der Kreise & Kommunen. Zum allgemeinen Test (Phase 1 des Vorgehens) haben wir folgenden Mandanten in der Stage Umgebung:

Mandantennummer und Bewirtschafternummer sind case-sensitiv.

Anwendungstipps und ergänzende Hinweise

Verschiedene Dateien und deren Unterscheidung

Die Erstellung von XFinanz bzw. camt054 Dateien findet mit Hilfe sogenannter Kommunikationskanäle statt. Der Name des Kommunikationskanals findet sich im Parameter "kanalname" in der downloadlinkListe.

XFinanz 

Für den Kanalnamen gilt bei XFinanz Dateien das Muster  "<MANDANTENNUMMER>-<BEWIRTSCHAFTERNUMMER-V3", wobei das V3 für den XFinanz-Standard in der Version 3 (derzeit 3.1.0) steht.

Für den Testmandanten DPEFA1 mit dem Bewirtschafter EfA1 würde der Kanalname also "DPEFA1-EfA1-V3" lauten.

Einmal erstellte Dateien werden nicht wieder ergänzt oder überschrieben.

camt-054

Alle camt-054 Dateien eines Mandanten werden im Kanal "camt054-KK" abgelegt. Hier findet die Unterscheidung nach Zahlungsart (Kreditkarte bzw. Paypal) und nach dem Bewirtschafter anders als bei XFinanzdateien anhand des Dateinamens statt. Beispiel einer Paypal camt-054 bei DPEFA1/EfA1: " Paypal_camt054_CC_20230123_DPEFA1_EfA1_EfA1.xml". 

Einmal erstellte Dateien werden nicht wieder ergänzt oder überschrieben.

Laufzeitpunkte

XFinanz Dateien werden in der Stage-Umgebung stündlich automatisch erstellt. In der Produktionsumgebung findet ein Lauf pro Tag statt (derzeit ca. 0:15 Uhr). Es werden alle Transaktionen in die Datei verarbeitet die seit dem letzten Lauf angefallen sind. Eine erstellte XFinanz-Datei ist also weder mit dem aktuellen Tag, noch mit dem Vortag zeitlich deckungsgleich.

Camt-054 Dateien werden durch das manuelle Einspielen der gelieferten ZVP Dateien erzeugt. Dies findet einmal pro Tag statt. In der Camt054 Datei sind alle Transaktionen enthalten, die vom ZVP bereitgestellt wurden. Eine Camt-054 enthält die Aufschlüsselung der gehörigen Auswahl und muss auch nicht zeitlich deckungsgleich zu einem bestimmten Tag sein.

Empfehlungen für einen sicheren Abruf 

1. Die Abrufprozesse werden vollständig automatisiert.
2. Die Abfrage der Dateiliste wird stündlich durchgeführt mit Abrufdatum-von=gestern und Abrufdatum-bis=heute.
3. Mit der Ergebnisliste findet eine Prüfung auf neue Dateien bzw. Dubletten statt. Die Kombination aus dateiname und kanalname ist dabei eindeutig. Eine bisher unbekannte Kombination ist also eine neu abzurufende Datei. Ein hashkey ist kein geeigneter Identifikator zur Dublettenprüfung.
4. Die neu abzurufende Datei bzw. die abzurufenden Dateien werden einzeln mit dem Dateidownload heruntergeladen und entsprechend verarbeitet.

Feedback erwünscht

Im Falle von Fehler und auch zur allgemeinen Nutzung dieser Dokumentation freuen wir uns ausdrücklich über Feedback an das Dataport Produktmanagement Payment. Bitte nutzen Sie dazu unser Funktionspostfach - die Adresse erhalten Sie ggf. von Ihrem Berater.