|
|
|
Content
|
|
=======
|
|
|
|
1. What Is AqBanking ?
|
|
1.1. Generic Online Banking Interface
|
|
1.2. Generic Financial Data Importer/Exporter Framework
|
|
1.3. Bank/Account Information
|
|
2. Supported Platforms
|
|
3. Supported Backends
|
|
3.1. HBCI
|
|
3.2. OFX Direct Connect
|
|
3.3. EBICS
|
|
3.4. Paypal
|
|
3.5. None
|
|
4. What Do I Need ?
|
|
4.1. Required Packages
|
|
4.2. Applications
|
|
5. Building AqBanking
|
|
5.1. Building from the Tar File
|
|
5.2. Building from CVS/SVN
|
|
5.3. Building the API Documentation
|
|
6. Windows Registry Keys Used
|
|
6.1. Software\\AqBanking\\Paths\\pkgdatadir
|
|
6.2. Software\\AqBanking\\Paths\\sysconfdir
|
|
6.3. Software\\AqBanking\\Paths\\bankinfodir
|
|
6.4. Software\\AqBanking\\Paths\\providerdir
|
|
6.5. Software\\AqBanking\\Paths\\importerdir
|
|
7. Environment Variables Used
|
|
7.1. AQBANKING_LOGLEVEL
|
|
7.2. AQBANKING_STORE_JOBLOGS
|
|
7.3. AQHBCI_LOGBOOKED
|
|
7.4. AQHBCI_LOGNOTED
|
|
7.5. AQHBCI_DEBUG_JOBS
|
|
7.6. AQOFX_LOG_COMM
|
|
8 . Using Your Own Profiles for Im-/Exporters
|
|
9. Thanks
|
|
|
|
|
|
|
|
1. What Is AqBanking ?
|
|
======================
|
|
|
|
AqBanking is a library for online banking and financial
|
|
applications. It has three major goals which are described in the
|
|
following paragraphs.
|
|
|
|
(Note: Information in German can be found on
|
|
http://linuxwiki.de/AqBanking )
|
|
|
|
The homepage of AqBanking is http://www.aqbanking.de/
|
|
|
|
|
|
1.1. Generic Online Banking Interface
|
|
-------------------------------------
|
|
|
|
The intention of AqBanking is to provide a middle layer between the program
|
|
and the various Online Banking libraries (e.g. AqHBCI, OpenHBCI etc).
|
|
|
|
The real work is done in so-called banking backends. See chapter 3 for a
|
|
list of supported backends.
|
|
|
|
|
|
|
|
1.2. Generic Financial Data Importer/Exporter Framework
|
|
-------------------------------------------------------
|
|
|
|
AqBanking uses various plugins to simplify import and export of financial
|
|
data. It also provides the administration of profiles on a per import/export
|
|
plugin basis.
|
|
|
|
Currently there are plugins for the following formats:
|
|
|
|
- Importers:
|
|
- DTAUS (German financial format)
|
|
- SWIFT (MT940 and MT942)
|
|
- OFX
|
|
- CSV
|
|
- OpenHBCI1 transactions
|
|
- ERI
|
|
- Q43
|
|
|
|
- Exporters
|
|
- DTAUS (German financial format)
|
|
- CSV
|
|
|
|
|
|
1.3. Bank/Account Information
|
|
-----------------------------
|
|
|
|
AqBanking supports plugins which allow lookup and verification of
|
|
bank code/ account id pair validity. For Germany the library
|
|
KtoBlzCheck is used for validation, but the bank information is
|
|
shipped with aqbanking.
|
|
|
|
Currently AqBanking provides informations about:
|
|
- ca 25,000 US banks
|
|
- ca 20,000 German banks
|
|
- ca 3,600 Swiss banks
|
|
- ca 2,300 Austrian banks
|
|
|
|
AqBanking also provides information about countries: Country name, ISO-3166
|
|
country code (both numeric and alpha) and currency information (ISO 4217
|
|
currency codes).
|
|
|
|
|
|
|
|
2. Supported Platforms
|
|
======================
|
|
|
|
AqBanking uses the library Gwenhywfar (http://www.aqbanking.de/) for
|
|
abstraction of the underlying system. So it should work on any system for
|
|
which Gwenhywfar is available.
|
|
|
|
This includes (but is not limited to):
|
|
- Linux (of course ;-)
|
|
- Windows (WIN32 platforms, such as Windows95 up to Windows XP)
|
|
- MacOSX 10.5 and newer
|
|
- most POSIX systems (such as the BSDs) should also be supported,
|
|
however, this is untested
|
|
|
|
|
|
|
|
3. Supported Backends
|
|
=====================
|
|
|
|
AqBanking includes all its currently known banking backends.
|
|
|
|
|
|
3.1. HBCI
|
|
---------
|
|
|
|
The backend AqHBCI provides support for the German online banking protocol
|
|
called "Homebanking Computer Interface". It is a national standard provided
|
|
by most German credit institutes.
|
|
|
|
The following security media are supported:
|
|
- DDV chipcard (DES-DES-Verfahren)
|
|
- RSA chipcard (RSA-DES-Hybrid mode)
|
|
- OpenHBCI keyfile (either OpenHBCI 1 or 2, this medium allows continued use
|
|
with OpenHBCI in parallel)
|
|
- PIN/TAN (PIN/TAN mode using HTTP over SSL)
|
|
|
|
This backend supports the HBCI versions 2.01, 2.10, 2.20 and 3.00
|
|
|
|
|
|
3.2. OFX Direct Connect
|
|
-----------------------
|
|
|
|
This backend provides support for an online banking protocol used in the
|
|
United States, Canada and maybe in the United Kingdom.
|
|
|
|
|
|
3.3. EBICS
|
|
----------
|
|
|
|
EBICS is the successor of the German banking protocol FTAM. It is used in commercial
|
|
environments. The tool AqBanking-CLI comes with optional support for this protocol.
|
|
|
|
|
|
3.4. Paypal
|
|
-----------
|
|
|
|
This backend uses Paypal's native API for retrieving transactions.
|
|
|
|
|
|
3.5. None
|
|
---------
|
|
|
|
This is a fallback module which can be used by applications for accounts which
|
|
are not managed by any online banking backend.
|
|
|
|
|
|
|
|
4. What Do I Need ?
|
|
===================
|
|
|
|
|
|
4.1. Required Packages
|
|
----------------------
|
|
|
|
AqBanking has several direct dependencies:
|
|
|
|
- "Gwenhywfar" >= 3.99.0, available from
|
|
http://gwenhywfar.sf.net/, is absolutely required
|
|
|
|
- "GMP", the GNU MP Bignum Library available from
|
|
http://gmplib.org/index.html is required for calculations
|
|
|
|
- "KtoBlzCheck" >= 1.0 from http://sf.net/projects/ktoblzcheck is
|
|
required for the German bank account number checking, otherwise
|
|
the account number checking will not be compiled.
|
|
|
|
- The python module "ctypes" http://sf.net/projects/ctypes is
|
|
required for the python wrappers of aqbanking. The python wrappers
|
|
are installed by default (to disable it, use --disable-python),
|
|
but they cannot be used unless "ctypes" is installed.
|
|
|
|
|
|
4.2. Applications
|
|
-----------------
|
|
|
|
These applications fully or partially support AqBanking:
|
|
- AqFinance (http://www2.aquamaniac.de/sites/aqfinance/index.php)
|
|
- QBankManager (http://www.aquamaniac.de/qbanking/, discontinued)
|
|
- Gnucash (http://www.gnucash.org/)
|
|
- KMyMoney (http://kmymoney2.sf.net/)
|
|
- OrgaMon (http://orgamon.org/)
|
|
- Pecunia 0.2 (http://www.pecuniabanking.de/Pecunia/Home.html)
|
|
|
|
The aqbanking package also includes several command-line tools
|
|
(aqbanking-tool, aqhbci-tool).
|
|
|
|
|
|
|
|
5. Building AqBanking
|
|
=====================
|
|
|
|
|
|
5.1. Building from the Tar File
|
|
-------------------------------
|
|
|
|
#>./configure
|
|
#>make
|
|
#>make install
|
|
|
|
(the last step most probably requires you to be root)
|
|
|
|
Compilation hints for specific platforms:
|
|
|
|
- For FreeBSD and potentially other non-Linux platform, it might be
|
|
necessary to use "gmake" instead of the "make" program.
|
|
|
|
- Also, if your "make" program happens to complain about the variable
|
|
definition "I18NFILES = $(shell cat ..." (in Makefile.in around line
|
|
230) and related definitions, then you need to look for comments in
|
|
the Makefile about "old make programs". Follow the instructions in
|
|
these comments, i.e. set some variable definitions to an empty
|
|
variable manually. This should remove all potentially incompatible
|
|
directives from the Makefile.
|
|
|
|
- (especially on Mac/Darwin): If your configure run does not
|
|
detect the QT libraries and it says "checking for qt3
|
|
libraries... not found", then you need to specify the linker
|
|
flags for qt3 manually in the env variable qt3_libs. I.e. if
|
|
your qt3 library files are in /opt/qt/lib and is called
|
|
libqt-mt, then you need to specify
|
|
./configure qt3_libs="-L/opt/qt/lib -lqt-mt"
|
|
|
|
|
|
5.2. Building from CVS/SVN
|
|
--------------------------
|
|
|
|
#>make -fMakefile.cvs
|
|
|
|
and continue as described in "6.1. Building from the Tar File".
|
|
|
|
|
|
5.3. Building the API Documentation
|
|
-----------------------------------
|
|
|
|
#>make srcdoc
|
|
|
|
If you want to install a linked API documentation (which links against the
|
|
API documentations of the projects AqBanking depends on) use this:
|
|
|
|
#>make install-srcdoc
|
|
|
|
This installs the linked doc to the path you gave to ./configure
|
|
by "--with-docpath=PATH". It defaults to "$HOME/apidoc", which
|
|
means it does *not* obey the --prefix argument.
|
|
|
|
|
|
|
|
6. Windows Registry Keys Used
|
|
=============================
|
|
|
|
Some AqBanking versions might use registry keys below HKEY_CURRENT_USER.
|
|
These are at the moment only versions shipped with GnuCash (at least that
|
|
used to be the case which is why handling of registry keys was introduced
|
|
in the first place). Most versions of AqBanking don't use the registry
|
|
to determine installation paths because those versions are filesystem
|
|
relocatable, so they don't need the registry.
|
|
|
|
At any rate, those version that still do use the registry use the
|
|
following keys. These keys are created by the setup.exe which
|
|
contains the binary package for WIN32 platforms.
|
|
|
|
|
|
6.1. Software\\AqBanking\\Paths\\pkgdatadir
|
|
-------------------------------------------
|
|
This is the data folder (i.e. $PREFIX/share/aqbanking on POSIX systems).
|
|
|
|
|
|
6.2. Software\\AqBanking\\Paths\\sysconfdir
|
|
-------------------------------------------
|
|
This is the folder containing system configuration files.
|
|
(i.e. $PREFIX/etc on POSIX systems).
|
|
|
|
|
|
6.3. Software\\AqBanking\\Paths\\bankinfodir
|
|
-------------------------------------------
|
|
This folder is used to store bankinfo plugins.
|
|
|
|
|
|
6.4. Software\\AqBanking\\Paths\\providerdir
|
|
-------------------------------------------
|
|
This folder is used to store provider (backend) plugins.
|
|
|
|
|
|
6.5. Software\\AqBanking\\Paths\\importerdir
|
|
-------------------------------------------
|
|
This folder is used to store importer/exporter plugins.
|
|
|
|
|
|
|
|
7. Environment Variables Used
|
|
=============================
|
|
|
|
|
|
7.1. AQBANKING_LOGLEVEL
|
|
-----------------------
|
|
|
|
This variable stores the loglevel to be used for AqBanking.
|
|
Possible values are: emergency, alert, critical, error, warning, notice,
|
|
info, debug and verbous.
|
|
|
|
|
|
7.2. AQBANKING_STORE_JOBLOGS
|
|
----------------------------
|
|
If this variable is defined then AqBanking will always store job logs with
|
|
jobs. Otherwise job logs are only stored for jobs with a status other than
|
|
"finished". Job logs can become quite big.
|
|
|
|
|
|
7.3. AQHBCI_LOGBOOKED
|
|
---------------------
|
|
If this environment variable exists then the file "/tmp/booked.mt" is created
|
|
upon reception of transactions via the job GetTransactions. This file then
|
|
contains a SWIFT MT940 document which can be very helpfull in case there is
|
|
a problem in the SWIFT parser.
|
|
|
|
|
|
7.4. AQHBCI_LOGNOTED
|
|
--------------------
|
|
Same as AQHBCI_LOGBOOKED but for noted transactions (which are transactions
|
|
which are noted but ot yet booked)
|
|
|
|
|
|
7.5. AQHBCI_DEBUG_JOBS
|
|
----------------------
|
|
If this variable exists then additional debugging data is stored with each
|
|
job.
|
|
|
|
|
|
7.6. AQOFX_LOG_COMM
|
|
-------------------
|
|
If this variable exists then all OFX communication is logged to /tmp/ofx.log.
|
|
This is only needed when debugging AqOfxConnect.
|
|
WARNING: This might expose your user id and password to everyone who can read
|
|
that file!
|
|
|
|
|
|
|
|
|
|
8. Using Your Own Profiles for Im-/Exporters
|
|
============================================
|
|
|
|
You can create your own profiles to be used with the various importers.
|
|
For AqBanking to recognize your private profiles they must be stored in
|
|
the user local folder.
|
|
E.g. CSV profiles on Linux must be stored in
|
|
"$HOME/.aqbanking/imexporters/csv/profiles/".
|
|
|
|
|
|
|
|
9. Thanks
|
|
==========
|
|
|
|
I wish to thank the following (among others) people for their support in
|
|
making AqBanking work:
|
|
- Christian Stimming (build-system and tarball cleanup, translations, inputs)
|
|
- Jens Koerner (did some huge jobs to provide German translation)
|
|
- David Reiser (for helping in debugging the OFX DirectConnect code)
|
|
- Christoph Bohl (for helping with the YellowNet backend)
|
|
|
|
- and of course the many people who submitted bug reports !!
|
|
|
|
|
|
Martin Preuss, Hamburg/Germany, 2010/08/26
|
|
|