English Deutsch

Documentation fintech.invoicing

Invoicing module of the Python Fintech package.

This module defines functions and classes working with invoices. Create e-invoices (Factur-X / ZUGFeRD 2 / XRechnung / Peppol), generate paycodes and verify VAT-IDs. New since v8.0

Index
fintech.invoicing.check_vatid(vat_id, timeout=30)

Checks a VAT-ID for validity using the webservice provided by the European Commission and returns a dictionary with the keys valid (bool), name (str) and address (str). The latter two values are not set for all countries and can be empty.

class fintech.invoicing.Paycode(account, purpose, amount=None, purpose_code=None)

The Paycode class is used to create a Girocode/EPC-QR-Code that can be scanned by banking apps to initiate a SEPA credit transfer.

Initializes the Paycode instance.

Parameters
  • account – The recipient account as an instance of fintech.sepa.Account. If you have international payers the corresponding BIC should be set.
  • purpose – The transaction purpose text. If the value matches a valid ISO creditor reference number (starting with “RF…”), it is added as a structured reference.
  • amount – The transaction amount as an instance of fintech.sepa.Amount, float or Decimal. In the latter two cases the currency is set to EUR.
  • purpose_code – The transaction purpose code.
create_image(size=None, border=4, save_as=None)

Creates an image of the EPC-QR-Code.

Parameters
  • size – The requested size of the QR-Code in pixels including borders. The image will not be created in exactly this size in order to avoid blurring. Therefore the dimensions may be slightly smaller or larger than requested. Without a given size the dimensions depend on the amount of data the QR-Code contains.
  • border – The border size around the QR-Code, represented by a factor of one box size (one dot of the QR-Code). The minimum value according to the specification is a factor of 4.
  • save_as – If given, it must be the destination path where to save the image. The extension of the file name determines the image format.
Returns
An instance of PIL.Image.
merge_pdf(pdf_file, pos, size, border=4, page=1, resolution=300, save_as=None)

Merges the EPC-QR-Code with an existing PDF document.

Parameters
  • pdf_file – The PDF document into which the QR-Code is to be inserted. Can be either the path or a binary file-like object. The source document is not modified.
  • pos – A tuple of (x, y) coordinates in inches, where to place the QR-Code on the document. Measured from the bottom left.
  • size – The size of the QR-Code in inches including borders.
  • border – The border size around the QR-Code, represented by a factor of one box size (one dot of the QR-Code). The minimum value according to the specification is a factor of 4.
  • page – The page number where to insert the QR-Code. First page is 1, last page is -1. A value of 0 adds the QR-Code to all pages.
  • resolution – The requested resolution of the QR-Code image in DPI. The final resolution can vary slightly in order to avoid blurring.
  • save_as – If given, it must be the destination path where to save the new PDF document.
Returns
The modified PDF document as bytes.
class fintech.invoicing.Entity(name, street, postcode, city, country, entity_id=None, commercial_reg_id=None, vat_id=None, tax_id=None, email=None, account=None)

Represents the seller, buyer or the shipment recipient required for e-invoices.

Initializes the Entity instance.

Parameters
  • name – The name of the organization or person.
  • street – The street address. Can be a string or a tuple of up to three strings.
  • postcode – The postcode of the address.
  • city – The city of the address.
  • country – The country code (ISO-3166 ALPHA 2).
  • entity_id – The entity id, eg. customer or supplier number (optional).
  • commercial_reg_id – The commercial registration id (optional).
  • vat_id – The VAT id (required for the seller if no tax id specified; always required for seller and buyer with a vat_flag of EXEMPTED_EU).
  • tax_id – The tax id (required for the seller if no VAT id specified).
  • email – The email address (required with XRECHNUNG-UBL if no endpoint ID specified, otherwise ignored; always ignored with PEPPOL and UBL).
  • account – The account as an instance of fintech.sepa.Account (required for the seller if payment method is set to credit transfer; required for seller and buyer if payment method is set to direct debit).
set_contact_details(name, email=None, phone=None)

Sets the personal contact details for this entity. For the seller all fields are required with XRECHNUNG and PEPPOL.

Parameters
  • name – The contact name.
  • email – The email address.
  • phone – The phone number.
set_endpoint_id(scheme_id, endpoint_id)

Sets the endpoint id for this entity (required with PEPPOL; required with XRECHNUNG-UBL if no email specified; ignored with FACTURX). For available EAS scheme ids see: https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/

Parameters
  • scheme_id – The EAS scheme id.
  • endpoint_id – The value of endpoint id.
class fintech.invoicing.Invoice(id, date, seller, buyer, total_net, total_gross, vat_totals, currency='EUR', vat_flag='EXCL', billing_period=None)

Invoice class (Factur-X / ZUGFeRD 2, XRechnung, PEPPOL or raw UBL)

Initializes the Invoice instance with TypeCode 380 (commercial invoice).

VAT handling and how to pass prices (parameter vat_flag):

  • EXCL: VAT is applied. Prices must be passed VAT excluded.
  • INCL: VAT is applied. Prices must be passed VAT included. Since e-invoices are based on net prices, this can result in rounding errors of 0.01 per line item. Therefore the extended level of factur-x is used which tolerates such discrepancies. Should be used for B2C only.
  • EXEMPTED_EU: Tax-free intra-community delivery within the EU. VAT is not applied. Prices must be passed VAT excluded.
  • EXEMPTED_NON_EU: Tax-free export delivery outside the EU. VAT is not applied. Prices must be passed VAT excluded.
  • SMB: Small business regulation in Germany. VAT is not applied.
