TUTORIAL: Update documentation of "fields"

[rmilecki]

TUTORIAL: Document suggested common field names

This should help standardize templates a bit.

Signed-off-by: Rafał Miłecki <[email protected]>

TUTORIAL: Move regex info to the "Parser regex" section

It's where it's really useful. In "fields" other parsers can be used.
Some of them not requiring regex at all.

Signed-off-by: Rafał Miłecki <[email protected]>

I was trying to start discussion on naming fields in the #309 and just recently a feature request has been opened: #311.

This Pull Request updates documentation adding some standard fields names that should be used for common invoice data.

Please feel free to discuss & comment this idea as well as chosen names.

[rmilecki]

Preview of updated TUTORIAL.rst

[rmilecki]

In #311 we shortly discussed following some names documented in UBL.

This Pull Requests adds:

• email: does it make sense to replace it with electronic_mail (to match ElectronicMail)?
• phone: is there any UBL name for that?
• vat: does it make sense to replace it with company_id (to match PartyTaxScheme / CompanyID)?
• amount_untaxed: does it make sense to make it tax_exclusive_amount (to match TaxExclusiveAmount)?
• lines: does it make sense to make it invoice_lines (to match multiple InvoiceLine)?

I like having things standardized but somehow I'm not convinced about above field names (like electronic_mail or company_id).

[Seriousness]

I do ask myself if we'd like to follow this mixed way of writing or go all lowercase with _ before a group of capital letters or single capital letters. Anything that speaks for/against using the original UBL entity name besides personal preferences? I do agree that this looks a bit akward and yes the terms do not really feel like fitting everyday life.

Maybe it is an idea to have some mapping and processing at hand, so old template names could be rewritten for xml export? Not sure if thats actually needed by anyone. My basic idea was only to have existing standards implemented, but I do see that maybe UBL is not the way to go?

Considering the terms:

• From what I have seen it looks like telephone is ubl for the phone.
• considering the company_id it does make sense from my pov as the tax number should be universal identifier for most countries and companys. As long as it is not flagged als "necessary" field, it shouldnt cause any problems in usage.
• tax_exclusive_amount should be understandible from my pov
• using invoice_lines against invoice_line might create unnecessary confusion

[m3nu]

Currently we follow Python syntax (snake case) for field names. UBL names (camel case) should be "translated" before using. This is also done when going e.g. from JS to Python.

I'd always use UBL for new field names. For existing fields, it's probably not worth breaking backwards compat and existing templates users may have locally. Also because this project's relation to UBL isn't very strong.

[m3nu]

I converted all our doc files to Markdown. Much easier to edit.

[Seriousness]

I will start this weekend. current pandemic has kept me busy in doing all those cheap jobs to stay fluid.

[rmilecki]

I've updated this pull request.

Preview: https://github.com/rmilecki/invoice2data/blob/tutorial-fields/TUTORIAL.md#fields

Suggested documented fields names:

1. company_id - based on UBL's cbc:CompanyID
2. electronic_mail - based on UBL's cbc:ElectronicMail
3. telephone - based on UBL's cbc:Telephone
4. tax_exclusive_amount - based on UBL's cbc:TaxExclusiveAmount
5. sale_date - custom name
6. tax_exclusive_amount - based on UBL's cbc:TaxExclusiveAmount
7. bic - custom name as UBL's cbc:ID doesn't fit
8. due_date - based on UBL's cbc:DueDate
9. bic - custom name as UBL's cbc:ID doesn't fit
10. payment_means_name - based on UBL's @name

@m3nu, @Seriousness: can you review this pull request, please?

[Seriousness]

sorry forgot.

I'd add:

tax_inclusive_amount - based on cbc:TaxInclusiveAmount

tax_total - based on cbc:tax_total - document level

per item+document level:

tax_percent - based on cbc:Percent

I am not sure if this is internationally common, in Germany the VAT normally applies for the date the service has been provided/finished. If we agree on that it could be

tax_date - based on cbc:TaxPointDate

[bosd]

Could you include a section of other programs using this library?
As it would be usefull to know which fields are used so current implementations are'nt getting broken.
For example this library is used in the invoice2data module of odoo.
https://github.com/OCA/edi/tree/14.0/account_invoice_import_invoice2data

That module looks at the following fields:
vat: for matching the invoice to the vendor. (if the VAT number of the supplier is not in the text of PDF file, add it as a static in the template or add a 'partner_name' key)
'partner_name' can be optionally used for matching of supplier
partner_email can be optionally used for matching of supplier
partner_street can be optionally used for matching of supplier
partner_street2 can be optionally used for matching of supplier
partner_zip can be optionally used for matching of supplier
partner_country_code can be optionally used for matching of supplier
partner_website can be optionally used for matching of supplier
sirenfrench vat number
partner_coc Chamber of Commerce number

invoice_number as a reference of the invoice
currency
amount ('amount' is the total amount with taxes)
amount_untaxed or amount_tax (one or the other, no need for both)
date: the date of the invoice
invoice_number
date_due, if this information is available in the text of the PDF file.
date_start , if this information is available in the text of the PDF file.
date_end, if this information is available in the text of the PDF file.

In the lines section
name or description, currently support is in development to use this to match a product
product,currently support is in development
qty
price_unit
price_subtotal The total amount of the invoice line, (including taxes)
vat_percent The vat percentage if present on the invoice line
vat_line_amount The amount of VAT if present on the line.
discount float Percentage of discount to apply to the line. Default 0.0
date_start Usefull for importing services which are unvoiced per period.
date_end
line_note Used to display notes in Odoo
sectionheader Used to display invoiceline headers in Odoo

On a different note, to make a invoice fully compliant to one of the ubl standards a lot more info needs to be used / mapped.
For those interested have a look in the oca repositories. For example in community data-files there is al lot of information on ubl invoicing.