Aktionen

Funktionen und Verwendung von windata black box

Aus windata WIKI

 

Voraussetzung

Um windata black box wie im folgenden Text beschrieben nutzen zu können, muss die Einrichtung von windata black box abgeschlossen sein.

Einführung

Die windata black box bietet Entwicklern die Möglichkeit, leistungsfähige und sichere Banking-Funktionen in eigene Programme zu integrieren. Es stehen dabei verschiedene Kommunikations- und Legitimationsverfahren zur Verfügung:

  • HBCI/FinTS mit Chipkarte
  • HBCI/FinTS mit Schlüsseldatei
  • HBCI/FinTS mit PIN/TAN
  • HBCI/FinTS mit 2-Schritt-TAN-Verfahren
  • EBICS

Zusätzlich besteht die Möglichkeit Transaktionsdaten eines Paypal-Accounts abzurufen. Dabei werden alle Transaktionen mit den zugehörigen Detaildaten bereitgestellt.
Zahlungsdaten müssen in einem der folgenden Formate vorliegen:

  • DTAUS (belegloser Datenträgeraustausch, Inlandszahlungen)
  • DTAZV (belegloser Datenträgeraustausch, Auslandszahlungen)
  • SEPA-Überweisungen (SEPA-XML)
  • SEPA-Basislastschriften (SEPA-XML)
  • SEPA-Firmenlastschriften (SEPA-XML)
  • SEPA-Überweisungen (SEPA, CSV)
  • SEPA-Basislastschriften (SEPA, CSV)
  • SEPA-Firmenlastschriften (SEPA, CSV)
  • BZAHL-Dateien (*.XBZ-Datei)

Die zu übertragende Datei muss sich im definierten Ordner (Optionen) befinden.

  • Hinweis: Um Zahlungen zu übertragen muss kein bestimmtest Auftraggeberkonto aufgerufen werden. Es wird automatisch das Konto verwendet, welches in der zu übertragenden Datei genannt ist.

Parameter für den Programmaufruf

Das Programm wird durch sog. Übergabeparameter gesteuert. Diese Parameter sind kombinierbar:

wd8bb.exe /Übergabeparamater1/Übergabeparamater2 etc.

Beim Aufruf des ausführbaren Programms (wd8bb.exe) können folgende Übergabeparameter verwendet werden:

  • /Abruf - Kontoumsätze werden abgerufen - in Verbindung mit /HBCI bzw. /EBICS (MT940)
  • /Senden - Zahlungen aus dem definierten Verzeichnis werden versandt - in Verbindung mit /HBCI bzw. /EBICS
  • /Ordner:<Ordner> - Im Parameter kann der Pfad mitgegeben werden, aus welchem Zahlungen übertragen werden sollen.
  • /HBCI - Das Kommunikationsverfahren HBCI wird angesprochen - in Verbindung mit weiterem Befehl
  • /EBICS - Das Kommunikationsverfahren EBICS wird angesprochen - in Verbindung mit weiterem Befehl
  • /Ab<Datum> - Hier kann ein Datum (Format: TT.MM.JJJJ) für den historischen Abruf von Kontoumsätzen mitgegeben werden - in Verbindung mit weiterem Befehl
  • /Automatik - Parameter zur automatischen Befehlausführung - gleichgestellt mit /Silent sowie /Hidden - in Verbindung mit weiterem Befehl
  • /Benutzer:<Benutzer> - hier kann mit der gewählten EBICS-Aktion ein angelegter EBICS-Benutzer in windata black box angesprochen werden.
  • /Mandant:<Name des Mandanten> - hier kann mit der gewählten Aktion ein bestimmter Mandant in windata black box angesprochen werden.
  • /VMP - Vormerkposten werden abgerufen
  • /Abrufcamt - CAMT-Nachrichten werden abgerufen
  • /BZAHL - XBZ-Dateien werden versandt - nur per EBICS möglich
  • /DTV - Zahlungsaufträge werden versandt - nur per EBICS möglich
  • /Devisen - Abruf und Export von aktuellen Devisenkursen.
  • /Drucker: - Hier kann gesteuert werden, auf welchem Drucker das Übertragungsprotokoll gedruckt werden soll.
  • /PayPal - Umsätze aller eingerichteten PayPal-Konten abrufen
  • /PayPal/Refund/ID:<TransaktionID>/Benutzer:<API-Benutzer>/VWZ:<Verwendungszweck> - vollständige Erstattung einer PayPal-Buchung
  • /PayPal/Refund/ID:<TransaktionID>/Benutzer:<API-Benutzer>/VWZ:<Verwendungszweck>/Betrag:<Betrag>/Währung:<Währung> - teilweise Erstattung einer PayPal-Buchung
  • /Abruf/Protokoll - EBICS-Protokoll (PTK) im TXT-Format abrufen
  • /Abruf/Protokoll/HAC - EBICS-Protokoll (HAC) im XML-Format abrufen
  • /Sandbox - gewählte Aktion (Dateiversand) wird ohne Echtkontakt zu einem Kreditinstitut ausgeführt - ideal als Testumgebung im Rahmen der Implementierung -> Beschreibung. (ab Version 8.6.0.6)

