invoicing
: Generating invoices¶
The lino_xl.lib.invoicing
plugin adds functionality for
invoicing, i.e. automatically generating invoices from data in the
database.
This document describes some general aspects of invoicing and how applications can handle this topic. You should have read sales : Product invoices and Accounting stuff in Lino. See also Invoicing in Lino Voga (lino_voga.lib.invoicing) and How Lino Tera generates invoices.
This is a tested document. The following instructions are used for initialization:
>>> from lino import startup
>>> startup('lino_book.projects.roger.settings.demo')
>>> from lino.api.doctest import *
>>> ses = rt.login("robin")
>>> translation.activate('en')
Overview¶
As an application developer you define invoice generators by
having one or several models of your application inherit from
InvoiceGenerator
.
API¶
On the API level it defines the InvoiceGenerator
mixin.
This plugin requires the lino_xl.lib.sales
plugin.
>>> dd.plugins.invoicing.needs_plugins
['lino_xl.lib.sales']
The plugin adds a main menu command
:>>> show_menu_path(invoicing.Plan.start_plan)
Sales --> Create invoices
The InvoiceGenerator
model mixin¶
-
class
lino_xl.lib.invoicing.
InvoiceGenerator
¶ Mixin for things that can generate invoices.
An invoice generator must produce a series of invoiceable events (the application developer must implement a method
get_invoiceable_events()
). These events can be instances of any model, but the generator'sget_invoiceable_event_formatter()
must understand them.Methods and class attributes:
-
default_invoiceable_qty
¶ The default value to return by
get_invoiceable_qty()
.
-
get_invoice_items
(self, info, invoice, ar)¶ Yield one or several invoice items generated by this object.
These must be instances of
lino_xl.lib.sales.InvoiceItem
.
-
get_invoiceable_events
(self, start_date, max_date)¶ Return a Django query that represents the invoiceable events.
The query must be sorted in the order they are to be considered for invoicing.
-
get_invoiceable_event_formatter
(self)¶ Return a callable which formats an invoiceable event as a HTML etree element.
-
get_invoiceables_for_plan
(cls, plan, partner=None)¶ Yield a sequence of invoiceable candidates (objects of this class) for the given plan. If a partner is given, use it as an additional filter condition.
Not every yielded candidate will become an invoice. This is a pre-selection. For every candidate Lino will call
get_invoiceable_product()
-
get_invoiceable_product
(self, plan)¶ To be implemented by subclasses. Return the product to put into the invoice item.
>>> obj = rt.models.courses.Enrolment.objects.all()[0] >>> print(obj.get_invoiceable_product()) Journeys
-
get_invoiceable_qty
(self)¶ Return the quantity to use for each generated invoice item.
May be overridden by subclasses. The default implementation simply returns
default_invoiceable_qty
.>>> obj = rt.models.courses.Enrolment.objects.all()[0] >>> print(obj.get_invoiceable_qty()) 1
-
get_invoiceable_title
(self, invoice=None)¶ Return the title to put into the invoice item.
May be overridden by subclasses.
-
invoicings
¶ A simple GenericRelation to all invoice items pointing to this enrolment.
This is preferred over
get_invoicings()
.
-
get_invoicings
(**kwargs)¶ Get a queryset with the invoicings which point to this enrolment.
This is deprecated. Preferred way is to use
invoicings
.
-
get_last_invoicing
()¶ Return the last invoicing that was created by this generator. According to the invoice's
voucher_date
.
-
-
class
lino_xl.lib.invoicing.
InvoicingInfo
¶ A volatile object which holds cached information about a given invoice generator.
-
generator
¶ The invoice generator this is about.
-
max_date
¶ The latest date of events considered when computing this.
-
invoicings
¶ Existing invoice items generated by this generator for earlier periods.
-
invoiced_qty
¶ Sum of quantities invoiced earlier.
-
invoiced_events
¶ Number of events invoiced earlier.
-
used_events
¶ A list of the "events" used for computing this.
-
invoiceable_product
¶ Which fee to apply. If this is None, no invoicing should get generated.
-
Sales rules¶
Every partner can have a sales rule.
-
class
lino_xl.lib.invoicing.
SalesRule
¶ The Django model used to represent a sales rule.
-
partner
¶ The partner to which this sales rule applies.
-
invoice_recipient
¶ The partner who should get the invoices caused by this partner.
-
paper_type
¶ The default paper type to be used for invoicing.
-
>>> fld = rt.models.invoicing.SalesRule._meta.get_field('invoice_recipient')
>>> print(fld.help_text)
The partner who should get the invoices caused by this partner.
-
class
lino_xl.lib.invoicing.
SalesRules
¶
The invoicing plan¶
-
class
lino_xl.lib.invoicing.
Plan
¶ The Django model used to represent an invoicing plan.
An invoicing plan is a rather temporary database object which represents the plan of a given user to have Lino generate a series of invoices.
It inherits from
lino.modlib.users.UserPlan
.-
user
¶ The user who manages this plan.
-
today
¶ This invoice date to be used for the invoices to generate.
-
max_date
¶ Don't invoice events after this date. If this is empty, Lino will use the day before the invoice date.
-
partner
¶
-
update_plan
¶ Update this plan (fill the list of suggestions).
-
execute_plan
¶ Execute this plan (create an invoice for each selected suggestion).
-
start_plan
(user, **options)¶ Start an invoicing plan for the given user on the database object defined by k and v. Where k is the name of the field used to select the plan (e.g. 'partner' or 'journal') and v is the value for that field.
This will either create a new plan, or check whether the currently existing plan for this user was for the same database object. If it was for another object, then clear all items.
-
fill_plan
(ar)¶ Add items to this plan, one for each invoice to generate.
This also groups the invoiceables by their invoiceable partner.
Note a case we had (20171007) : One enrolment for Alfons whose invoice_recipient points to Erna, a second enrolment for Erna directly. The first enrolment returned Erna as Partner, the second returned Erna as Pupil, so they were not grouped.
-
-
class
lino_xl.lib.invoicing.
Item
¶ The Django model used to represent a item of an invoicing plan.
The items of an invoicing plan are called suggestions.
-
plan
¶
-
partner
¶
-
preview
¶ A textual preview of the invoiceable items to be included in the invoice.
-
amount
¶
-
invoice
¶ The invoice that has been generated. This field is empty for new items. When an item has been executed, this field points to the generated invoice.
The following fields are maybe not important:
-
first_date
¶
-
last_date
¶
-
number_of_invoiceables
¶
-
create_invoice(ar):
Create the invoice corresponding to this item of the plan.
-
-
class
lino_xl.lib.invoicing.
Plans
¶
-
class
lino_xl.lib.invoicing.
MyPlans
¶
-
class
lino_xl.lib.invoicing.
AllPlans
¶
-
class
lino_xl.lib.invoicing.
Items
¶
-
class
lino_xl.lib.invoicing.
ItemsByPlan
¶
-
class
lino_xl.lib.invoicing.
InvoicingsByInvoiceable
¶
-
class
lino_xl.lib.invoicing.
StartInvoicing
¶ Start an invoicing plan for the authenticated user.
Base for
StartInvoicingForPartner
.Inherits from
lino.modlib.users.StartPlan
and just overrides the label.
-
class
lino_xl.lib.invoicing.
StartInvoicingByArea
¶ Start an invoicing plan for this area.
This is installed onto the VouchersByJournal table of the VoucherType for the configured
voucher_model
as start_invoicing.
-
class
lino_xl.lib.invoicing.
StartInvoicingForPartner
¶ Start an invoicing plan for this partner.
This is installed onto the
contacts.Partner
model as start_invoicing.
-
class
lino_xl.lib.invoicing.
ExecutePlan
¶ Execute this invoicing plan. Create an invoice for each selected suggestion.
-
class
lino_xl.lib.invoicing.
ExecuteItem
¶ Create an invoice for this suggestion.
-
class
lino_xl.lib.invoicing.
ToggleSelection
¶ Invert selection status for all suggestions.
Invoicing areas¶
An invoicing area is is used to classify business activities into different parts for which end users can start separate invoicing plans.
This is used in Lino Presto to differentiate between activities for which invoicing is often run manually based on occasional work from those that are invoiced monthly automatically based on regular work. In Lino Tera they might get used to separate the therapy centres in different towns.
The application is responsible for selecting only invoiceables that belong to
the area of the current plan. For example Lino Presto does this by defining a
field lino_presto.lib.cal.Room.invoicing_area
.
>>> rt.show(invoicing.Areas)
===== ============= ================== ================== ======================
No. Designation Designation (de) Designation (fr) Journal
----- ------------- ------------------ ------------------ ----------------------
1 First Erster Premier Sales invoices (SLS)
===== ============= ================== ================== ======================
Resetting title and description of a generated invoice item¶
When the user sets title of an automatically generated invoice item to an empty string, then Lino restores the default value for both title and description