finan : Financial vouchers

This document describes the lino_xl.lib.finan plugin, which introduces concepts like financial voucher and booking suggestion.

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.apc.settings.doctests')
>>> from lino.api.doctest import *
>>> ses = rt.login("robin")
>>> translation.activate('en')

This document is based on the following other specifications:

Vocabulary

There are three kinds of financial vouchers:

bank statement

A ledger voucher received from your bank and which reports the transactions that occurred on a given bank account during a given period.

See Bank statements.

payment order

A voucher you send to your bank asking them to execute a series of payments (outgoing transactions) to third-party partners from a given bank account.

See Payment orders.

journal entry

A voucher where you declare that you move money around internally, for your own accounting.

French: "operations diverse".

See Journal entries.

financial voucher

General term for the voucher types bank statement, payment order and journal entry. They have certain things in common, but use different database models because certain things differ.

expected movement

A ledger movement that did not yet happen but is expected to happen. For example the payment of an invoice.

booking suggestion

A suggestion to add an expected movement to a financial voucher. See Booking suggestions.

Payment orders

To configure a journal of payment orders, you set the following fields:

  • voucher_type should be lino_xl.lib.ledger.VoucherTypes.bank_po

  • partner ("Organization") should point to your bank.

  • dc (Primary booking direction) should be DEBIT because each item should debit (not credit) the partner's account.

  • account should be the ledger account marked as CommonAccounts.pending_po.

A payment order clears the invoices it asks to pay. Which means for example that a supplier might tell you that some invoice isn't yet paid, although your MovementsByPartner says that it is paid. The explanation for this difference is simply that the payment order hasn't yet been executed by your or their bank.

Lino books the sum of a payment order into a single counter-movement that will debit your bank's partner account (specified in the partner of the journal). Your bank becomes a creditor (you owe them the sum of the payments) and you expect this amount to be cleared by an expense in a bank statement which confirms that the bank executed your payment order.

>>> rt.show("finan.PaymentOrdersByJournal", ledger.Journal.get_by_ref("PMO"))
===================== ============ =========== =============== ================ =================== ================
 No.                   Entry date   Narration   Total           Execution date   Accounting period   Workflow
--------------------- ------------ ----------- --------------- ---------------- ------------------- ----------------
 2/2015                13/02/2015               6 801,22                         2015-02             **Registered**
 1/2015                13/01/2015               5 626,48                         2015-01             **Registered**
 12/2014               13/12/2014               5 878,16                         2014-12             **Registered**
 11/2014               13/11/2014               6 124,29                         2014-11             **Registered**
 10/2014               13/10/2014               5 877,47                         2014-10             **Registered**
 9/2014                13/09/2014               6 228,18                         2014-09             **Registered**
 8/2014                13/08/2014               5 707,66                         2014-08             **Registered**
 7/2014                13/07/2014               5 944,37                         2014-07             **Registered**
 6/2014                13/06/2014               6 112,07                         2014-06             **Registered**
 5/2014                13/05/2014               6 350,89                         2014-05             **Registered**
 4/2014                13/04/2014               7 061,63                         2014-04             **Registered**
 3/2014                13/03/2014               5 570,88                         2014-03             **Registered**
 2/2014                13/02/2014               5 570,38                         2014-02             **Registered**
 1/2014                13/01/2014               6 793,62                         2014-01             **Registered**
 **Total (14 rows)**                            **85 647,30**
===================== ============ =========== =============== ================ =================== ================
class lino_xl.lib.finan.PaymentOrder

Django model to represent a payment order.

entry_date

The date of the ledger entry.

execution_date

The execution date of payment order. If this is empty, Lino assumes the entry_date when writing the pain_001.xml file.

total

The total amount. This is automatically computed when you register de voucher.

class lino_xl.lib.finan.PaymentOrderItem

Django model to represent an individual item of a payment order.

class lino_xl.lib.finan.PaymentOrders

