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

class aiviro.actions.reader.ProcessInvoice(filepath: Path | str)

Process invoice documents and extract structured data.

This action processes PDF invoice documents and returns a structured DocumentInvoiceV2 object containing comprehensive information including vendor details, customer data, line items, payment information, and more.

Parameters:

filepath – Path to the invoice PDF file to process

Returns:

DocumentInvoiceV2 object containing size unit, page-size, and the extracted invoice data

Example:

>>> from aiviro.actions import ProcessInvoice
>>> from aiviro.core.utils.api_client.schemas.reader import InvoiceDataV2, DocumentInvoiceV2
>>>
>>> invoice_path = "path/to/invoice.pdf"
>>> process_invoice = ProcessInvoice(filepath=invoice_path)
>>> result: DocumentInvoiceV2 = process_invoice()
>>> inv_data: InvoiceDataV2 = result.invoice_data
>>>
>>> # Access extracted data
>>> print(f"Vendor: {inv_data.vendor.name.value}")
>>> print(f"Total Amount: {inv_data.primary_total.total_amount.value}")

Note

The legacy InvoiceReader is still available via 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.

InvoiceData

Attribute

Type

Description

customer

InvoiceEntityV2

Customer details including name, tax ID, address, etc.

vendor

InvoiceVendorV2

Vendor details including name, tax ID, address, etc.

shipping_address

InvoiceAddressV2

Shipping address information if different from customer address

shipping_address_recipient

str

Name associated with the shipping address

invoice_id

str

Unique identifier/number of the invoice

invoice_date

datetime.date

Date when the invoice was issued

due_date

datetime.date

Date payment for this invoice is due

tax_date

datetime.date

Date the tax was applied to the invoice

order_number

list, str

List of order reference numbers

primary_total

InvoiceTotalsV2

Main invoice totals in the primary currency (e.g., EUR for international transactions)

secondary_total

InvoiceTotalsV2

Additional invoice totals in a secondary currency (e.g., CZK for Czech invoices that also show amounts in local currency)

exchange_rate

decimal.Decimal

Exchange rate between primary and secondary currency

vat_rate

decimal.Decimal

VAT rate applied to the invoice

variable_symbol

str

Variable symbol of the invoice

payment_term

str

The terms of payment for the invoice

bank_accounts

list, InvoiceBankAccountV2

List of bank accounts for payment

items

list, InvoiceItemV2

List of invoice line items, filtered by totals

raw_items

list, InvoiceItemV2

List of unfiltered invoice line items

InvoiceEntityV2

Attribute

Type

Description

name

str

Name of the entity (company or person)

id

str

Entity reference ID

tax_id

str

The taxpayer number (VAT ID)

address

InvoiceAddressV2

Mailing address

address_recipient

str

Name associated with the address

ico

str

The Czech company ID number

InvoiceVendorV2

Attribute

Type

Description

is_not_tax_payer

bool

Indicates if the vendor is not a tax payer

Inherits all attributes from InvoiceEntity

InvoiceAddressV2

Attribute

Type

Description

house_number

str

House number

road

str

Street/road name

city

str

City name

postal_code

str

Postal code

street_address

str

Full street address (combined road and house number)

country_code_A3

str

Country code in alpha-3 format (3 letters), e.g., CZE, DEU, AUT, SVK

InvoiceTotalsV2

Attribute

Type

Description

total_amount

decimal.Decimal

Total gross amount of the invoice

total_amount_without_tax

decimal.Decimal

Total net amount of the invoice (without tax)

total_tax

decimal.Decimal

Total tax amount of the invoice

amount_due

decimal.Decimal

Amount due for payment

currency

decimal.Decimal

Currency code (e.g., EUR, USD, CZK)

InvoiceBankAccountV2

Attribute

Type

Description

iban

str

IBAN of the bank account

swift

str

SWIFT/BIC code of the bank

bank_name

str

Name of the bank

country_code

str

Country code in alpha-2 format (e.g., CZ, DE, AT)

local_account

LocalBankAccountV2

Local bank account details

LocalBankAccountV2

Attribute

Type

Description

bank_code

str

Bank code

account_number

str

Account number

account_prefix

str

Account prefix

InvoiceItemV2

Attribute

Type

Description

index

int

Line item index

content

str

Full text of the line item

description

str

Description of the item

quantity

decimal.Decimal

Quantity of the item

unit_price

decimal.Decimal

Price per unit

unit

str

Unit of measurement (e.g., kg, pcs)

product_code

str

Product code/SKU

amount

decimal.Decimal

Total gross amount for the line item

amount_without_tax

