npm package: @general-dexterity/n8n-nodes-qonto
Description: Unofficial n8n community node for Qonto Business API integration. Not affiliated with or endorsed by Qonto.
Author: Aliou Diallo
Latest version: 0.4.0

# n8n-nodes-qonto

[![NPM Version](https://img.shields.io/npm/v/@general-dexterity/n8n-nodes-qonto.svg)](https://www.npmjs.com/package/@general-dexterity/n8n-nodes-qonto)
[![NPM Downloads](https://img.shields.io/npm/dt/@general-dexterity/n8n-nodes-qonto.svg)](https://www.npmjs.com/package/@general-dexterity/n8n-nodes-qonto)

This is an n8n community node. It lets you use Qonto in your n8n workflows.

Qonto is a business finance solution that simplifies banking, bookkeeping, and expense management for SMEs and freelancers. It provides powerful APIs for managing invoices, transactions, and financial data.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

**Note:** This is a custom n8n node developed by General Dexterity and is not officially affiliated with or endorsed by Qonto.

## Table of Contents

- [Installation](#installation)
- [Operations](#operations)
- [Credentials](#credentials)
- [Compatibility](#compatibility)
- [Usage](#usage)
- [Resources](#resources)
- [Version History](#version-history)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

### Quick Installation

1. In n8n, go to **Settings** > **Community Nodes**
2. Select **Install a community node**
3. Enter `@general-dexterity/n8n-nodes-qonto`
4. Select **Install**

### Manual Installation (self-hosted)

```bash
npm install @general-dexterity/n8n-nodes-qonto
```

After installation, restart your n8n instance.

## Operations

This node supports operations for 20 different Qonto API resources:

### Attachment
- **Get Many**: Retrieve attachments for a specific transaction
- **Get One**: Retrieve a single attachment by ID

### Beneficiary  
- **Get Many**: Retrieve multiple beneficiaries with filtering
  - Filter by trusted status, status (pending/validated/declined), IBAN, and update timestamps
- **Get One**: Retrieve a single beneficiary by ID

### Business Account
- **Get Many**: Retrieve all business accounts
- **Get One**: Retrieve a single business account by ID

### Card
- **Get Many**: Retrieve all cards (physical and virtual)
- **Get One**: Retrieve a single card by ID

### Client
- **Get Many**: Retrieve multiple clients with filtering
  - Filter by tax ID, VAT number, email, or name
- **Get One**: Retrieve a single client by ID

### Client Invoice
- **Get Many**: Retrieve multiple client invoices with filtering and pagination
  - Filter by status (draft, unpaid, canceled, paid)
  - Filter by date range (created from/to)
  - Sort by creation date (ascending or descending)
- **Get One**: Retrieve a single client invoice by ID

### Credit Note
- **Get Many**: Retrieve multiple credit notes with date filtering
- **Get One**: Retrieve a single credit note by ID

### External Transfer
- **Get Many**: Retrieve multiple external transfers with extensive filtering
  - Filter by status, beneficiary IDs, and date ranges
- **Get One**: Retrieve a single external transfer by ID

### Insurance Contract
- **Get Many**: Retrieve all insurance contracts
- **Get One**: Retrieve a single insurance contract by ID

### Internal Transfer
- **Get Many**: Retrieve all internal transfers
- **Get One**: Retrieve a single internal transfer by ID

### Label
- **Get Many**: Retrieve all labels for categorization
- **Get One**: Retrieve a single label by ID

### Membership
- **Get Many**: Retrieve all memberships
- **Get Current**: Retrieve the current user's membership

### Organization
- **Get**: Retrieve organization details

### Quote
- **Get Many**: Retrieve multiple quotes with filtering
  - Filter by status (pending_approval/approved/canceled) and creation date
- **Get One**: Retrieve a single quote by ID

### Request
- **Get Many**: Retrieve multiple requests with filtering
  - Filter by status, request type, creation and processing dates
- **Get One**: Retrieve a single request by ID

### SEPA Transfer
- **Get Many**: Retrieve SEPA transfers
- **Get One**: Retrieve a single SEPA transfer
- **Get Recurring Transfers**: List recurring SEPA transfers
- **Get Single Recurring Transfer**: Get one recurring transfer
- **Get Bulk Transfers**: List bulk SEPA transfers  
- **Get Single Bulk Transfer**: Get one bulk transfer
- **Get SEPA Beneficiaries**: List SEPA beneficiaries
- **Get Single SEPA Beneficiary**: Get one SEPA beneficiary

### Statement
- **Get Many**: Retrieve multiple statements with filtering
  - Filter by bank account IDs, IBANs, and period ranges
- **Get One**: Retrieve a single statement by ID

### Supplier Invoice
- **Get Many**: Retrieve multiple supplier invoices with filtering
  - Filter by status (to_review/pending/scheduled/paid) and creation date
- **Get One**: Retrieve a single supplier invoice by ID

### Team
- **Get Many**: Retrieve all teams
- **Get One**: Retrieve a single team by ID

### Transaction
- **Get Many**: Retrieve multiple transactions with filtering and bank account selection
  - Required bank account selection
  - Filter by status (completed/pending/declined) and date range
  - Pagination support
- **Get One**: Retrieve a single transaction by ID

## Credentials

### Prerequisites

1. You need a Qonto business account. Sign up at [qonto.com](https://qonto.com)
2. Ensure you have the necessary permissions to access API features or create OAuth applications

### Authentication Methods

This node supports the following authentication methods:

#### API Key Authentication
1. Log in to your Qonto account
2. Navigate to **Settings** > **API Integration**
3. Click **Generate API Key**
4. Set the required permissions for your use case
5. Copy the generated login and secret key
6. In n8n, add new Qonto API Key credentials:
   - **Environment**: Select Production or Sandbox (default: Production)
   - **Login**: Your Qonto login (from step 5)
   - **Secret Key**: Your generated secret key (from step 5)

#### OAuth2 Authentication
1. Log in to your Qonto account
2. Navigate to the OAuth applications section
3. Register a new OAuth application
4. Set the redirect URI to your n8n OAuth callback URL
5. Copy the Client ID and Client Secret
6. In n8n, add new Qonto OAuth2 credentials:
   - **Environment**: Select Production or Sandbox (default: Production)
   - **Client ID**: Your OAuth application's Client ID
   - **Client Secret**: Your OAuth application's Client Secret
   - **Scopes**: Set the required permissions for your use case. Common scopes include:
     - `organization.read` (organization details)
     - `client_invoices.read` (client invoices)
     - `transactions.read` (transaction data)
     - `beneficiaries.read` (beneficiary data)
     - Additional scopes based on the resources you need
7. Complete the OAuth authorization flow when prompted

### Environment Selection

Both authentication methods support environment selection:

- **Production** (default): Uses the live Qonto API
  - API Base URL: `https://thirdparty.qonto.com`
  - OAuth URLs: `https://oauth.qonto.com`
- **Sandbox**: Uses the testing environment for development and testing
  - API Base URL: `https://thirdparty-sandbox.qonto.com`
  - OAuth URLs: `https://oauth-sandbox.qonto.com`

**Important**: Make sure to select the correct environment that matches your Qonto account and use case. Sandbox credentials will not work with the production environment and vice versa.

## Compatibility

- **Minimum n8n version**: 1.0.0
- **Tested up to**: 1.0.0

### Known Issues
- None reported at this time

## Usage

### Example: Get Client Invoices

1. Add the Qonto node to your workflow
2. Select the "Client Invoice" resource
3. Choose the "Get Many" operation
4. Configure the optional filters:
   - **Status**: Select invoice status to filter by
   - **Created From**: Set a start date for the date range filter
   - **Created To**: Set an end date for the date range filter
5. Configure pagination:
   - **Return All**: Toggle to get all results or limit to specific number
   - **Limit**: Number of invoices per request (if Return All is false)
6. Execute the node

### Example: Get Transactions

1. Add the Qonto node to your workflow  
2. Select the "Transaction" resource
3. Choose the "Get Many" operation
4. **Select Bank Account**: Choose which bank account to retrieve transactions from
5. Configure optional filters:
   - **Status**: Filter by transaction status (completed/pending/declined)
   - **Date From/To**: Set date range for filtering
6. Configure pagination and sorting options
7. Execute the node

### Example: Get Organization Details

1. Add the Qonto node to your workflow
2. Select the "Organization" resource  
3. Choose the "Get" operation (only operation available)
4. Execute the node to retrieve organization information

### Tips and Best Practices

- **Pagination**: Use "Return All" for complete datasets or set appropriate limits to avoid timeouts
- **Bank Account Selection**: Transaction operations require selecting a specific bank account first
- **Date Filtering**: All date filters use ISO 8601 format (YYYY-MM-DD)
- **Resource Selection**: Choose the most specific resource for your needs (e.g., use Client Invoice instead of generic data)
- **Filtering**: Use filters to reduce API calls and improve performance
- **Rate Limits**: The API has rate limits; use pagination and avoid excessive concurrent requests

### Common Issues

**Error: "Authentication failed"**
- Solution: Verify your API credentials are correct and have the necessary permissions for the selected resource

**Error: "Unknown resource"**  
- Solution: Ensure you're using a supported resource name and the node version supports it

**Error: "Bank account required"**
- Solution: Select a bank account when using Transaction operations

**Error: "Invalid date format"**
- Solution: Ensure dates are in YYYY-MM-DD format

**Error: "Resource not found"**
- Solution: Check that the ID exists and you have permission to access the resource

## Resources

* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
* [Qonto API documentation](https://docs.qonto.com/api-reference/business-api)
* [Qonto OAuth documentation](https://docs.qonto.com/api-reference/business-api/authentication/oauth/oauth-flow)
* [Qonto Sandbox Environment](https://docs.qonto.com/api-reference/business-api/urls#sandbox)
* [Qonto official website](https://qonto.com)

## Version History

### 0.2.0 (Major Expansion)
- Added support for 19 additional Qonto API resources
- Complete architecture refactoring for better maintainability
- Enhanced OAuth2 configuration and security
- Improved error handling and pagination across all resources

### 0.1.0 (Initial Release)
- Initial release with Client Invoice operations
- Support for API Key and OAuth2 authentication
- Get Many operation with filtering and pagination