The base table of all tables on PaymentOrder.

class lino_xl.lib.finan.ItemsByPaymentOrder

Bank statements

>>> rt.show("finan.BankStatementsByJournal", ledger.Journal.get_by_ref("BNK"))
===================== ============ =============== =============== =================== ================
 No.                   Entry date   Old balance     New balance     Accounting period   Workflow
--------------------- ------------ --------------- --------------- ------------------- ----------------
 2/2015                21/02/2015   -2 367,73       -1 723,45       2015-02             **Registered**
 1/2015                21/01/2015   2 518,58        -2 367,73       2015-01             **Registered**
 12/2014               21/12/2014   1 732,80        2 518,58        2014-12             **Registered**
 11/2014               21/11/2014   2 377,98        1 732,80        2014-11             **Registered**
 10/2014               21/10/2014   -2 395,03       2 377,98        2014-10             **Registered**
 9/2014                21/09/2014   -5 619,22       -2 395,03       2014-09             **Registered**
 8/2014                21/08/2014   -2 029,93       -5 619,22       2014-08             **Registered**
 7/2014                21/07/2014   -190,86         -2 029,93       2014-07             **Registered**
 6/2014                21/06/2014   5 846,85        -190,86         2014-06             **Registered**
 5/2014                21/05/2014   -524,23         5 846,85        2014-05             **Registered**
 4/2014                21/04/2014   -2 746,54       -524,23         2014-04             **Registered**
 3/2014                21/03/2014   288,24          -2 746,54       2014-03             **Registered**
 2/2014                21/02/2014   1 196,16        288,24          2014-02             **Registered**
 1/2014                21/01/2014                   1 196,16        2014-01             **Registered**
 **Total (14 rows)**                **-1 912,93**   **-3 636,38**
===================== ============ =============== =============== =================== ================
class lino_xl.lib.finan.BankStatement

Django model to represent a bank statement.

balance1

The old (or start) balance.

balance2

The new (or end) balance.

class lino_xl.lib.finan.BankStatementItem

Django model to represent an individual item of a bank statement.

class lino_xl.lib.finan.BankStatements

The base table of all tables on BankStatement.

class lino_xl.lib.finan.ItemsByBankStatement

Shows the items of a bank statement.

Cash journals

Cash journals are technically the same as bank statements.

>>> rt.show("finan.BankStatementsByJournal", ledger.Journal.get_by_ref("CSH"))
No data to display

Journal entries

>>> rt.show("finan.JournalEntriesByJournal", ledger.Journal.get_by_ref("MSC"))
No data to display
>>> rt.show("finan.JournalEntriesByJournal", ledger.Journal.get_by_ref("PRE"))
======== ============ =========== =================== ================
 No.      Entry date   Narration   Accounting period   Workflow
-------- ------------ ----------- ------------------- ----------------
 1/2014   01/01/2014               2014-01             **Registered**
======== ============ =========== =================== ================
class lino_xl.lib.finan.JournalEntry

Django model to represent a journal entry.

class lino_xl.lib.finan.JournalEntryItem

Django model to represent an individual item of a journal entry.

class lino_xl.lib.finan.JournalEntries

The base table of all tables on JournalEntry.

class lino_xl.lib.finan.ItemsByJournalEntry

Shows the items of a journal entry.

Model mixins

class lino_xl.lib.finan.FinancialVoucher

Base class for all financial vouchers.

item_account

The default value to use when FinancialVoucherItem.account of an item is empty.

item_remark

The default value to use when FinancialVoucherItem.remark of an item is empty.

printed
See :attr:`lino_xl.lib.excerpts.mixins.Certifiable.printed`
class lino_xl.lib.finan.FinancialVoucherItem

The base class for the items of all types of financial vouchers (FinancialVoucher).

account

The general account to be used in the primary booking. If this is empty, use item_account of the voucher.

project

