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-----