AqBanking

aqbd ist ein für Linux verfügbares Commando-Zeilen-Tool (und Dämon), das es ermöglicht ...

... Umsätze und Salden eines Kontos via AqBanking-HBCI auszulesen. Als Ausgabe erzeugt aqbd CSV-Dateien, die leicht weiterverarbeitet werden können.
... Laschriften, die als CSV-Datei vorliegen, via AqBanking-HBCI an die Bank zu übertragen und durchzuführen.

weitere Infos über aqbd ...

... basiert 100% auf der Arbeit von Martin Preuss http://www.aquamaniac.de/ und der Bibliothek "AqBanking"
... erfordert "AqBanking" (Version >=3.99.5-beta)
... liegt im C-Quelltext (GPL 3.0 Lizenz) vor
... bietet im Zusammenspiel mit Apache2+PHP einen RESTful Webservice an
... bietet ein simples Webinterface, das es ermöglich eigene Konto-Daten mit einem Browser weltweit abzurufen

Download

Gwenhywfar: http://www.aquamaniac.de/sites/download/packages.php?package=01&showall=1
AqBanking: http://www.aquamaniac.de/sites/download/packages.php?package=03&showall=1
aqbd: http://cargobay.orgamon.de/aqbd.html

RESTfull Webservice-Design

Um AqBanking für den OrgaMon nutzbar zu machen wird ein Linux-basierter REST-Webservice implementiert. Dabei dient das Gesamtsystem (Apache2+PHP+index.php+aqbd-Dämon) nur als Wrapper für grundlegende "AqBanking Rev. 3.x" Funktionen. REST hilft uns, auf Kontoumsätze und andere Informationen ganz primitiv über das Web zuzugreifen. Zum Informations-Abruf benötigt man auf der Client-Seite nur einen einfachen Webbrowser (Punkt!). Dadurch ist auch die Integration in andere Prozesse ein Kinderspiel. Ruby on Rails z.B. kann REST-Webservices direkt ansprechen. "AqBanking-REST" bietet dabei folgende Dienste an ...

... Umsätze abrufen (./umsatz)
... Salden abrufen (./saldo)
... Sammel-Lastschriften durchführen (./lastschrift)
... OPTIONAL: (Termin-)Überweisungen durchführen (./ueberweisung)

Die Buchführung des OrgaMon kann "externe" Konten via Webserices (vorzugsweise REST) integrieren. Dadurch werden Giro-Konto-Buchungen direkt im OrgaMon sichtbar. Systematischer Aufbau des Server-Dienstes.

aqbd - der aqbanking dämon. Muss notwendigerweise als Dämon programmiert werden da z.B. das Mehrstufige TAN Verfahren mehrere REST-Zyklen benötigt und die Verbindung zur Bank dazwischen nicht unterbrochen werden darf, insbesondere beim iTAN Verfahren. Die Kommunikation mit der Aussenwelt erledigt der Dämon über das Dateisystem. Ein PHP-Script legt Konto-Anfragen in Mini "Job"-Dateien im Verzeichnis /srv/aqbanking ab.
aqREST - der REST Service als PHP Implementierung. Erfordert die mod_rewrite Anpassung im Apache2 (Beschreibung hier REST).

Installation (aqbd)

16.07.2009: Diese Anleitung gilt unverändert für gwen 3.9.0 in Verbindung mit aqb 4.1.0

Gwenhywfar installieren

Wir haben beide Packages (Gwen+AqB) in das Verzeichnis /usr/src entpackt.

gwen-Lib installieren

tar xzfz gwenhywfar-3.3.4.tar.gz
cd gwenhywfar-3.3.4
./configure
make
make install

AqBanking patchen und installieren

aqbanking-Lib installieren

tar xzfz aqbanking-3.99.5beta.tar.gz
cd aqbanking-3.99.5beta

Anzahl der Aufträge in einer Sammellastschrift setzen

in src/plugins/backends/aqhbci/plugin/accountjobs/jobmultitransfer_p.h
die Konstante AH_JOBMULTITRANSFER_MAXTRANS von 16 auf 999 ändern

endlich compilieren

./configure --disable-tutorials --disable-chipcard-client --with-frontends="" --with-backends="aqhbci"
make
make install

Danach kopieren der abtest.c-source (einfach die alte überschreiben) in das Verzeichnis /usr/src/aqbanking-3.2.1/src/test.

touch abtest.c
make abtest

Da unser Server ein 64bit-System ist, mussten wir vor dem Anlegen der Konten noch alle libaq*, alle libgwen* und die beiden gwenhywfar und aqbanking-verzeichnisse von usr/lib nach usr/lib64 kopieren.

Installation (REST)

