Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More
trading
: Exchanging things with your business partners¶
See also The trading plugin.
This page contains code snippets (lines starting with >>>
), which are
being tested during our development workflow. The following
snippet initializes the demo project used throughout this page.
>>> from lino_book.projects.cosi4.startup import *
>>> ses = rt.login('robin')
The plugin¶
Lino implements product invoices in the lino_xl.lib.trading
plugin. The internal codename was “sales” until 20240325, we renamed it because you
might generate product invoices for other trade types as well.
The plugin needs and automatically installs the
lino_xl.lib.products
plugin.
It also needs and installs lino_xl.lib.vat
(and not
lino_xl.lib.vatless
). Which means that if you want product invoices, you
cannot not also install the VAT framework. If the site operator is not
subject to VAT, you might add lino_xl.lib.bevats
, which hides most of the
VAT functionality.
>>> dd.plugins.trading.needs_plugins
['lino.modlib.memo', 'lino_xl.lib.products', 'lino_xl.lib.vat']
This plugin may be combined with the lino_xl.lib.invoicing
plugin, which
adds automatic generation of such product invoices.
Configuration settings¶
- lino_xl.lib.trading.items_column_names¶
The
column_names
to use forItemsByInvoice
.>>> dd.plugins.trading.items_column_names 'asset product title unit_price qty discount_rate amount invoiceable *'
- lino_xl.lib.trading.columns_to_print¶
A list of column names as they should appear in the body a printed trade voucher.
The following columns are currently supported: qty, title, unit_price, asset, amount, total_incl and total_base. These names are defined in the
trading/VatProductInvoice/default.weasy.html
template.This can also get specified as a space-separated string, which will be converted to a list at startup.
Value in this demo site is:
>>> dd.plugins.trading.columns_to_print 'asset title unit_price qty amount'
- trading.print_items_table¶
The name of a data table to use when printing invoices using appypod print method.
No longer used.
Product invoices¶
- class lino_xl.lib.trading.VatProductInvoice¶
The Django model representing a product invoice.
Inherits from
lino_xl.lib.accounting.Voucher
,TradingVoucher
,Matching
,lino_xl.lib.invoicing.InvoicingTargetVoucher
andStorageTransferer
.Virtual fields:
- balance_before¶
The balance of payments or debts that existed already before this voucher.
On a printed invoice, this amount should be mentioned and added to the invoice’s amount in order to get the total amount to pay.
- balance_to_pay¶
The balance of all movements matching this invoice.
Methods:
- get_print_items(self, ar):
For usage in an appy template:
do text from table(obj.get_print_items(ar))
- class lino_xl.lib.trading.InvoiceItem¶
The Django model representing an item of a product invoice.
- class lino_xl.lib.trading.InvoiceDetail¶
The Lino layout representing the detail view of a product invoice.
- class lino_xl.lib.trading.Invoices¶
- class lino_xl.lib.trading.InvoicesByJournal¶
Shows all invoices of a given journal.
The master instance must be a journal having
VatProductInvoice
aslino_xl.lib.accounting.Journal.voucher_type
.
- class lino_xl.lib.trading.DueInvoices¶
Shows all due product invoices.
- class lino_xl.lib.trading.TradingVoucherItem¶
Model mixin for voucher items that potentially refer to a product.
- description¶
A multi-line rich text to be printed in the resulting printable document.
- discount¶
The percentage to subtract from the unit price of this item.
- class lino_xl.lib.trading.ItemsByInvoicePrint¶
The table used to render items in a printable document.
- description_print¶
TODO: write more about it.
- class lino_xl.lib.trading.ItemsByInvoicePrintNoQtyColumn¶
Alternative column layout to be used when printing an invoice.
- class lino_xl.lib.trading.TradingPrintable¶
Inherits from
PartnerPrintable
andCertifiable
.- subject¶
A single-line text that describes this voucher.
- paper_type¶
The type of paper to use when printing this voucher.
- class lino_xl.lib.trading.TradingVoucher¶
Common base class for
lino_xl.lib.orders.Order
andVatProductInvoice
.Inherits from
TradingPrintable
andVatVoucher
Subclasses must either add themselves a
date
field (as doesOrder
) or inherit it from Voucher (as doesVatProductInvoice
).This model mixin sets
edit_totals
to False.- intro¶
An optional introduction text to be printed on the document.
- print_items_table¶
The table (column layout) to use in the printed document.
Paper types¶
- class lino_xl.lib.trading.PaperType¶
Describes a paper type (document template) to be used when printing an invoice.
A sample use case is to differentiate between invoices to get printed either on a company letterpaper for expedition via paper mail or into an email-friendly pdf file.
Inherits from
lino.utils.mldbc.mixins.BabelNamed
.- templates_group = 'trading/VatProductInvoice'
A class attribute.
- template¶
Trade types¶
The plugin updates your lino_xl.lib.accounting.TradeTypes.sales
,
causing two additional database fields to be injected to
lino_xl.lib.products.Product
.
The first injected field is the sales price of a product:
>>> translation.activate('en')
>>> print(accounting.TradeTypes.sales.price_field_name)
sales_price
>>> print(accounting.TradeTypes.sales.price_field_label)
Sales price
>>> products.Product._meta.get_field('sales_price')
<lino.core.fields.PriceField: sales_price>
The other injected field is the sales base account of a product:
>>> print(accounting.TradeTypes.sales.base_account_field_name)
sales_account
>>> print(accounting.TradeTypes.sales.base_account_field_label)
Sales account
>>> products.Product._meta.get_field('sales_account')
<django.db.models.fields.related.ForeignKey: sales_account>
Trading rules¶
Every business partner can have a series of trading rules, one for each trade type.
- class lino_xl.lib.trading.TradingRule¶
The Django model used to represent a trading rule.
- partner¶
The partner to which this trade rule applies.
- payment_term¶
The default payment terms to apply to new trading vouchers for this partner and trade type.
- 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.trading.TradingRule._meta.get_field('invoice_recipient')
>>> print(fld.help_text)
The partner who should get the invoices caused by this partner.
- class lino_xl.lib.trading.TradingRules¶
Shows the list of trading rules.
The sales journal¶
The cosi2 demo site has no VAT declarations, no purchase journals, no financial journals, just a single sales journal.
>>> rt.show('accounting.Journals', column_names="ref name trade_type")
=========== ================ ==================== ============
Reference Designation Designation (es) Trade type
----------- ---------------- -------------------- ------------
SLS Sales invoices Facturas de ventas Sales
=========== ================ ==================== ============
Invoices are sorted by number and year. The entry date should normally never “go back”. Lino supports exceptional situations, e.g. starting to issue invoices at a given number or entering a series of sales invoices from a legacy system afterwards.
>>> jnl = rt.models.accounting.Journal.get_by_ref("SLS")
>>> rt.show('trading.InvoicesByJournal', jnl)
...
==================== ============ ======= ======= =========================== ========= =============== ================
No. Date Date1 Date2 Partner Subject TotIncl Workflow
-------------------- ------------ ------- ------- --------------------------- --------- --------------- ----------------
1/2024 07/01/2024 Rumma & Ko OÜ 2 999,85 **Registered**
2/2024 08/01/2024 Bäckerei Ausdemwald 2 039,82 **Registered**
3/2024 09/01/2024 Bäckerei Mießen 679,81 **Registered**
4/2024 10/01/2024 Bäckerei Schmitz 280,00 **Registered**
5/2024 11/01/2024 Garage Mergelsberg 535,00 **Registered**
6/2024 07/02/2024 Donderweer BV 1 110,16 **Registered**
7/2024 08/02/2024 Van Achter NV 1 499,85 **Registered**
8/2024 09/02/2024 Hans Flott & Co 1 939,82 **Registered**
9/2024 10/02/2024 Bernd Brechts Bücherladen 815,96 **Registered**
**Total (9 rows)** **11 900,27**
==================== ============ ======= ======= =========================== ========= =============== ================
>>> mt = contenttypes.ContentType.objects.get_for_model(accounting.Journal).id
>>> obj = trading.VatProductInvoice.objects.get(journal__ref="SLS", number=9)
>>> url = '/api/trading/InvoicesByJournal/{0}'.format(obj.id)
>>> url += '?mt={0}&mk={1}&an=detail&fmt=json'.format(mt, obj.journal.id)
>>> test_client.force_login(ses.user)
>>> res = test_client.get(url, REMOTE_USER='robin')
>>> # res.content
>>> r = check_json_result(res, "navinfo data disable_delete id param_values title")
>>> print(r['title'])
<a ...>Sales invoices (SLS)</a> » SLS 9/2024
IllegalText: The <text:section> element does not allow text¶
The following reproduces a situation which caused above error until 2015-11-11.
TODO: it is currently disabled for different reasons: leaves dangling temporary directories, does not reproduce the problem (probably because we must clear the cache).
>> obj = rt.models.trading.VatProductInvoice.objects.all()[0] >> obj VatProductInvoice #1 (‘SLS#1’) >> from lino.modlib.appypod.appy_renderer import AppyRenderer >> tplfile = rt.find_config_file(‘trading/VatProductInvoice/Default.odt’) >> context = dict() >> outfile = “tmp.odt” >> renderer = AppyRenderer(ses, tplfile, context, outfile) >> ar = rt.models.trading.ItemsByInvoicePrint.create_request(obj) >> print(renderer.insert_table(ar)) #doctest: +ELLIPSIS <table:table …</table:table-rows></table:table>
>> item = obj.items.all()[0] >> item.description = “”” … <p>intro:</p><ol><li>first</li><li>second</li></ol> … <p></p> … “”” >> item.save() >> print(renderer.insert_table(ar)) #doctest: +ELLIPSIS Traceback (most recent call last): … IllegalText: The <text:section> element does not allow text
The language of an invoice¶
The language of an invoice not necessary that of the user who enters
the invoice. It is either the partner’s language
or (if this is empty)
the Site’s get_default_language
.
Discount was applied on the unit price¶
Until 20250501 the discount of an invoice item
(TradingVoucherItem.discount
was getting applied to the unit price,
not to the total amount. This may lead to surprising situations. For example,
when the unit price was 0.01 and the quantity is 1000, the total_base
would remain 10.00 even with a discount of 40%, and it suddenly becomes 0.00
when you give more than 50% discount.
>>> vch = trading.VatProductInvoice.objects.last()
>>> prd = products.Product(name="Nail", sales_price="0.01")
>>> prd.full_clean()
>>> prd.save()
>>> i = vch.add_voucher_item(product=prd, qty=1000)
>>> i.full_clean()
>>> i.product_changed()
>>> print(i.total_base)
10.00
>>> i.discount_rate = 40
>>> i.discount_rate_changed()
>>> print(i.total_base)
6.00
>>> i.discount_rate = 51
>>> i.discount_rate_changed()
>>> print(i.total_base)
4.90
>>> prd.delete()
Some fields of a registered voucher can remain editable¶
The default behaviour is that a registered voucher is not editable.
>>> UserTypes = rt.models.users.UserTypes
>>> InvoicesByJournal = rt.models.trading.InvoicesByJournal
>>> obj = InvoicesByJournal.model.objects.first()
>>> obj.state
<accounting.VoucherStates.registered:20>
>>> actor = InvoicesByJournal
>>> actor.get_row_permission(
... obj, ses, actor.get_row_state(obj), actor.update_action)
False
But if you set accounting.VoucherState.is_editable to True for the
registered
state, then the record itself becomes editable.
>>> accounting.VoucherStates.registered.is_editable = True
>>> actor.get_row_permission(
... obj, ses, actor.get_row_state(obj), actor.update_action)
True
>>> resp = obj.disabled_fields(obj.get_default_table().request(parent=ses))
>>> assert resp == {'clear_printed', 'send_now'}
Only the voucher state refuses editing, the actors don’t disable editing for all rows:
>>> rt.models.trading.InvoicesByJournal.editable
True
>>> InvoicesByJournal.hide_editing(UserTypes.admin)
False
TODO: Split is_editable of a voucher state into two booleans: fields_editable and row_editable. For example the partner field of a registered trading invoice must never be editable while the language field or some narration might remain editable.