Invoice Processing ================== Starting with Aiviro version 3.28.0, we've introduced an improved invoice processing system that makes extracting data from invoices simpler and more powerful than ever. Action ------ .. autoclass:: aiviro.actions.reader.ProcessInvoice :members: .. note:: The legacy InvoiceReader is still available via :ref:`invoice-reader` for backward compatibility. Data Structure -------------- Below are the detailed data models that represent the structured information extracted from invoices by the Aiviro processing system. These models define all the fields and their types that you can access after processing an invoice. .. list-table:: InvoiceData :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - customer - :class:`~.InvoiceEntityV2` - Customer details including name, tax ID, address, etc. * - vendor - :class:`~.InvoiceVendorV2` - Vendor details including name, tax ID, address, etc. * - shipping_address - :class:`~.InvoiceAddressV2` - Shipping address information if different from customer address * - shipping_address_recipient - :class:`str` - Name associated with the shipping address * - invoice_id - :class:`str` - Unique identifier/number of the invoice * - invoice_date - :class:`datetime.date` - Date when the invoice was issued * - due_date - :class:`datetime.date` - Date payment for this invoice is due * - tax_date - :class:`datetime.date` - Date the tax was applied to the invoice * - order_number - :class:`list`, :class:`str` - List of order reference numbers * - primary_total - :class:`~.InvoiceTotalsV2` - Main invoice totals in the primary currency (e.g., EUR for international transactions) * - secondary_total - :class:`~.InvoiceTotalsV2` - Additional invoice totals in a secondary currency (e.g., CZK for Czech invoices that also show amounts in local currency) * - exchange_rate - :class:`decimal.Decimal` - Exchange rate between primary and secondary currency * - vat_rate - :class:`decimal.Decimal` - VAT rate applied to the invoice * - variable_symbol - :class:`str` - Variable symbol of the invoice * - payment_term - :class:`str` - The terms of payment for the invoice * - bank_accounts - :class:`list`, :class:`~.InvoiceBankAccountV2` - List of bank accounts for payment * - items - :class:`list`, :class:`~.InvoiceItemV2` - List of invoice line items, filtered by totals * - raw_items - :class:`list`, :class:`~.InvoiceItemV2` - List of unfiltered invoice line items .. list-table:: InvoiceEntityV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - name - :class:`str` - Name of the entity (company or person) * - id - :class:`str` - Entity reference ID * - tax_id - :class:`str` - The taxpayer number (VAT ID) * - address - :class:`~.InvoiceAddressV2` - Mailing address * - address_recipient - :class:`str` - Name associated with the address * - ico - :class:`str` - The Czech company ID number .. list-table:: InvoiceVendorV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - is_not_tax_payer - :class:`bool` - Indicates if the vendor is not a tax payer * - *Inherits all attributes from InvoiceEntity* - - .. list-table:: InvoiceAddressV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - house_number - :class:`str` - House number * - road - :class:`str` - Street/road name * - city - :class:`str` - City name * - postal_code - :class:`str` - Postal code * - street_address - :class:`str` - Full street address (combined road and house number) * - country_code_A3 - :class:`str` - Country code in alpha-3 format (3 letters), e.g., CZE, DEU, AUT, SVK .. list-table:: InvoiceTotalsV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - total_amount - :class:`decimal.Decimal` - Total gross amount of the invoice * - total_amount_without_tax - :class:`decimal.Decimal` - Total net amount of the invoice (without tax) * - total_tax - :class:`decimal.Decimal` - Total tax amount of the invoice * - amount_due - :class:`decimal.Decimal` - Amount due for payment * - currency - :class:`decimal.Decimal` - Currency code (e.g., EUR, USD, CZK) .. list-table:: InvoiceBankAccountV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - iban - :class:`str` - IBAN of the bank account * - swift - :class:`str` - SWIFT/BIC code of the bank * - bank_name - :class:`str` - Name of the bank * - country_code - :class:`str` - Country code in alpha-2 format (e.g., CZ, DE, AT) * - local_account - :class:`~.LocalBankAccountV2` - Local bank account details .. list-table:: LocalBankAccountV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - bank_code - :class:`str` - Bank code * - account_number - :class:`str` - Account number * - account_prefix - :class:`str` - Account prefix .. list-table:: InvoiceItemV2 :widths: 25 25 50 :header-rows: 1 :class: tight-table * - Attribute - Type - Description * - index - :class:`int` - Line item index * - content - :class:`str` - Full text of the line item * - description - :class:`str` - Description of the item * - quantity - :class:`decimal.Decimal` - Quantity of the item * - unit_price - :class:`decimal.Decimal` - Price per unit * - unit - :class:`str` - Unit of measurement (e.g., kg, pcs) * - product_code - :class:`str` - Product code/SKU * - amount - :class:`decimal.Decimal` - Total gross amount for the line item * - amount_without_tax - :class:`decimal.Decimal` - Total net amount for the line item * - amount_tax - :class:`decimal.Decimal` - Tax amount for the line item * - tax_rate - :class:`decimal.Decimal` - Tax rate percentage Simplified Data Access ~~~~~~~~~~~~~~~~~~~~~~ The :class:`~.InvoiceDataV2` class provides a convenient :meth:`~.InvoiceDataV2.dump_to_values` method that converts the entire object into a simple dictionary containing only the actual values, without the additional metadata from the :class:`~.FieldDataV2` wrapper: .. code-block:: python # Convert to a plain dictionary with just the values simple_data = result.dump_to_values() # Access data directly with standard dictionary syntax vendor_name = simple_data.get("vendor", {}).get("name") total_amount = simple_data.get("primary_total", {}).get("total_amount") print(f"Vendor Name: {vendor_name}") print(f"Total Amount: {total_amount}") .. automodule:: aiviro.core.utils.api_client.schemas.reader :members: InvoiceDataV2, InvoiceEntityV2, InvoiceVendorV2, InvoiceAddressV2, InvoiceTotalsV2, InvoiceBankAccountV2, InvoiceItemV2, LocalBankAccountV2, FieldDataV2