Nachfolgend werden die zulässigen Übergabeparameter in praktischen Beispielen erläutert:

HBCI/FinTS

Abruf von Kontoumsätzen mit Benutzerführung

wd8bb.exe /Abruf/HBCI

Abruf von Kontoumsätzen mit hinterlegter PIN (bei PIN/TAN-Verfahren bzw. Schlüsseldatei) im sog. silent mode

wd8bb.exe /Abruf/HBCI/Automatik

Zahlungen senden mit Benutzerführung

wd8bb.exe /Abruf/HBCI/Automatik/Ab<Datum>
/Ab<Datum> (Format: TT.MM.JJJJ)
wd8bb.exe /Senden/HBCI

Zahlungen senden mit hinterlegter PIN (bei PIN/TAN-Verfahren bzw. Schlüsseldatei) im sog. silent mode

wd8bb.exe /Senden/HBCI/Automatik

Zahlungen senden mit hinterlegter PIN (bei PIN/TAN-Verfahren bzw. Schlüsseldatei) im sog. silent mode

wd8bb.exe /Senden/HBCI/Automatik

EBICS

Abruf von Kontoumsätzen per EBICS

wd8bb.exe /Abruf

Abruf von Kontoumsätzen mit Benutzerführung

wd8bb.exe /Abruf/Benutzer: <Benutzer>

Wenn der Benutzername nicht mit übergeben wird, wird immer das Dialogfenster zur Auswahl eines Benutzers eingeblendet.
Abruf von Kontoumsätzen mit hinterlegtem Passwort im sog. silent mode

wd8bb.exe /Abruf/Automatik/Benutzer:<Benutzer>

Abruf von Vormerkposten mit Benutzerführung

wd8bb.exe /Abruf/VMP/Benutzer:<Benutzer>

Wenn der Benutzername nicht mit übergeben wird, wird immer das Dialogfenster zur Auswahl eines Benutzers eingeblendet.
Abruf von Vormerkposten mit hinterlegtem Passwort im sog. silent mode

wd8bb.exe /Abruf/VMP/Automatik/Benutzer:<Benutzer>

Zahlungen senden mit Benutzerführung

wd8bb.exe /Senden/Benutzer:<Benutzer>

Wenn der Benutzername nicht mit übergeben wird, wird immer das Dialogfenster zur Auswahl eines Benutzers eingeblendet.
Zahlungen senden mit hinterlegtem Passwort im sog. silent mode

wd8bb.exe /Senden/Automatik/Benutzer:<Benutzer>

Zahlungen mit verteilter, elektronischer Unterschrift (VEU) senden
Der Übergabeparameter wird um den Zusatz /VEU an beliebiger Stelle ergänzt.
Bsp.:

wd8bb.exe /Senden/VEU/Automatik/Benutzer:<Benutzer>
wd8bb.exe /VEU/Senden/Benutzer:<Benutzer>

BZAHL-Dateien

Um XBZ-Dateien aus Geldkartenumsätzen per EBICS zu übertragen, muss der Parameter /BZAHL hinzugefügt werden.

Mandantenverwaltung

Die Bereitstellung von abgerufenen Daten für einen bestimmten Mandanten wird über den Parameter

/Mandant:<Name des Mandanten>

gesteuert. Der Name des Mandanten muss entsprechend der Namensgebung bei der Anlage des Mandanten erfolgen.
Die Mandantenverwaltung wird hier aufgerufen.

Automatische Ausführung

Über den windows-Aufgabenplaner kann die Ausführung von windata black box zeitgesteuert und automatisiert ausgeführt werden. Somit ist die Implementierung der windata black box in andere Softwareprogramme nicht zwingend notwendig.
Über diesen Weg kann sicheres Onlinebanking automatisiert durchgeführt werden, ohne dass Ihr Softwarehersteller Funktionen der windata black box implementiert.
Hinweis: Wenn der windows-Aufgabenplaner genutzt wird, muss die Benutzerkontensteuerung vollständig deaktiviert sein!