Parameters
  • id – The invoice number [BT-1].
  • date – The invoice date [BT-2]. Can be a date object or an ISO8601 formatted string.
  • seller – The seller as an instance of Entity.
  • buyer – The buyer as an instance of Entity.
  • total_net – The total net amount of the invoice.
  • total_gross – The total gross amount of the invoice.
  • vat_totals – A dictionary of all VAT entries of the invoice. Keys represent the percentage rate and values the total amount of this specific VAT rate. VAT amounts must be calculated vertically based on the totaled net prices.
  • currency – The currency for this invoice [BT-5].
  • vat_flag – The VAT flag (see above) [BT-118] [BT-151] [BT-121] [BT-120].
  • billing_period – A 2-tuple of start date [BT-73] and end date [BT-74] which represents the billing period (optional).
add_item(title, quantity, price, vat_rate, item_id=None, description=None, unit_code='C62', billing_period=None, note=None)

Adds an item to the invoice.

Parameters
  • title – The item title [BT-153].
  • quantity – The quantity [BT-129].
  • price – The item price [BT-146] (either net or gross, depending on vat_flag).
  • vat_rate – The VAT rate [BT-152].
  • item_id – The item id/number [BT-155] (optional).
  • description – The item description [BT-154] (optional).
  • unit_code – The unit code [BT-130] (defaults to “C62”).
  • billing_period – A 2-tuple of start date [BT-134] and end date [BT-135] which represents the billing period (optional).
  • note – Invoice line note [BT-127] (optional).
add_note(note)

Adds a note to the invoice [BT-22].

merge_pdf(pdf_file, lang=None, save_as=None)

Merges the Factur-X invoice data with an existing PDF document.

Parameters
  • pdf_file – The PDF document. Can be either the path or a binary file-like object. The source document is not modified.
  • lang – ISO 639-1 language code of the invoice (optional).
  • save_as – If given, it must be the destination path where to save the new PDF document.
Returns
The merged PDF document as bytes.
render(format='FACTURX-CII')

Renders the invoice and returns the XML data as bytes. All amounts are checked for consistency (vertical VAT calculation). The following formats are supported (based on EN 16931):

  • FACTURX-CII: B2B/B2C (aka ZUGFeRD-2, can be merged with PDFs)
  • XRECHNUNG-CII: B2G (Germany)
  • XRECHNUNG-UBL: B2G (Germany)
  • PEPPOL-UBL: B2G (EU)
  • UBL: B2B (International)

CII: Cross Industrie Invoice, UBL: Universal Business Language

set_corrected_invoice(id, date)

Sets the reference to the corrected or canceled invoice in case of refunds. If the totals are negative, the TypeCode is set to 384 (corrected invoice). Otherwise the TypeCode is set to 381 (credit note).

Parameters
  • id – Number of corrected or canceled invoice [BT-25].
  • date – The date of the invoice [BT-26]. Can be a date object or an ISO8601 formatted string.
set_delivery_details(recipient=None, note_id=None, date=None)

Sets the delivery details.

Parameters
  • recipient – The recipient as an instance of Entity (optional).
  • note_id – The delivery note number [BT-16] (optional).
  • date – The shipping date [BT-72] (optional). Can be a date object or an ISO8601 formatted string.
set_payment_details(method_id, method_name=None, payment_terms=None, due_date=None, payment_ref=None, card_number=None, card_holder=None, amount_prepaid=0)

Sets the payment details.

Common payment methods:

  • 10: Cash
  • 58: Credit transfer (SEPA)
  • 59: Direct debit (SEPA)
  • 30: Credit transfer (non-SEPA)
  • 49: Direct debit (non-SEPA)
  • 54: Credit card
  • 55: Debit card
  • 48: Bank card (in general)
  • 68: Online payment service (eg. PayPal)
Parameters
  • method_id – The payment method id [BT-81]. This value is initially set to “1” (instrument not defined).
  • method_name – A short description of the billing method [BT-82] (optional, ignored with XRECHNUNG-UBL and PEPPOL-UBL).
  • payment_terms – The payment terms [BT-20] (defaults to “n/a”).
  • due_date – The due date of the invoice [BT-9]. Can be a date object or an ISO8601 formatted string. It is initially set to the invoice date.
  • payment_ref – The payment reference number which should be quoted by the buyer when initiating the payment [BT-83] (required for payments by credit transfer).
  • card_number – The shortened debit or credit card number [BT-87] (required for card payments).
  • card_holder – The name of the card holder [BT-88] (required for card payments).
  • amount_prepaid – Amount that has been already paid by the buyer [BT-113] (optional). This value will be substracted from the payable amount.
set_reference_numbers(seller_order_id=None, contract_id=None, project_id=None, buyer_ref=None, buyer_order_id=None, accounting_ref=None)

Sets some reference numbers.

Parameters
  • seller_order_id – The corresponding order id [BT-14] (optional).
  • contract_id – The corresponding contract id [BT-12] (optional).
  • project_id – The corresponding project id [BT-11] (optional).
  • buyer_ref – The corresponding buyer ref [BT-10] (required with XRECHNUNG and must be set to the route id [Leitweg-ID]).
  • buyer_order_id – The customer’s order id [BT-13] (optional).
  • accounting_ref – An accounting reference number from the customer [BT-19] (optional).
property typecode

The assigned typecode (read-only).