Beancount CaixaBank Importer

beancount-caixabank provides a Beancount importer for converting CaixaBank Excel statement exports to the Beancount format.

Features

• Format Support: Handles CaixaBank Excel exports (.xls and .xlsx)
• Robust Parsing:
  • Flexible header detection (handles statements with metadata rows)
  • Supports both Excel date serial numbers and DD/MM/YYYY string dates
  • European number format parsing (comma as decimal, dot as thousands separator)
• Full Beancount Integration: Creates proper transactions with metadata, payee, and narration

Installation

pip install beancount-caixabank

Usage

Getting Your CaixaBank Statement

1. Log in to CaixaBank online
2. Navigate to your account
3. Export statement as Excel file (.xls or .xlsx)
4. The file should contain columns: Fecha, Fecha valor, Movimiento, Más datos, Importe, Saldo

Beancount 3.x

Beancount 3.x uses a script-based workflow. Create an import.py file in your Beancount directory:

from beancount_caixabank import CaixaBankImporter
from beangulp import Ingest

importers = [
    CaixaBankImporter('Assets:CaixaBank:Checking'),
]

if __name__ == '__main__':
    ingest = Ingest(importers)
    ingest()

Then run:

python import.py extract path/to/statement.xls

Beancount 2.x

Add the following to your config.py:

from beancount_caixabank import CaixaBankImporter

CONFIG = [
    CaixaBankImporter('Assets:CaixaBank:Checking'),
]

Configuration

Account Name

The importer requires you to specify the Beancount account name where transactions will be imported:

CaixaBankImporter('Assets:MyBank:CaixaBank:Main')

Example Configuration

For a typical Beancount 3.x setup:

from beancount_caixabank import CaixaBankImporter
from beangulp import Ingest

importers = [
    CaixaBankImporter('Assets:CaixaBank:Checking'),
    CaixaBankImporter('Assets:CaixaBank:Savings'),
]

if __name__ == '__main__':
    ingest = Ingest(importers)
    ingest()

File Format

CaixaBank Excel statements should contain the following columns:

Note: The importer automatically detects the header row, so metadata rows before the headers are handled correctly.

Development

Prerequisites

• Python 3.9 or higher
• uv - Fast Python package installer and resolver

Setup

1. Clone the repository:

   git clone https://github.com/rogiia/beancount-caixabank
   cd beancount-caixabank
   

2. Install dependencies:

   uv sync
   

3. Run tests:

   uv run pytest
   

4. Run linting:

   uv run task lint
   

Using a Python environment

If you prefer to use a specific Python version:

uv sync --python 3.11

Testing

The importer includes comprehensive tests covering:

• File identification and validation
• Single and multiple transaction extraction
• Date parsing (string and Excel formats)
• European number format parsing
• Edge cases and error handling

Run the test suite with:

uv run pytest

Or with verbose output:

uv run pytest -v

Contributing

Contributions are welcome! Please feel free to submit a PR.

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Disclaimer

This importer is provided as-is. Always verify imported transactions against your bank statements to ensure accuracy.

Support

For issues, questions, or suggestions, please create an issue on the GitHub repository.

Related Projects

• Beancount - Command-line accounting system
• beancount-n26 - N26 bank importer
• beangulp - Beancount importer framework