GnuCash account API (vs. online banking)
Christian Stimming
stimming@tuhh.de
Sun, 12 Aug 2001 16:43:20 +0200
-----BEGIN PGP SIGNED MESSAGE-----
This is a rough description on how GnuCash accesses its account structures.
The German online banking coders (for the HBCI standard) have asked for it,
and I'm CC'ing that to gnucash-devel so that you can correct any errors. Note
that I ignored all multi-currency-related data fields to simplify the
discussion.
[HBCI list, please write your answers in english here.]
The GnuCash internal accounting engine is built upon three data structures:
Splits (German: "Buchungen"), Transactions ("Geschäftsvorgänge"), and
Accounts ("Konten"). From the info pages gnucash-design.info:
*Splits* or "Ledger Entries" are the fundamental accounting units. Each
Split consists of a quantity (number of dollar bills, number of shares,
etc.), [...] a pointer to the parent Transaction, a pointer to the debited
Account, [...] and a key-value frame [a datastructure which can store
arbitrary data, see the related info pages for details].
*Transactions* embody the notion of "double entry" accounting ("Doppelte
Buchführung"). A Transaction consists of a date, a description, [...] a list
of one or more Splits, and a key-value frame. When double-entry rules are
enforced, the total value of the splits is zero. [...] If there are two
splits, then the value of one must be positive, the other negative: this
denotes that one account is debited, and another is credited by an equal
amount. Positive Split values are 'debits' ("Belastung, Soll, Debit") and
negative Split values are 'credits' ("Gutschrift, Haben, Kredit"). Ensuring
the Splits to 'add up' to zero causes a double-entry accounting system to
always balance. [...]
Every Split must point to its parent Transaction, and that
Transaction must in turn include that Split in the Transaction's list
of Splits. A Split can belong to at most one Transaction. [...]
Splits are grouped into *Accounts* which are also known as "Ledgers"
("Buchungsbericht") in accounting practice. Each Account consists of a
list of Splits that debit that Account. To ensure consistency, if a Split
points to an Account, then the Account must point to the Split, and
vice-versa. A Split can belong to at most one Account. Besides merely
containing a list of Splits, the Account structure also give the Account a
name, [...] description and notes fields, a key-value frame, and a currency.
[...]
[End quote]
To create a new transaction from, say, account a1 to account a2, one would do
something like the following [Note: The `xacc' prefix is a historical
artifact. GnuCash was derived from X-Accountant by Robin Clark.]
Account *account1;
Account *account2;
/* do something to let account1 and account2 point to the actual accounts */
Transaction * trans = xaccMallocTransaction ();
Split * split1 = xaccMallocSplit();
Split * split2 = xaccMallocSplit();
xaccSplitSetAmount(split1, 47.11);
xaccSplitSetAmount(split2, -47.11);
/* ok, in actual GnuCash we don't use doubles here, so that's just a gross
simplification. */
xaccTransBeginEdit (trans);
xaccTransAppendSplit (trans, split1);
xaccTransAppendSplit (trans, split2);
xaccTransSetDescription (trans, "Some Descriptive Text");
xaccTransCommitEdit (trans);
xaccAccountInsertSplit (account1, split1);
xaccAccountInsertSplit (account2, split2);
/* Done. */
That's how GnuCash uses accounts. Now we can continue the discussion on how
an online banking API should look like.
Christian Stimming
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.5 (GNU/Linux)
Comment: For info see http://www.gnupg.org
iQCVAwUBO3aWDmXAi+BfhivFAQExMgP/dL/04/C9D9/4iKONYES1CcdByT6sSXtG
thsUUd+XPwNDskrpCmoVgtkn9HrG27NggZP6fy2yL5c/57uVqXKKQljpgMyKDj/d
JQvqDoyFWcfUX3gfcfd4NBJ0rysNNyZIpgsGG3Se1L0sWbDQINq2AZ2c981+D/g/
cuKc7UkCQgM=
=nWJV
-----END PGP SIGNATURE-----