dieser Schritt kann übersprungen werden, wenn man den aqbd Dienst nicht über als REST-Webservice ansprechen will (z.B. wenn man aqbd als Kommandozeilen-Tool verwenden will).

Apache2 anpassen

Damit PHP mit den REST-typischen Anfragen aus dem Web zurecht kommt, muss das "mod_rewrite" / "rewrite"-Modul zunächst aktiviert werden.
Ob das Modul schon aktiv ist kann durch die PHP-Info-Seite deines Apache2 angezeigt werden.
Wenn nicht hier die Anleitungs, wie man es aktiviert ...

/etc/sysconfig/apache2

In dieser Datei muss rewrite eingetragen werden!

APACHE_MODULES="actions ... rewrite ..."

Mit ...

SuSEconfig

muss die Konfiguration scharf geschaltet werden.

Im nächsten Schritt geht es darum REST-Anfragen aus dem Web so zu manipulieren dass PHP das alles ordentlich verstehen kann ...

/etc/apache2/mod_rewrite.conf

<IfModule mod_rewrite.c>
 
RewriteEngine   On
RewriteRule ^/aqb(.*) /aqb/index.php?rest=$1 [QSA,L]
 
</IfModule>

/etc/apache2/vhosts.d/aqb.conf

 <VirtualHost *>
   ServerName aqb.orgamon.net
   ServerAlias aqb.raib91
   DocumentRoot /srv/www/htdocs/aqb
 
   RewriteEngine on
   RewriteLog /var/log/apache2/rewrite_log
   RewriteLogLevel 9
 
   RewriteRule ^/(.*) /index.php?rest=$1 [QSA,L]
 
 </VirtualHost>

erster Test

http://~MeinServer~/saldo/~MeineBLZ~/~MeineKontoNr~/

Ergebnis

Betrag;Waehrung 2938,23;EUR

Konto - Deklaration

Vorbereitung, wir brauchen ...

