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 >=5.0.0)
- ... liegt im C-Quelltext (GPL 3.0 Lizenz) vor
- ... bietet im Zusammenspiel mit Apache2+PHP einen RESTful Webservice an für /saldo, /umsatz, /lastschrift
- ... bietet somit 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. 4.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)
Abhängigkeiten
zypper install libgcrypt-devel zypper install gnutls-devel zypper install libktoblzcheck1-devel zypper install ktoblzcheck zypper install fox16-devel
Gwenhywfar installieren
Wir haben beide Packages (Gwen+AqB) in das Verzeichnis /usr/src entpackt. Versionsnummern sind heute natürlich schon weiter ...
- gwen-Lib installieren
tar xzfz gwenhywfar-4.0.0.tar.gz cd gwenhywfar-4.0.0 ./configure --with-guis=fox16 make make install
AqBanking installieren
tar xzfz aqbanking-5.0.0.tar.gz cd aqbanking-5.0.0 export PKG_CONFIG=`which pkg-config` ./configure --with-backends="aqhbci aqofxconnect" make make install
Danach kopieren der abtest.c-source (einfach die alte überschreiben) in das Verzeichnis /usr/src/aqbanking-n.n.n/src/test.
touch abtest.c make abtest
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/vhosts.d/aqb.conf
- Bevor man den virtuellen Host testet sollte die korrekte Namensauflösung überprüft werden. Also muss in diesem Fall ein
ping aqb.orgamon.com
auch den orgamon.com erreichen. Dies muss durch einen Wildcard-Eintrag im Nameserver erreicht werden "*.orgamon.com", bzw. "*.raib23" usw ...
<VirtualHost *:80> ServerName aqb.orgamon.com ServerAlias aqb.raib91 aqb.orgamon.de DocumentRoot /srv/www/htdocs/aqb RewriteEngine on RewriteLog /var/log/apache2/rewrite_log RewriteLogLevel 9 RewriteRule ^/rest/(.*) /index.php?rest=$1 [PT] </VirtualHost>
/srv/aqb/aqb.sh
Das startscript starten den dämon, der immer nach neuen Jobs lauscht.
# # AqBanking Daemon Start Script # # export AQHBCI_LOGLEVEL=debug killproc -v /usr/src/aqbanking-5.0.0/src/test/.libs/abtest rm /root/.aqbanking/settings/users/*.lck* mv /srv/aqb/jobs/* /srv/aqb/error logger "aqbd-Startup-Script ausgfuehrt!" startproc -v /usr/src/aqbanking-5.0.0/src/test/.libs/abtest -D #
erster Test "Info"
- die Anfrage
http://~MeinServer~/rest/info
- der Ergebnis-Header
Date Fri, 16 Oct 2009 16:10:13 GMT Server Apache/2.2.4 (Linux/SUSE) X-Powered-By PHP/5.2.11 Expires Mon, 26 Jul 1997 05:00:00 GMT Last-Modified Fri, 16 Oct 2009 16:10:13 GMT Cache-Control no-store, no-cache, must-revalidate, post-check=0, pre-check=0 Pragma no-cache Etag "182422" Content-Length 96 Keep-Alive timeout=15, max=100 Connection Keep-Alive Content-Type text/plain
am Ergebnis-Header ist vor allem der "ETag" interessant. Die ist die Transaktions-Nummer, die das phpREST mit dem aqbd ausgehandelt hat. Über diese TAN können auch Logs zur aktuellen Anfragen abgefragt werden:
http://~MeinServer~/rest/log/182422
- das Ergebnis
Modul;Version aqbanking;4.1.0.0stable gwenhywfar;3.9.0stable-0 abtest;1.029 aqb-REST;1.029
erster Test "Saldo"
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)
- Benutzerkennung für den Login
- Name des Kontoinhabers für die Identifikation bei Lastschriften
- Kontonummer
- PIN Passwort
Benutzer anlegen
aqhbci-tool4 adduser -N Name -b BLZ -u Benutzerkennung -s HBCI-URL -t pintan aqhbci-tool4 adduserflags -c Benutzerkennung -f keepMultipleBlanks
Systeme miteinander bekanntmachen
- Ein notwendiger Schritt damit AqBanking genau speichern kann, was die Gegenstellen für Fähigkeiten und Vorlieben hat.
aqhbci-tool4 getsysid -b BLZ -c Benutzerkennung
- Dieser Befehl gelingt nicht immer beim ersten Mal, um zu prüfen, dass alle Konten angelegt wurden:
aqhbci-tool4 listaccounts | grep BLZ
Konten prüfen / anlegen
Ist das gewünschte Konto nicht dabei hat beim oberen
aqhbci-tool4 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 ...
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.
(TransactionCode) |
5 |
VorgangText | Vorgangsbeschreibung die sich aus der VorgangsID ergibt. (TransactionText) | 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) |
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 (./sammellastschrift)
Buchungsvolumen übertragen
POST ./sammellastschrift/~BLZ~/~Konto~ [DTA-Attachement]
mit einem zeitgleichen http-Upload der DTA-Datei (Name spielt keine Rolle)!
Antwort:
- die Antwort ist, sobald die DTA-Datei fehlt ein kleines Upload-Formular, mit dem man die Anfrage (diesmal mit Datei) wiederholen kann.
- die Antwort ist der JobID, unter dem die Sammellastschrift abgearbeitet wird. Diese JobID ist zwischenzuspeichern, damit man die Folgenden Schritte "meldung" und "itan" abwickeln kann.
Fragetext der Bank
GET ./meldung/~JobID~
Antwort:
Entweder:
INFO: [NA] Bisher keine Rückmeldung der Bank.\r\n
in diesem Fall muss die Anfrage in einigen Sekunden wiederholt werden!
Oder:
- ansonsten ist die Antwort eine Text der Bank, die Informationen zur TAN-Eingabe enthält:
Nun bitte die 34. TAN eingeben
(i)TAN übertragen
Nun erfolgt die TAN-Übergabe an die Bank und die tatsächliche Durchführung. War die Ausführung erfolgreich, so erscheint ein einfaches "OK".
GET ./itan/~JobID~/~TAN~
Kontostand (./saldo)
Termin-Überweisung
-- noch kein Bedarf --
Historisches
Erreichte Meilensteine
- Linux-Anwendungsebene: QBankingManager installieren (Erfolg: 21.02.2008)
- ein Giro-Konto abfragen um zu sehen, ob das Teil funktioniert (Erfolg: 21.02.2008)
- Transaktion "Konto-Umsatz-Abfrage" ausprobieren! (Erfolg: 21.02.2008)
- Transaktion "Sammel-Lastschrift" (DTA) ausprobieren! (Geht nicht! Nur Einzeln)
- Linux-Programmierebene: "aqbanking 3" versuchen zu compilieren (Erfolg: 19.02.2008)
- Mini-Programm Konsolen-Programm erstellen das z.B. die Kontenliste auf den Schirm bringt (Erfolg: 22.02.2008)
- AH_Job_GetBalance ("~kto~.~blz~") : double (Erfolg: 26.03.08)
- AH_Job_GetTransactions ("~kto~.~blz~","20.02.2008") : (Erfolg: 28.02.2008)
- AH_Job_MultiDebitNode_new (Achtung schwierig: "Multi-Job" + "TAN" notwendig + DTAUS Importer verwenden!) (07.03.2008)
- Erfolgreiche erzeugung eines DebitNote-Auftrags aus Kommandozeilenparametern und csv-Datei (07.03.2008)
- Erfolgreiche auftragsübertragung bis zur TAN-Abfrage über den Passwort-Callback!! (05.03.2008)
- Erfolgreiche Lastschriften mit einer einzelnen, sowie mit 2 Lastschriften in einer Sammellastchrift. (07.03.2008)
- REST - Server in PHP verwirklicht, Technologie: mod_rewrite und "$fn();" (13.03.2008)
- REST - Mappings definieren auf ein nun fertiges "aqbc"-Programm das in C programmiert ist. (13.03.2008)
- REST: Lastschriften (15.03.2008)
- Umlaute (scheinbar durchgängig UTF-8, wär ja OK!) (19.03.2008)
- Integration in den OrgaMon 1/2 "Umsatz" (20.03.2008)
- Integration in den OrgaMon 2/2 "Sammellastschrift" (26.03.2008)
- aqbd TimeOut-Problem bei den Lastschriften (Erfolg mit AqBanking 3.5.0)
- Sammellastschrift mit iTAN (Erfolg mit AqBanking 3.5.0)
- Eingang aller meiner Patches (Erfolg mit AqBanking 3.99)
Offen
- aqbd nun als richtiges / eigentständiges Linux Projekt beginnen und Know-How aus abtest übernehmen (Info: http://www.openismus.com/documents/linux/automake/automake.shtml)
- Sammellastschrift mit 2000 Posten durchführen (Massentest!)
Sicherheitsüberlegungen
- Während der Installtionsphase sollte der Webserver nur für den Admin sichbar sein, bis alles funktioniert
- Dann sollten "pin."-Dateien nur "root" sichtbar gemacht werden
- Überlegungen sollten den Rechten der Verzeichnisse ab /srv/aqb gewidmet werden
- Das Wurzelverzeichnis des REST Servers (index.php) sollte passwortgeschützt werden
- Wird der REST Server im Internet sichtbar sollte https:// (SSL-Verschlüsselung) auf das Verzeichnis gelegt werden
- Die PIN eines Kontos wird design-bedingt niemals über das Netz übertragen
- Der (HBCI-Server-)Login-Name wird design-bedingt niemals über das Netz übertragen
- Von aussen - ohne manuellen Eingriff des admin - können keine veränderte Zertifikate akzeptiert werden. Somit ist ausgeschlossen dass die Übernahme des Netzes rund um den aqbd-Host zum Stehlen von PIN / TAN führen kann
Links
- Homepage: http://www.aquamaniac.de/sites/aqbanking/index.php
- Developement-Snapshot-aqbanking: http://devel.aqbanking.de/viewsvn/aqbanking
- Mailing-List: http://sourceforge.net/mailarchive/forum.php?forum_name=aqbanking-devel