Registry

Im Rahmen der Installation von winata black box wird folgender Eintrag in der windows-Registry erstellt:
HKEY_CURRENT_USER\Software\windata black box
Hier kann unter dem Wert App.Path der Installationspfad von windata black box ausgelesen werden.

Steuerdatei für den Abruf von Kontoumsätzen

Ab der Version 8.7.0.9 kann die AbrufKonten.csv wahlweise mit Kontonummer & Bankleitzahl oder IBAN erstellt werden:

Kontonummer & Bankleitzahl

Die Steuerdatei muss folgenden Dateiname und Dateikennung haben:
AbrufKonten.csv
Es handelt sich hierbei um eine Textdatei, bei der die einzelnen Daten mit Semikolon (;) getrennt werden. Jede Zeile entspricht einem Datensatz. Der Aufbau der Datei ist wie folgt:
Konto-Nr; BLZ; Währung
Bsp.:
1234567; 65050110; EUR
5697890; 65092010; USD
Die Angabe der Bankleitzahl ist optional. Sie ist nur dann zwingend anzugeben, wenn eine Kontonummer bei einem Kreditinstitut für mehrere Konten mit unterschiedlicher Währung verwendet wird.
Bsp.: Eine Kontonummer wird sowohl für ein EUR- als auch für ein USD-Konto genutzt.
123456789; 65070024; EUR
123456789; 65070024; USD

IBAN

Die Steuerdatei muss folgenden Dateiname und Dateikennung haben:
AbrufKonten.csv
Es handelt sich hierbei um eine Textdatei, bei der die einzelnen Daten mit Semikolon (;) getrennt werden. Jede Zeile entspricht einem Datensatz. Der Aufbau der Datei ist wie folgt:
IBAN; Währung
Bsp.:
DE9665050110123456789; EUR
DE9665050110123456789; USD
Bsp.: Eine IBAN wird sowohl für ein EUR- als auch für ein USD-Konto genutzt.

Das Währungskennzeichen ist ebenfalls optional und muss nur angegeben werden, wenn die Kontowährung nicht EUR lautet. Ist das Währungskennzeichen nicht angegeben, wird die Standardwährung Euro genutzt. Abweichende Währungskennzeichen sind gem. ISO 4217 (s. Anhang) anzugeben.
Die Datei AbrufKonten.csv muss sich im selben Ordner wie die ausführbare Datei wd8bb.exe befinden.

Satzaufbau für SEPA, CSV-Dateien

Zum automatisierten Import von SEPA-Zahlungen im Format CSV (Textdatei, Felder durch Semikolon getrennt, einzelne Datensätze sind durch CR/LF zu trennen) ist nachfolgender Satzaufbau zu berücksichtigen.

  • Im CSV-Format können nach windata black box nur SEPA-Zahlungen (Überweisungen und Lastschriften) übergeben werden. DTAUS- und DTAZV-Dateien müssen als fertige Dateien an windata black box übergeben werden.

    Hinweis: CR/LF= Carriage Return + Line Feed

Die erste Zeile der CSV-Datei enthält die Kennzeichnung des Importformats und ist mit dem Wert windata CSV zu belegen. In der zweiten Zeile sind zwingend die Feldbezeichnungen wie nachfolgend dargestellt anzugeben und mit einem CR/LF abzuschließen:
AG Name; AG KontoNr; AG BLZ; Beg/Zahlpfl Name; Beg/Zahlpfl Name2; Beg/Zahlpfl Strasse; Beg/Zahlpfl Ort; Beg/Zahlpfl KontoNr bzw. IBAN; Beg/Zahlpfl BLZ bzw. BIC; Betrag; Währung; Textschlüssel bzw. Zahlart; Termin; VWZ1; VWZ2; VWZ3; VWZ4; VWZ5; VWZ6; VWZ7; VWZ8; VWZ9; VWZ10; VWZ11; VWZ12; VWZ13; VWZ14; Ref-ID; Mandat-ID; Mandat-Datum, AG Gläubiger-ID; Sequenz

Datensatzbeschreibung