The "project" related to this transaction. For example in Lino Welfare this is the client.

partner

The partner account to be used in the primary booking.

In Lino Welfare this field is optional and used only for transactions whose recipient is different from the client. When empty, Lino will book to the client (i.e. project).

amount

The amount to be booked. If this is empty, then the voucher cannot be registered.

dc

The direction of the primary booking to create.

remark

External reference. The description of this transation as seen by the external partner.

seqno
match

An arbitrary string used to group several movements.

A reference to the voucher that caused this voucher entry. For example the match of the payment of an invoice points to that invoice.

In a bank statement you might want to specify an individual date for every item.

class lino_xl.lib.finan.DatedFinancialVoucher

A FinancialVoucher whose items have a date field.

class lino_xl.lib.finan.DatedFinancialVoucherItem

A FinancialVoucherItem with an additional date field.

date

The value date of this item.

Plugin configuration

class lino_xl.lib.finan.Plugin

This Plugin class adds some entries to the Explorer menu. It contains the following additional attributes:

suggest_future_vouchers

Whether to suggest vouchers whose due_date is in the future.

The default value is currently False because some demo fixtures rely on this. But in most cases this should probably be set to True because of course a customer can pay an invoice in advance.

You can specify this for your application:

def setup_plugins(self):
    self.plugins.finan.suggest_future_vouchers = True
    super(Site, self).setup_plugins()

Or, as a local system administrator you can also simply set it after your SITE instantiation:

SITE = Site(globals())
...
SITE.plugins.finan.suggest_future_vouchers = True

Tables

class lino_xl.lib.finan.FinancialVouchers

Base class for the default tables of all financial voucher types (JournalEntries , PaymentOrders and BankStatements).

class lino_xl.lib.finan.ItemsByVoucher

The base table of all tables which display the items of a given voucher.

Booking suggestions

In a financial voucher you often book transactions that are actually expected. When you have booked your invoices, then Lino "knows" that each invoice will --ideally-- lead to a payment.

class lino_xl.lib.finan.SuggestionsByVoucher

Shows the suggested items for a given voucher, with a button to fill them into the current voucher.

This is the base class for SuggestionsByJournalEntry SuggestionsByBankStatement and SuggestionsByPaymentOrder who define the class of the master_instance (master)

This is an abstract virtual slave table.

Every row is a DueMovement object.

class lino_xl.lib.finan.SuggestionsByJournalEntry

A SuggestionsByVoucher table for a JournalEntry.

class lino_xl.lib.finan.SuggestionsByPaymentOrder

A SuggestionsByVoucher table for a PaymentOrder.

class lino_xl.lib.finan.SuggestionsByBankStatement

A SuggestionsByVoucher table for a BankStatement.

class lino_xl.lib.finan.SuggestionsByVoucherItem

Displays the payment suggestions for a given voucher item, with a button to fill them into the current item (creating additional items if more than one suggestion was selected).

class lino_xl.lib.finan.SuggestionsByJournalEntryItem
class lino_xl.lib.finan.SuggestionsByPaymentOrderItem

A SuggestionsByVoucherItem table for a PaymentOrderItem.

class lino_xl.lib.finan.SuggestionsByBankStatementItem

A SuggestionsByVoucherItem table for a BankStatementItem.

class lino_xl.lib.finan.ShowSuggestions

Show suggested items for this voucher.

class lino_xl.lib.finan.FillSuggestionsToVoucher

Fill selected suggestions from a SuggestionsByVoucher table into a financial voucher.

This creates one voucher item for each selected row.

class lino_xl.lib.finan.FillSuggestionsToVoucherItem

Fill the selected suggestions as items to the voucher. The first selected suggestion does not create a new item but replaces the item for which it was called.

Template files

pain_001.xml

Used for writing a SEPA payment initiation.

finan/PaymentOrder/pain_001.xml

class lino_xl.lib.finan.FinancialVoucherItemChecker