BLZ
HBCI-URL (http://www.hbci-zka.de/institute/institut_auswahl.htm)
Kontonummer
Benutzerkennung
PIN

Benutzer anlegen

aqhbci-tool3 adduser -N Benutzerkennung -b BLZ -u Benutzerkennung -s HBCI-URL -t pintan

Konto anlegen

aqhbci-tool3 addaccount -b BLZ -c Benutzerkennung -a Kontonummer

ACHTUNG: Wenn was schiefging muss man in settings\account die entsprechenden Dateien löschen sonst gibt es "Ambigous account names" oder so ...

Systeme miteinander bekanntmachen

Ein notwendiger Schritt damit AqBanking genau speichern kann, was die Gegenstellen für Fähigkeiten und Vorlieben hat.

aqhbci-tool3 getsysid -b BLZ -c Benutzerkennung

Dieser Befehl gelingt nicht immer beim ersten Mal, es folgen 2 Tipps zur Problemlösung:

iTAN bereitstellen

aqhbci-tool3 getitanmodes -b BLZ

Sammellastschrift nutzbarmachen

~/.aqbanking/settings/users


data {
 backend {
       char tokenType="pintan"
       char userFlags="forceSsl3" # 1)
       int  selectedTanMethod="912"
       char userFlags="keepMultipleBlanks" # 2)
       int  tanMethodList="912"
       char multiJobAllowed="J" # 3)
       int hbciVersion="300" # 4)
  } #backend
} #data

kommt der Fehler "A TLS packet with unexpected length was received" muss man SSL3 (anstelle von SSL2) aktivieren.
Blank+Blank im Überweisungstext
mehrere Jobs per Anfrange aktivieren (hat aber glaube ich keine Bedeutung)
HBCI Version muss ggf. angepasst werden

~/.aqbanking/settings/accounts


data {
  backend {
    char accountFlags="preferSingleTransfer", "PreferSingleDebitNotes"
  } #backend
} #data

das Flag "PreferSingleDebitNotes" rausmachen

Zertifikat speichern

Wechsle ins Verzeichnis /srv/aqb
Führe eine erste Saldoabfrage durch

aqbd -S ~BLZ~ ~Konto#~ ~PIN~

Das Programm bricht mit einem Zertifikatsfehler ab
Umbenennen der frisch erstellten "cert.~BLZ~.~KTO~.tmp"-Datei nach "cert.~BLZ~.~KTO~.txt"

PIN dauerhaft speichern

Erstelle eine Datei "pin.~BLZ~.~KTO~.txt" in /srv/aqb. In ihr darf nur die PIN in einer Zeile enthalten sein, keine Kommentare oder Leerzeilen.

abschliessender Test und Diagnose

export AQHBCI_LOGLEVEL=debug

Anwendung als Kommandozeilen-Programm

Ausgabe bei ./aqbd --help

  aqbd -[U|L|B|S|D] BLZ KontoNummer PIN [Datum|"Pfad"]
  -U Ausgabe der Umsaetze in eine Datei
  -L Durchfuehren von Lastschriften
  -S Ausgabe von Salden
  -D werde selbst zum Dämon
  ### folgende Schalter sind im Beta Stadium ###
  -N Ausgabe der nicht gebuchten Umsätze (NOCH NICHT FEHLERFREI)
  -T Ausgabe der Terminüberweisungen (NOCH NICHT PROGRAMMIERT)
  -B Durchfuehren von Terminueberweisungen (NOCH NICHT PROGRAMMIERT)

Umsätze

Bedienung:

-U oder -u für umsatzabfrage

Danach kommen die Parameter
BLZ KTO PIN [Datum]
ohne - oder / oder ähnliches, nur durch whitespace getrennt

Die erfolgreich abgerufenen Umsätze werden in einer csv-Datei unter srv/aqb/results/JobName.Umsatz.csv abgelegt, und kann leicht weiterverarbeitet werden (z.B. mit OpenOffice). JobName ist bei Konsolenbedienung die niedrigste unbenutzte Zahl. Liegen die Dateien 1, 2, und 3 schon im Ordner, heißt die Datei 4.Umsatz.csv. Alle Dateien eines Jobs haben den gleichen JobNamen.

Name	Bedeutung	Beispiel
PosNum	vortlaufende Umsatznummer der aktuellen DATEI	1
Datum	Aktuelles Datum DD.MM.YYYY	30.06.2008
Valuta	Datum der Wertstellung	03.07.2008
Betrag	Betrag mit Dezimalkomma	33,50
Waehrung	Standard-Währungskürzel	EUR
Typ	Transaktionstyp (z.B.Scheck/Miscellaneous/Lastschrift)	NCHK/NMSC/NSTO
VorgangID	von der Bank gelieferte Numerische Entsprechung des VorgangsText, der intern übersetzt wird. (TextKey)	5
VorgangText	Vorgangsbeschreibung die sich aus der VirgangsID ergiebt.	Lastschrift
PrimaNota	Von der Bank übergebene PrimaNota-Nummer	850
VonBLZ	Bankleitzahl des Bankinstitutes der Gegenseite	66391600
VonKonto	Kontonummer der Gegenseite	10504104
VonREF	Dieses Feld hat in der Bankenwelt mehrere Bedeutungen: a) Bei Scheckeinreichungen die Dein Konto belasten wird hier die Scheck-Nummer eingetragen, bei sehr vielen Schecks, die man mit identischem Betrag draussen hat, ist diese Nummer sehr interessant, zumal "erfundene" Schecknummern (die nicht in deinem Scheck-Büchle (hoffentlich) aufnotiert sind ) hier sofort auffallen. (Oder Doppeleinreichungen) b) Bei Sammellastschriften steht hier die Anzahl der Buchungen, also "1", "2", usw. c) Bei Überweisungen die über eine Homebanking-Plattform steht hier immer eine "1", naja wird scheinbar intern als eine Art Sammelüberweisung mit nur einer Überweisung verbucht oder so ...	1
VonName1	Kontoinhaber der Gegenseite	Andreas Filsinger
VonName2	Selten genutzte zweite Namensspalte ebenfalls Kontoinhaber	Filsinger GmbH
Buchungstext1-Buchungstext7	Verwendungszweck. Maximal 27 Zeichen pro Zeile, Maximal 7 Zeilen	Ihr Einkauf bei Tante Emma

Beispiel

PosNo;Datum;Valuta;Betrag;Waehrung;Typ;VorgangID;VorgangText;PrimaNota;VonBLZ;VonKonto;VonREF;VonName1;VonName2;Buchungstext1;Buchungstext2;Buchungstext3;Buchungstext4;Buchungstext5;Buchungstext6;Buchungstext7
1;05.10.2009;05.10.2009;-3,00;EUR;NSTO;8;DAUERAUFTRAG;900;66061724;309xxxxx;;MUSTERMANN MAX   /DA:00001;;TASCHENGELD;;;;;;;
2;05.10.2009;05.10.2009;-79,07;EUR;NMSC;5;LASTSCHRIFT;931;30060010;1xxxxx;;ALDI SUED SAGT DANKE;;EC 65213439 02.10 18.24 CE1;02 3B0001 1212 080814 EUR01;6726611412000740219 2808911;;;;;

Lastschrift

Bedienung

-L oder -l für Lastschrift

Danach kommen die Paramter
BLZ KTO PIN "Pfad der CSV-Datei"
ebenfalls ohne sonderzeichen, nur durch whitespace getrennt

