Invoice¶

class en16931.Invoice(invoice_id=None, currency='EUR', from_xml=False)¶

EN16931 Invoice class.

This is the main entry point of this library. You can build, step by step, an Invoice and then serialize to XML.

It uses the class Entity to represent seller and buyer parties, and the class InvoiceLine to represent invoice lines.

>>> from en16931 import Invoice
>>> invoice = Invoice(invoice_id="2018-01", currency="EUR")
>>> seller = Entity(name="Acme Inc.", tax_scheme="VAT",
...                 tax_scheme_id="ES34626691F", country="ES",
...                 party_legal_entity_id="ES34626691F",
...                 registration_name="Acme INc.", mail="acme@acme.io",
...                 endpoint="ES76281415Y", endpoint_scheme="ES:VAT",
...                 address="easy street", postalzone="08080",
...                 city="Barcelona")
>>> buyer = Entity(name="Corp Inc.", tax_scheme="VAT",
...                tax_scheme_id="ES76281415Y", country="ES",
...                party_legal_entity_id="ES76281415Y",
...                registration_name="Corp INc.", mail="corp@corp.io",
...                endpoint="ES76281415Y", endpoint_scheme="ES:VAT",
...                address="busy street", postalzone="08080",
...                city="Barcelona")
>>> invoice.buyer_party = buyer
>>> invoice.seller_party = seller
>>> invoice.due_date = "2018-09-11"
>>> invoice.issue_date = "2018-06-11"
>>> # lines
>>> il1 = InvoiceLine(quantity=11, unit_code="EA", price=2,
...                   item_name='test 1', currency="EUR",
...                   tax_percent=0.21, tax_category="S")
>>> il2 = InvoiceLine(quantity=2, unit_code="EA", price=25,
...                   item_name='test 2', currency="EUR",
...                   tax_percent=0.21, tax_category="S")
>>> il3 = InvoiceLine(quantity=5, unit_code="EA", price=3,
...                   item_name='test 3', currency="EUR",
...                   tax_percent=0.1, tax_category="S")
>>> invoice.add_lines_from([il1, il2, il3])

And serialize it to XML:

>>> # As a string
>>> xml = invoice.to_xml()
>>> # Or save it directly to a file
>>> invoice.save('example_invoice.xml')

__init__(invoice_id=None, currency='EUR', from_xml=False)¶

Initialize an Invoice.

This is the main class and entry point for creating an Invoice.

Parameters:

invoice_id (string (optional, default '1')) – Arbitrary string to identify the invoice.
currency (string (optional, default 'EUR')) – An ISO 4217 currency code.
from_xml (bool (optional, default False)) – A flag to mark if the object is the result of importing an XML invoice.

Raises:

KeyError – If the currency code is not a valid ISO 4217 code.:

Examples

By default the currency of the invoice is EUR and its id is 1:

>>> i = Invoice()
>>> i.invoice_id
1
>>> i.currency
EUR

You can also specify an arbitrary id and a valid ISO 4217 currency code.

>>> i = Invoice(invoice_id="0001-2018", currency="USD")
>>> i.invoice_id
0001-2018
>>> i.currency
USD

__weakref__¶: list of weak references to the object (if defined)

add_line(line)¶

Adds an InvoiceLine to the Invoice.

Parameters:: line (InvoiceLine object.) –

add_lines_from(container)¶

Adds InvoiceLine instances from a container.

Parameters:: container (container) – An iterable container of InvoiceLine objects.

property buyer_party¶

The Entity with the role of AccountingCustomerParty.

See the Entity class for details

Parameters:

party (Entity object.) – The Entity object that plays the role of AccountingCustomerParty.

Raises:

ValueError – if the Entity is not valid.
TypeError – if the input is not an Entity or Entity subclass.

Type:

Property

property charge_amount¶

The ChargeTotalAmount of the Invoice.

Parameters:: value (string, integer, float) – The input must be a valid input for the Decimal class the Python Standard Library.
Raises:: decimal.InvalidOperation – If the input cannot be converted: to a Decimal.
Type:: Property

property charge_base_amount¶

The base amount of the charge.

The BaseAmount of the charge in PEPPOL BIS 3 terms.

property charge_percent¶

The percentage that the charge represents.

The MultiplierFactorNumeric of the charge in PEPPOL BIS 3 terms.

Parameters:: value (string, integer, float) – The input must be a valid input for the Decimal class the Python Standard Library.

property currency¶

String representation of the ISO 4217 currency code.

Parameters:: currency_str (string) – String representation of the ISO 4217 currency code.
Raises:: KeyError – If the currency code is not a valid ISO 4217 code.:
Type:: Property

property discount_amount¶

The AllowanceTotalAmount of the Invoice.

Parameters:: value (string, integer, float) – The input must be a valid input for the Decimal class the Python Standard Library.
Raises:: decimal.InvalidOperation – If the input cannot be converted: to a Decimal.
Type:: Property

property discount_base_amount¶

The base amount of the discount.

The BaseAmount of the discount in PEPPOL BIS 3 terms.

property discount_percent¶

The percentage that the discount represents.

The MultiplierFactorNumeric of the discount in PEPPOL BIS 3 terms.

