forked from aqbanking/aqbanking
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
496 lines (347 loc) · 17.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
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 GIT
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
10. Translation
11. Changes from AqBanking 5.x to 6.x
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
https://linuxwiki.de/AqBanking )
The homepage of AqBanking is https://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
- XML (various formats like SEPA-PAIN, CAMT, OFX)
- Exporters
- DTAUS (German financial format)
- CSV
- XML (various formats like SEPA-PAIN, CAMT, OFX)
1.3. Bank/Account Information
-----------------------------
AqBanking supports plugins which allow lookup of
bank code/ account id pair validity.
Currently AqBanking provides informations about:
- ca 20,000 German banks
2. Supported Platforms
======================
AqBanking uses the library Gwenhywfar (https://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
https://www.aqbanking.de/, is absolutely required
- "GMP", the GNU MP Bignum Library available from
https://gmplib.org/index.html is required for calculations
4.2. Applications
-----------------
These applications fully or partially support AqBanking:
- AqFinance (https://www2.aquamaniac.de/sites/aqfinance/index.php)
- Gnucash (https://www.gnucash.org/)
- KMyMoney (https://www.kmymoney.org/)
- OrgaMon (https://www.orgamon.org/)
- Pecunia 0.2 (https://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 GIT
----------------------
#> make -fMakefile.cvs
#> ./configure
#> make typedefs
#> make types
and continue as described in "5.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.
5.4. Building using gwbuild
---------------------------
Download the git version or a tarball of AqBanking. Create a folder "build" somewhere (e.g. completely outside
the source tree or in its main folder), change into that "build" folder and perform the following steps:
#> gwbuild -s PATH_TO_SOURCE_TREE
#> gwbuild -p
#> gwbuild -B tm2builder
#> gwbuild
The last two steps accept the argument "-j XX" which lets you specify the number of parallel build processes
to use.
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 versions 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. Each following log level includes the previous
one.
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 not 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 !!
10. Translation
===============
To work on translation of this project you need the following packages on
Debian based systems:
- po4edit
- translate-toolkit (for "msghack")
You can then create the necessary files with:
- make catalogs
- make merge
This will create the necessary *.pot and *.po files, the latter should then be
translated.
11. Changes from AqBanking 5.x to 6.x
======================================
These are the major changes which need to be followed by applications when using
AqBanking6:
- AB_TRANSACTION:
- remoteName: - changed type from GWEN_STRINGLIST to simple char*
- purpose: - changed type from GWEN_STRINGLIST to simple char* (lines separated by "\n")
- date: - changed type from GWEN_TIME to GWEN_DATE
- valutaDate: - changed type from GWEN_TIME to GWEN_DATE
- firstExecutionDate: - renamed to firstDate (used in a more generic way)
- lastExecutionDate: - renamed to lastDate (used in a more generic way)
- unitPrice: - renamed to unitPriceValue (because there is also unitPriceDate)
- commission: - renamed to commissionValue
- sequenceType: - renamed to sequence
- addPurpose(): - changed to addPurposeLine()
- addRemoteName(): - removed -> use AB_Transaction_SetRemoteName()
- AB_TRANSACTION_LIMITS
- valuesTextKey: - removed
- maxLinesRemoteName: - removed
- valuesCycleMonth: - changed type from GWEN_STRINGLIST to array of uint8_t
- valuesExecutionDayMonth: - changed type from GWEN_STRINGLIST to array of uint8_t
- valuesCycleWeek: - changed type from GWEN_STRINGLIST to array of uint8_t
- valuesExecutionDayWeek: - changed type from GWEN_STRINGLIST to array of uint8_t
- AB_TRANSACTION_TYPE
- euTransfer: - removed
- AB_TRANSACTION_SEQUENCETYPE: - renamed to AB_TRANSACTION_SEQUENCE
- AB_JobGetTransactions:
- setFromTime(): - renamed to setFromDate(), changed arg type from GWEN_TIME to GWEN_DATE
- setToTime(): - renamed to setToDate(), changed arg type from GWEN_TIME to GWEN_DATE
- AB_IMEXPORTER_CONTEXT:
- AB_IMEXPORTER_ACCOUNTINFO: - all kind of transactions are now in a single AB_TRANSACTION_LIST, removing
the previously dedicated lists for notedTransactions, transfers, debitNotes etc.
You can now distinguish the type of transaction by inspecting the field
"type" of AB_TRANSACTION.
Normally only one type of transaction is in use at any time anyway, e.g. when sending
debit note requests the AB_IMEXPORTER_CONTEXT will only contain debitNotes anyway.
- changed list traversal methods.
Previously you would iterate through the list of transactions like this:
-------------------------------------------------------------------------X8
t=AB_ImExporterAccountInfo_GetFirstTransaction(iea);
...
t=AB_ImExporterAccountInfo_GetNextTransaction(iea);
-------------------------------------------------------------------------X8
This made it necessary to hold internal pointers to keep track of the last transaction
returned.
Since AqBanking6 only the lists are stored inside a AB_IMEXPORTER_ACCOUNTINFO.
You can now freely iterate through a transaction list like this:
-------------------------------------------------------------------------X8
t=AB_ImExporterAccountInfo_GetFirstTransaction(iea);
...
t=AB_Transaction_List_Next(t);
...
t=AB_Transaction_List_Previous(t);
-------------------------------------------------------------------------X8
So you can now use all list functions on the lists stored.
This is true for all list handled by a AB_IMEXPORTER_CONTEXT and AB_IMEXPORTER_ACCOUNTINFO,
especially:
- list of account infos objects (AB_IMEXPORTER_ACCOUNTINFO)
- list of transactions
- list of account status
- list of messages
- list of electronic banking statements
- AB_JOB: - removed (now taken over by AB_TRANSACTION)
- AB_BANKING: - removed handling of AB_USER and AB_ACCOUNT completely, introduced AB_ACCOUNT_SPEC:
- added AB_Banking_GetAccountSpecList()
- added AB_Banking_GetAccountSpecByUniqueId()
- replaced AB_Banking_ExecuteJobs() with AB_Banking_SendCommands()
- this function takes a list of jobs in AB_TRANSACTIONs and sends them, no longer needs AB_JOB
- AB_COUNTRY: - deprecated, will be removed before release
- AB_IMEXPORTER: - removed (functions now in AB_Banking)
- Includes: - some header files have been moved to subfolders (e.g. aqbanking/value.h -> aqbanking/types/value.h>)
If your compiler complains about missing headers try "aqbanking/types/" instead of "aqbanking".
Martin Preuss, Hamburg/Germany, 2021/02/19