Feldbezeichnung   Inhalt Typ Länge
AG Name P Name des Auftraggebers Text 27
AG KontoNr P Kontonummer des Auftraggeberkontos numerisch 10
AG BLZ P Bankleitzahl des Auftraggeberinstituts numerisch 8
Beg/Zahlpfl Name P Name des Begünstigten (bei Überweisungen) bzw. Zahlungspflichtigen (bei Lastschriften) Text 27
Beg/Zahlpfl Name2 O Weitere Angaben zum Name des Begünstigten (bei Überweisungen) bzw. Zahlungspflichtigen (bei Lastschriften) Text 27
Beg/Zahlpfl Strasse O Straße des Begünstigten (bei Überweisungen) bzw. Zahlungspflichtigen (bei Lastschriften) Text 27
Beg/Zahlpfl Ort O Ort des Begünstigten (bei Überweisungen) bzw. Zahlungspflichtigen (bei Lastschriften) Text 27
Beg/Zahlpfl KontoNr bzw. IBAN P IBAN des Begünstigten (bei Überweisungen) bzw. Zahlungspflichtigen (bei Lastschriften) Text 35
Beg/Zahlpfl BLZ bzw. BIC EP BIC des Begünstigten (bei Überweisungen) bzw. Zahlungspflichtigen (bei Lastschriften) Text 11
Betrag P Betrag im Format XXXX,XX Beträge ohne Nachkommastellen werden mit ,00 beim Import ergänzt numerisch, Komma als Trennzeichen für Nachkommastellen 12
Währung O EUR Text 3
Textschlüssel bzw. Zahlart P SEPA: für SEPA-Überweisungen (Angabe der Währung entfällt, immer EUR)

BASIS: für SEPA-Basis-Lastschriften (Angabe der Währung entfällt, immer EUR) FIRMEN: für SEPA-Firmenlastschriften (Angabe der Währung entfällt, immer EUR)