property due_date¶

Due date of the invoice.

Parameters:: date (datetime or string) – If the input is a string, it should be in one of the following formats: “%Y-%m-%d”, “%Y%m%d”, “%d-%m-%Y”, “%Y/%m/%d”, “%d/%m/%Y”.
Raises:: ValueError – if the input string cannot be converted to a datetime object.

Examples

>>> from datetime import datetime
>>> i = Invoice()

Supported date formats are:

>>> i.due_date = datetime(2018, 6, 21)
>>> i.due_date
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.due_date = "2018-06-21"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.due_date = "20180621"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.due_date = "21-6-2018"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.due_date = "2018/06/21"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.due_date = "21/6/2018"
datetime.datetime(2018, 6, 21, 0, 0)

Incorrect date formats will raise a ValueError:

>>> i.due_date = "today"
Traceback (most recent call last):
[...]
ValueError: See documentation for string date formats supported

Type:: Property

classmethod from_xml(xml_path)¶

Import a XML invoice in EN16931 format.

Parameters:: xml_path (path) – A path to the XML file.
Raises:: FileNotFoundError – if the file does not exist.:

Examples

>>> i = Invoice.from_xml('path/to/invoice.xml')

gross_subtotal(tax_type=None)¶: Sum of gross amount of each invoice line.

property issue_date¶

The issue date of the invoice.

Parameters:: date (datetime or string) – If the input is a string, it should be in one of the following formats: “%Y-%m-%d”, “%Y%m%d”, “%d-%m-%Y”, “%Y/%m/%d”, “%d/%m/%Y”.
Raises:: ValueError: – if the input string cannot be converted to a datetime object.

Examples

>>> from datetime import datetime
>>> i = Invoice()

Supported date formats are:

>>> i.issue_date = datetime(2018, 6, 21)
>>> i.issue_date
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.issue_date = "2018-06-21"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.issue_date = "20180621"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.issue_date = "21-6-2018"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.issue_date = "2018/06/21"
datetime.datetime(2018, 6, 21, 0, 0)
>>> i.issue_date = "21/6/2018"
datetime.datetime(2018, 6, 21, 0, 0)

Incorrect date formats will raise a ValueError:

>>> i.issue_date = "today"
Traceback (most recent call last):
[...]
ValueError: See documentation for string date formats supported

Type:: Property

property line_extension_amount¶

The total LineExtensionAmount of the invoice.

It’s only computed as the gross_subtotal() if the Invoice was not imported from an XML file. In that case, its value is the one reported on the XML.

lines_with_taxes(tax_type=None)¶

Generator of InvoiceLines

Parameters:: tax_type (Tax object (default None).) – If a Tax object is provided, only generate lines with that Tax. If this parameter is None, generate all lines.

property payable_amount¶

The total PayableAmount of the invoice.

It’s only computed as the total() if the Invoice was not imported from an XML file. In that case, its value is the one reported on the XML.

property payment_means_code¶

The payment means code.

It has to be one of:

‘10’: ‘cash’
‘49’: ‘debit’
‘31’: ‘transfer’
‘26’: ‘cheque’
‘23’: ‘cheque_b’
‘48’: ‘credit’
‘ZZZ’: ‘awarding, reposition, special’

Parameters:: code (string) – A valid payment means code.
Raises:: ValueError – If the code is not valid.
Type:: Property

save(path=None)¶

Save the XML representation of the invoice.

Parameters:: path (a path (optional, default None)) – If the path is None it a file named ‘invoice_id.xml’ will be created in the current working directory.

property seller_party¶

The Entity with the role of AccountingSupplierParty.

See the Entity class for details

Parameters:

party (Entity object.) – The Entity object that plays the role of AccountingSupplierParty.

Raises:

ValueError: – if the Entity is not valid.
TypeError: – if the input is not an Entity or Entity subclass.

Type:

Property

subtotal(tax_type=None)¶

Gross amount before taxes.

TotalGrossAmount - AllowanceTotalAmount + ChargeTotalAmount

tax_amount(tax_type=None)¶

Computes the tax amount of the Invoice.

Parameters:: tax_type (Tax object (default None).) – If a Tax object is provided, the tax amount corresponding to the porvided Tax. If None the total tax amount.

property tax_exclusive_amount¶

The total TaxExclusiveAmount of the invoice.

It’s only computed as the gross_subtotal() if the Invoice was not imported from an XML file. In that case, its value is the one reported on the XML.

property tax_inclusive_amount¶

The total TaxInclusiveAmount of the invoice.

It’s only computed as the total() if the Invoice was not imported from an XML file. In that case, its value is the one reported on the XML.

taxable_base(tax_type=None)¶

Computes the taxable base of the Invoice

Parameters:: tax_type (Tax object (default None).) – If a Tax object is provided, the taxable base corresponding to the porvided Tax. If None the total taxable base.

to_xml()¶

Serialize the invoice object to XML.

Generate a valid PEPPOL BIS 3 XML document using the UBL 2.1 syntax.

total()¶: Computes the TaxInclusiveAmount of the Invoice

property unique_taxes¶: Set of unique taxes in the Invoice.

Invoice¶

python-en16931

Table of Contents

Related Topics

Navigation