decimal.Decimal

Total net amount for the line item

amount_tax

decimal.Decimal

Tax amount for the line item

tax_rate

decimal.Decimal

Tax rate percentage

Simplified Data Access

The InvoiceDataV2 class provides a convenient dump_to_values() method that converts the entire object into a simple dictionary containing only the actual values, without the additional metadata from the FieldDataV2 wrapper:

# 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}")
pydantic model aiviro.core.utils.api_client.schemas.reader.FieldDataV2
field page_index: int = -1
field value: T | None = None
field value_type: str = ''
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceItemV2
field amount: FieldDataV2[Decimal] | None = None
field amount_tax: FieldDataV2[Decimal] | None = None
field amount_without_tax: FieldDataV2[Decimal] | None = None
field content: FieldDataV2[str] | None = None
field description: FieldDataV2[str] | None = None
field index: int [Required]
field product_code: FieldDataV2[str] | None = None
field quantity: FieldDataV2[Decimal] | None = None
field tax_rate: FieldDataV2[Decimal] | None = None
field unit: FieldDataV2[str] | None = None
field unit_price: FieldDataV2[Decimal] | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.LocalBankAccountV2
field account_code: FieldDataV2[str] | None = None
field account_prefix: FieldDataV2[str] | None = None
field bank_code: FieldDataV2[str] | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceBankAccountV2
field bank_name: FieldDataV2[str] | None = None
field country_code: FieldDataV2[str] | None = None
field iban: FieldDataV2[str] | None = None
field local_account: LocalBankAccountV2 | None = None
field swift: FieldDataV2[str] | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceTotalsV2
field amount_due: FieldDataV2[Decimal] | None = None
field currency: FieldDataV2[str] | None = None
field total_amount: FieldDataV2[Decimal] | None = None
field total_amount_without_tax: FieldDataV2[Decimal] | None = None
field total_tax: FieldDataV2[Decimal] | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceAddressV2
field country_code_A3: str | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceEntityV2
field address: InvoiceAddressV2 | None = None
field address_recipient: FieldDataV2[str] | None = None
field ico: FieldDataV2[str] | None = None
field id: FieldDataV2[str] | None = None
field name: FieldDataV2[str] | None = None
field tax_id: FieldDataV2[str] | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceVendorV2
field is_not_tax_payer: FieldDataV2[bool] | None = None
pydantic model aiviro.core.utils.api_client.schemas.reader.InvoiceDataV2
field bank_accounts: list[InvoiceBankAccountV2] [Optional]
field customer: InvoiceEntityV2 | None = None
field due_date: FieldDataV2[date] | None = None
field exchange_rate: FieldDataV2[Decimal] | None = None
field invoice_date: FieldDataV2[date] | None = None
field invoice_id: FieldDataV2[str] | None = None
field items: list[InvoiceItemV2] [Optional]
field order_number: list[FieldDataV2[str]] [Optional]
field payment_term: FieldDataV2[str] | None = None
field primary_total: InvoiceTotalsV2 | None = None
field raw_items: list[InvoiceItemV2] [Optional]
field secondary_total: InvoiceTotalsV2 | None = None
field shipping_address: InvoiceAddressV2 | None = None
field shipping_address_recipient: FieldDataV2[str] | None = None
field tax_date: FieldDataV2[date] | None = None
field variable_symbol: FieldDataV2[str] | None = None
field vat_rate: FieldDataV2[Decimal] | None = None
field vendor: InvoiceVendorV2 | None = None
dump_to_values() dict[str, Any]

Creates a dictionary of basic data-type values without additional information of value_type or page_index.

Returns:

Dictionary of attribute_name as a key and its simple value as value.

Example:

>>> from aiviro.core.utils.api_client.schemas.reader import InvoiceDataV2, FieldDataV2
>>> inv_d = InvoiceDataV2(
...     customer=InvoiceEntityV2(name=FieldDataV2(value="John Doe", value_type="str", page_index=0)),
...     due_date=FieldDataV2(value=datetime.date(2022, 11, 11), value_type="datetime.date", page_index=0),
...     invoice_id=FieldDataV2(value="INV-12345", value_type="str", page_index=0),
...     order_number=[
...         FieldDataV2(value="12345", value_type="str", page_index=0),
...         FieldDataV2(value="67890", value_type="str", page_index=0)
...     ]
... )
>>> print(inv_d.dump_to_values())
... #{
... #   'customer': 'John Doe',
... #   'due_date': datetime.date(2022, 11, 11),
... #   'invoice_id': 'INV-12345',
... #   'order_number': ['12345', '67890'],
... #}