bench get-app https://github.com/Itaneo/erpnext-qonto

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Itaneo%2Ferpnext-qonto)](https://frappegems.com/gems/apps/Itaneo/erpnext-qonto)

Qonto Connector for ERPNext v15

Qonto Connector is a production-ready Frappe app that seamlessly syncs Qonto bank transactions into ERPNext v15, supporting multi-company and multi-account setups with API Key authentication.

🎯 Features

• ✅ ERPNext v15 Compatible - Built specifically for ERPNext v15 / Frappe v15
• 🔐 API Key Authentication - Secure authentication using Qonto API keys (no OAuth complexity)
• 🏢 Multi-Company Support - Manage transactions across multiple companies
• 💼 Multi-Account Support - Sync multiple Qonto bank accounts simultaneously
• 🔄 Automated Sync - Scheduled synchronization every 15 minutes (configurable)
• 📊 Transaction Management - Automatic creation of Bank Transaction records
• 🛡️ Idempotent Operations - Prevents duplicate transactions
• 📝 Comprehensive Logging - Detailed sync logs for debugging and auditing
• 🐳 Docker-First - Ready for containerized deployments
• 🧪 Test Coverage - Comprehensive test suite included

📋 Table of Contents

• Requirements
• Installation
• Configuration
• Usage
• API Endpoints
• Deployment
• Development
• Testing
• Troubleshooting
• Contributing
• License

🔧 Requirements

• Python: 3.10 or higher
• Frappe Framework: v15.x
• ERPNext: v15.x
• Qonto Account: Business account with API access

Dependencies

• requests>=2.28.0,<3.0.0 - HTTP library for API calls

📦 Installation

Method 1: Using bench (Recommended)

# Navigate to your Frappe bench directory
cd ~/frappe-bench

# Get the app from repository
bench get-app https://github.com/itaneo/qonto-connector.git

# Install the app on your site
bench --site your-site-name install-app qonto_connector

# Restart bench
bench restart

Method 2: Manual Installation

# Clone the repository
cd ~/frappe-bench/apps
git clone https://github.com/itaneo/qonto-connector.git

# Install dependencies
cd qonto-connector
pip install -r requirements.txt

# Install on site
cd ~/frappe-bench
bench --site your-site-name install-app qonto_connector

# Migrate
bench --site your-site-name migrate

# Restart
bench restart

Method 3: Docker Installation (Production)

This project uses the official frappe_docker pwd.yml configuration for production deployments.

Prerequisites: 1. Clone frappe_docker: git clone https://github.com/frappe/frappe_docker D:\ErpNext\frappe_docker 2. Docker and Docker Compose installed

Production Deployment:

Use the official frappe_docker pwd.yml file:

# Navigate to frappe_docker directory
cd D:\ErpNext\frappe_docker

# Deploy with pwd.yml
docker compose -f pwd.yml up -d

# Wait for services to be ready
docker compose -f pwd.yml logs -f create-site

# Install qonto_connector app
docker compose -f pwd.yml exec backend bash
cd /home/frappe/frappe-bench

# Option 1: Install from git (recommended)
bench get-app https://github.com/YOUR-USERNAME/qonto_connector
bench --site frontend install-app qonto_connector

# Option 2: Install from local directory (development)
# First, copy your app to the container
exit
docker cp D:\ErpNext\erpnext-qonto backend:/home/frappe/frappe-bench/apps/qonto_connector
docker compose -f pwd.yml exec backend bash
bench --site frontend install-app qonto_connector

Configuration Notes: - The pwd.yml file is maintained by the frappe_docker project - Default credentials: admin/admin - Default database password: admin - Site name: frontend - Accessible at: http://localhost:8080

For private repositories, create an apps.json file:

[
  {
    "url": "https://{{PAT}}@github.com/YOUR-ORG/qonto_connector.git",
    "branch": "main"
  }
]

Benefits of this approach: - ✅ Production-tested configuration - Uses official frappe_docker setup - ✅ No custom image building - Uses official images directly - ✅ Community-maintained - Updated with Frappe releases - ✅ Standardized deployment - Consistent with Frappe best practices

⚙️ Configuration

Step 1: Get Qonto API Credentials

1. Log in to your Qonto account
2. Navigate to Settings → API & Integrations
3. Create a new API key with the following permissions:
   • transactions:read
   • organization:read
4. Save your Organization Slug (Login) and Secret Key

Step 2: Configure Qonto Settings

1. Open ERPNext and navigate to:

   Home → Qonto Connector → Qonto Settings
   

2. Fill in the configuration:

   • Environment: Choose Sandbox for testing or Production for live data
   • API Login: Your Qonto organization slug
   • API Secret Key: Your Qonto secret key
   • Sync Interval: How often to sync (default: 15 minutes)
   • Default Lookback Days: How many days to look back on first sync (default: 90)

3. Click Test Connection to verify credentials

Step 3: Set Up Account Mappings

1. After successful connection, click Fetch Accounts to see your Qonto bank accounts

2. In the Account Mappings table, add a row for each account you want to sync:

   • Company: Select the ERPNext company
   • Qonto Account ID: The Qonto account slug (from Fetch Accounts)
   • ERPNext Bank Account: The corresponding Bank Account in ERPNext
   • Active: Check to enable syncing for this account

3. Click Save

Step 4: Verify Setup

1. Click Sync Now to trigger an immediate synchronization
2. Navigate to Banking → Bank Transaction to see synced transactions
3. Check Qonto Sync Log for detailed sync information

🚀 Usage

Automatic Synchronization

Once configured, Qonto Connector automatically syncs transactions every 15 minutes (configurable). No manual intervention is required.

Manual Synchronization

To manually trigger a sync:

1. Navigate to Qonto Settings
2. Click Actions → Sync Now
3. The sync will run in the background

View Sync Status

1. Navigate to Qonto Settings
2. Click Actions → View Sync Status
3. See current sync status and recent logs

Managing Transactions

Synced transactions appear in:

Home → Banking → Bank Transaction

Each transaction includes: - Date: Transaction posting date - Bank Account: Linked ERPNext bank account - Company: Associated company - Description: Transaction details - Deposit/Withdrawal: Transaction amount - Qonto Transaction ID: Unique identifier (custom field) - Qonto Data: Raw API response (custom field, hidden)

Reconciliation

Use ERPNext's standard bank reconciliation tools:

Home → Banking → Bank Reconciliation Tool

The connector creates draft Bank Transaction records. You can: 1. Review and verify transactions 2. Match with payment entries 3. Submit transactions after reconciliation

🚢 Deployment

For detailed deployment instructions and production best practices, see DEPLOYMENT.md.

Quick Deployment Options

Production (Recommended):

# Use official frappe_docker pwd.yml configuration
cd D:\ErpNext\frappe_docker
docker compose -f pwd.yml up -d

Development:

# Use PowerShell scripts for local setup
.\tools\setup-erpnext-docker.ps1

See DEPLOYMENT.md for: - Using frappe_docker pwd.yml for production - Backup and restore procedures - Production best practices - Complete troubleshooting guide

🔌 API Endpoints

The app exposes the following whitelisted API endpoints:

Test Connection

frappe.call({
    method: 'qonto_connector.api.v1.test_connection',
    callback: function(r) {
        console.log(r.message);
    }
});

Fetch Accounts

frappe.call({
    method: 'qonto_connector.api.v1.fetch_accounts',
    callback: function(r) {
        console.log(r.message.accounts);
    }
});

Trigger Sync

frappe.call({
    method: 'qonto_connector.api.v1.sync_now',
    callback: function(r) {
        console.log(r.message);
    }
});

Get Sync Status

frappe.call({
    method: 'qonto_connector.api.v1.get_sync_status',
    callback: function(r) {
        console.log(r.message);
    }
});

💻 Development

Project Structure

qonto_connector/
├── qonto/                      # Core business logic
│   ├── client.py              # Qonto API client
│   ├── sync.py                # Sync engine
│   ├── mapping.py             # Transaction mapping
│   ├── utils.py               # Utility functions
│   ├── constants.py           # Constants
│   └── exceptions.py          # Custom exceptions
├── api/                       # REST API endpoints
│   └── v1.py                  # API v1
├── qonto_connector/           # Module directory
│   └── doctype/               # DocTypes
│       ├── qonto_settings/
│       ├── qonto_account_mapping/
│       └── qonto_sync_log/
├── config/                    # App configuration
├── public/                    # Static assets
│   ├── css/
│   ├── js/
│   └── images/
├── tests/                     # Test suite
└── hooks.py                   # Frappe hooks

Local Development Setup

# Clone the repository
git clone https://github.com/itaneo/qonto-connector.git
cd qonto-connector

# Create virtual environment (optional)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
cd ~/frappe-bench
bench --site development.localhost install-app qonto_connector

# Enable developer mode
bench --site development.localhost set-config developer_mode 1

# Watch for changes
bench watch

Code Style

This project follows standard Python coding conventions:

• PEP 8 style guide
• Type hints for better code clarity
• Docstrings for all public functions and classes
• Black for code formatting (line length: 100)
• isort for import sorting

# Format code
black qonto_connector --line-length 100
isort qonto_connector --profile black

🧪 Testing

Run Tests

# Run all tests
cd ~/frappe-bench
bench --site test_site run-tests --app qonto_connector

# Run specific test file
bench --site test_site run-tests --app qonto_connector --module qonto_connector.tests.test_client

# Run with coverage
bench --site test_site run-tests --app qonto_connector --coverage

Test Structure

• tests/conftest.py - Pytest fixtures
• tests/test_client.py - API client tests
• tests/test_sync.py - Sync engine tests
• tests/test_mapping.py - Transaction mapping tests

🔍 Troubleshooting

Connection Issues

Problem: "Invalid API credentials" error

Solution: 1. Verify your API Login (organization slug) is correct 2. Ensure API Secret Key is valid and not expired 3. Check you're using the correct environment (Sandbox vs Production)

Sync Not Working

Problem: Transactions not syncing automatically

Solution: 1. Check if scheduler is enabled: bench --site your-site enable-scheduler 2. Verify account mappings are Active 3. Check Qonto Sync Log for error messages 4. Ensure Bank Account is linked correctly

Duplicate Transactions

Problem: Same transaction appearing multiple times

Solution: - The app includes duplicate prevention. If you see duplicates: 1. Check if transactions have different Qonto Transaction IDs 2. Verify the qonto_id