Text 6
Termin O Fälligkeits- bzw. Ausführungstermin Datum TT.MM.JJJJ 10
VWZ1 O Verwendungszweck Text 27
VWZ2 O Verwendungszweck Text 27
VWZ3 O Verwendungszweck Text 27
VWZ4 O Verwendungszweck Text 27
VWZ5 O Verwendungszweck Text 27
VWZ6 O Verwendungszweck Text 27
VWZ7 O Verwendungszweck Text 27
VWZ8 O Verwendungszweck Text 27
VWZ9 O Verwendungszweck Text 27
VWZ10 O Verwendungszweck Text 27
VWZ11 O Verwendungszweck Text 27
VWZ12 O Verwendungszweck Text 27
VWZ13 O Verwendungszweck Text 27
VWZ14 O Verwendungszweck Text 27
Ref-ID O Referenznummer Text 35
Mandat-ID SLO Lastschriftmandat Text 35
Mandat-Datum SLO Datum des Lastschriftmandats (Ausstellungsdatum) Datum TT.MM.JJJJ 10
AG Gläubiger-ID SLO Gläubiger-ID (zu beantragen bei der Deutschen Bundesbank Text 35
Sequenz SLO / SLR Gibt bei SEPA-Lastschriften an, ob es sich um eine Erst- (FRST), Folge- (RCUR), Einmal- (OOFF) oder letztmalige (FNAL) Lastschrift handelt. Text 4

 

Hinweise:
P = Pflichtangabe; O = optional; SLO = Pflichtangabe bei allen Formen der SEPA-Lastschriften sofern Mandatsinformationen bekannt bzw. Mandatsverwaltung über andere Anwendung durchgeführt wird; EP = Pflichtangabe bei europäischen SEPA-Transaktionen, optionale Angabe bei innerdeutschen SEPA-Transaktionen (IBAN-only); SLR = Pflichtangaben bei SEPA-Basis- und Firmenlastschrift, nicht bei SEPA-Basis-Eillastschrift (COR1)
Die CSV-Datei kann Zahlungen verschiedener Zahlungsarten enthalten.
Leere Zeilen sind zulässig. Jede Zeile muss mit einem CR/LF abgeschlossen werden.

Datensatzbeschreibung der SendenStatus.txt

Datum; Datei; Zahlart; Konto-Nr.; BLZ; Bank; Betrag; Übertragen; Information; Referenz-ID, Auftragsnummer

Die Datei - SendenStatus.txt - wird nach jeder Übertragung in dem Verzeichnis erzeugt, aus welchem die zu übertragenen Zahlungsdateien geholt wurden. Je übertragene Zahlungsdatei wird eine eigene Zeile in der SendenStatus.txt erzeugt. Ein Protokoll je Zahlung ist nicht möglich.
In der Spalte Zahlart gibt es folgende Möglichkeiten:

  • EU --> Überweisungen
  • EUL --> Lastschriften
  • EULF --> Firmenlastschriften
  • AZV --> Aussenwirtschaftsverkehr

Ab der Version 8.6.0.7 kann die SendenStatus.txt anstelle von Konto-Nr. & BLZ mit IBAN & BIC erstellt werden.

Satzaufbau für Kontoumästze im CSV-Format

Im Anschluß an den Abruf von Kontoumsätzen über die windata black box werden immer zwei Dateien erzeugt:

  • AbrufStatus.txt
Diese Datei beinhaltet Details zum Abruf der Kontoumsätze.
  • Datei mit Kontoumsätzen
Diese Datei beinhaltet alle Kontoumsätze des jeweiligen Zeitraums.

Datensatzbeschreibung der AbrufStatus.txt

Datum; Konto-Nr.; BLZ; Bank; Abruf; Information

Die Datei - AbrufStatus.txt - wird in das Verzeichnis erstellt, in welchem auch die abgeholten Umsätze abgelegt werden.
Im Feld - Übertragen - ist der Wert - Ja - oder - Nein - zu finden. Dieser Wert wird aufgrund Rückmeldecodes vom Bankrechner durch windata black box generiert. Dieser Wert ist programmtechnisch auswertbar.
Jeder Abruf wird incl. Rückmeldung vom Bankrechner protokolliert. Diese individuellen Rückmeldungen können von Rechenzentrum zu Rechenzentrum unterschiedlich sein - den Freitext finden Sie 1:1 im Feld Information wieder.

Ab der Version 8.6.0.7 kann die AbrufStatus.txt anstelle von Konto-Nr. & BLZ mit IBAN & BIC erstellt werden.
Zum automatisierten Export von Kontoumsätze im Format CSV (Textdatei, Felder durch Semikolon getrennt) ist nachfolgender Satzaufbau zu berücksichtigen:

Datensatzbeschreibung der Kontoauszug.csv

Konto-Währung; IBAN Auftraggeber; Konto-Nr. Auftraggeber; BIC Auftraggeber; BLZ Auftraggeber; Buchungstag; Valuta; Betrag; Währung; Sall/Haben (CRDT/DBIT); Ende-zu-Ende-Ref; Kundenreferenz; Mandats-ID; Gläubiger/Creditor-ID, VWZ1; VWZ2; VWZ3; VWZ4; VWZ5; VWZ6; VWZ7; VWZ8; VWZ9; VWZ10; VWZ11; VWZ12; VWZ13; VWZ14; Buchungstext; Primanota; Geschäftsvorfallcode, Name; IBAN; Konto-Nr.; BIC; BLZ; Auszugs-Nr.; AnfangsSaldo; Soll/Haben (CRDT/DBIT); Endsaldo; Soll/Haben (CRDT/DBIT); Textschlüssel; Textschlüsselergänzung

Devisenkurse

Mit windata black box können aktuelle Devisenkurse abgerufen und exportiert werden.
Der Abruf und Export kann manuell oder auch automatisiert durchgeführt werden.

Das Menü Devisenkurse kann manuell unter Tools / Devisenkurse aufgerufen werden. Hier kann der Abruf der aktuellen Kurse sowie auch der Export der aktuellen Daten angestoßen werden.
Die Funktion "Devisenkurse abrufen und exportieren" kann automatisch über den Parameter /Devisen aufgerufen werden.

Protokoll

Ein Protokoll über alle Aktivitäten von windata black box wird automatisch im Ordner Protokoll, im Installationsverzeichnis der windata black box, unter dem Dateinamen <Rechnername>-PC-bbcf.log erstellt.

Downloads

Die vollständige Beschreibung der windata black box kann hier als PDF-Datei geöffnet werden: Funktionen und Verwendung von windata black box
windata black box steht allen Interessenten als installationsfähige exe-Datei zum Download zur Verfügung: windata black box

Interessante Links

Eine aktuelle Liste der im deutschen Zahlungsverkehr genutzten Textschlüssel finden Sie unter www.zahlungsverkehrsfragen.de
Eine aktuelle Liste der Purpose-Codes im SEPA-Zahlungsverkehr finden Sie unter Purpose-SEPA-Codes
Die automatisierte Konvertierung von Kto.Nr. und BLZ in IBAN und BIC auf Grundlage von windata black box ist hier beschrieben: Konvertierung von Kto.Nr. und BLZ in IBAN und BIC
Die Beschreibung der aktuellen Updates für windata black box sind hier beschrieben: Release Historie windata black box