invoice2data
invoice2data copied to clipboard
TUTORIAL: Update documentation of "fields"
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.
In #311 we shortly discussed following some names documented in UBL.
This Pull Requests adds:
-
email
: does it make sense to replace it withelectronic_mail
(to matchElectronicMail
)? -
phone
: is there any UBL name for that? -
vat
: does it make sense to replace it withcompany_id
(to matchPartyTaxScheme
/CompanyID
)? -
amount_untaxed
: does it make sense to make ittax_exclusive_amount
(to matchTaxExclusiveAmount
)? -
lines
: does it make sense to make itinvoice_lines
(to match multipleInvoiceLine
)?
I like having things standardized but somehow I'm not convinced about above field names (like electronic_mail
or company_id
).
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
againstinvoice_line
might create unnecessary confusion
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.
I converted all our doc files to Markdown. Much easier to edit.
I will start this weekend. current pandemic has kept me busy in doing all those cheap jobs to stay fluid.
I've updated this pull request.
Preview: https://github.com/rmilecki/invoice2data/blob/tutorial-fields/TUTORIAL.md#fields
Suggested documented fields
names:
-
company_id
- based on UBL's cbc:CompanyID -
electronic_mail
- based on UBL's cbc:ElectronicMail -
telephone
- based on UBL's cbc:Telephone -
tax_exclusive_amount
- based on UBL's cbc:TaxExclusiveAmount -
sale_date
- custom name -
tax_exclusive_amount
- based on UBL's cbc:TaxExclusiveAmount -
bic
- custom name as UBL's cbc:ID doesn't fit -
due_date
- based on UBL's cbc:DueDate -
bic
- custom name as UBL's cbc:ID doesn't fit -
payment_means_name
- based on UBL's @name
@m3nu, @Seriousness: can you review this pull request, please?
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
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
siren
french 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.