Die CSV-Datei ist Semikolon getrennt, und die Zeilenumbrüche sind mit \r\n ausgeführt. RID ist eine durchlaufende beliebige Nummer(Primary Key) und wird vom Parser ignoriert, ebenso wie Ort. Diese beiden Felder dürfen jedoch nicht weggelassen werden!!! Jede Zeile ist ein neuer Datensatz, und wird vom Programm als jeweils einzelne Lastschrift in eine Sammellastschrift verpackt und ausgeführt.

RID;Name;Ort;BLZ;Konto;Betrag;VZ1;VZ2;VZ3;VZ4
1;"MARTIN SCHMIDT";"";66391600;0002076616;0,25;"TESTABBUCHUNG8";"REV. 1.005";"";""

Nach der Jobverarbeitung wird die Lastschrift-CSV als JobName.csv In results bzw. error kopiert.

Salden

Bedienung:

-S oder -s für Saldo

Danach kommen die Parameter
BLZ KTO PIN
ohne - oder / oder ähnliches, nur durch whitespace getrennt

Das Ergebnis wird bei erfolgreicher Saldenabfrage als JobName.Saldo.csv in results gespeichert.

Betrag;Waehrung
1000000,00;EUR;

Anwendung als Dämon für den Serverbetrieb

Dämon (-D)

Es werden zwischen den verschiedenen Programmebenen Daten ausgetauscht, indem Files auf der Festplatte abgelegt werden. (Von der DBUS-Technologie sind wir abgekommen, schlicht und einfach wegen der enormen, und für unsere Zwecke zu hohen, komplexität der DBUS-Bibliothek.)

Job-Files

Wird abtest mit -d als Parameter gestartet befindet sich die Anwendung im "Deamon-Mode". Aufträge werden mit in sogenannten JobFiles in das jobs-verzeichnis geschrieben, und von abtest gelesen. Der Inhalt der Files ist identisch mit den in der Kommandozeile zu übergebenden Parameter(Benutzung).

-s 66091600 1234567

gespeichert als JobName.job im Unterverzeichnis jobs bzw. /srv/aqb/jobs

Der Name des Jobs wird für alle Dateien, die bei der Jobverarbeitung entstehen, benutzt. Sind die Jobs Abgearbeitet werden sie je nach erfolg zusammen mit den Ergebnisdaten bzw mit den Lastschrift-Daten im CSV-Format in den results-Ordner, oder in den error-Ordner verschoben. Uber jede Aktion werden Log-Dateien geschrieben (/logs/JobName.log.txt).

Tan-Übergabe

Die Tan wird ab Sommer 2008 im iTan-verfahren abgefragt, und ist damit nichtmehr frei wählbar. Die Aufforderung lautet dann in etwa: "Bitte die 17.TAN eingeben: ". Damit muss während eines Lastschriftverfahrens die Gegenseite gerufen werden. Dafür wird die Anforderung der Bank in einem File Gespeichert, und muss innerhalb von 20sec mit einem tanFile "beantwortet" werden.

Dazu legt aqbd nach start der Jobverarbeitung im Verzeichnis /srv/aqb/results/ eine Datei namens JobName.tan-anfrage.txt mit dem Anfragetext der Bank an, und wartet anschließend 20 Sekunden auf das Auftauchen der Datei JobName.tan unter /srv/aqb/jobs. Diese darf AUSSCHLIEßLICH die tan enthalten und wird nach Abschluss der Jobverarbeitung ebenfalls in error bzw. results kopiert.

PHP-Rest-Server

aqdb läuft im Daemon-Modus im Hintergrund, und wird sozusagen vom Restserver ferngesteuert. Das PHP-Skript erzeugt die Job-Files und prüft auf das Vorhandensein der Ergebnissdaten, und gibt diese aus.

Implementiert Anfragen an den Server

http://www.orga-mon.de/rest/Funktion/BLZ/KTO/datum

Funktionen:
./info/
./umsatz/
./saldo/
./lastschrift/
./itan/

Umsatz (./umsatz/)

Anfrage:

./UMSATZ/~BLZ~/~KONTO#~/2008-02-28?f=text

Antwort:

Mapping csv<->Aqbanking

       // Zuordnungen gefunden
       Buchungsdatum<->date
       Typ<->transactionKey (Beispiel: "NSTO","NMSC","NCHK")
       vonBLZ<->remoteBankCode
       vonKonto<->remoteAccountNumber
       vonName1..2<->remoteName
       ValutaDatum<->valutaDate
       Betrag<->value.value
       Waehrung<->value.currency
       VorgangID<->textKey
       VorgangText<->transactionText
       Primanota<->primanota
       Verwendungszweck1..7<->purpose

Sammellastschrift (./lastschrift)

Anfrage 1/2

POST ./lastschrift/~BLZ~/~Konto~

mit einem zeitgleichen http-Upload der DTA-Datei (Name spielt keine Rolle)!