qonto-split

Automatically split your Qonto incomes into an internal account.
Report Bug · Request Modification

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • 1. Installation
   • 2. Environment variables
   • 3. Setup
   • 4. Manual Run
   • 5. Scheduled Run (Cron-like)
3. Commands
   • qonto:watch - Manage watched accounts
   • qonto:exclude - Manage excluded accounts
4. Contact

About The Project

Qonto Split is a tool that automatically distributes your Qonto account’s income into an internal account.

The initial purpose was to allocate incoming VAT amounts to a sub-account to prevent excessive cash flow usage and ensure a constant provision for its payment. However, it can also be used to allocate a fixed percentage of an incoming amount (a different calculation than VAT). This feature is not available on Qonto.

Built With

• 
• 

(back to top)

Getting Started

Follow the step-by-step guide below to start using qonto-split.

Prerequisites

We ❤️ pnpm for managing project dependencies. You can install it using npm or yarn. If you don’t have it, use the following command or refer to the pnpm documentation for more information.

npm install -g pnpm@latest-10

1. Installation

Run the following commands to get the project on your machine:

1. Clone the repo (using HTTPS or SSH)

   git clone https://github.com/underscore-blank/qonto-split.git

2. Go to the project directory

   cd qonto-split

3. Install packages dependencies

   pnpm install

4. Copy the .env.example file to .env

   cp .env.example .env

5. Generate the application key

   node ace generate:key

6. Create the database (we use SQLite)

   node ace db:create

7. Run the migrations

   node ace migration:fresh

That's it! You are now ready to setup the application.

(back to top)

2. Environment variables

Define all the environment variables in the .env file at the project root. Your completed file should look like this. The NODE_ENV variable influences the application’s behavior:

• development : All commands are executed in dry-run mode, and no transfers are made.
• production : Commands are executed normally, and transfers are performed.

To retrieve your credentials, go to Qonto and get your secret key and organization ID: Settings (Cog Icon) > Integrations & Partnerships > API Key.

TZ=UTC
PORT=3333
HOST=localhost
LOG_LEVEL=info
APP_KEY=RzsLKGzEC3xQVLYG64vfifRkDMz4VVgk # Your app key may be different
NODE_ENV=development # Set as production for production environment

QONTO_API_BASE_URL=https://thirdparty.qonto.com/
QONTO_SECRET_KEY=YOUR_QONTO_SECRET_KEY # Your Qonto secret key
QONTO_ORGANIZATION_SLUG=YOUR_QONTO_ORGANIZATION_SLUG # Your Qonto organization slug

(back to top)

3. Setup

Now, you will configure the application. If you need to modify the configuration later, simply rerun the setup command. The setup wizard will guide you interactively. The setup will allow you to configure watched accounts and IBANs to exclude. If you want to configure them later, check the commands section.

• Reference for withdrawal: The reference used for transfers to help you identify them. Default: Internal Transfer - Qonto Split.
• Split amount: The percentage of the incoming amount to transfer to the internal account. Enter the number without the %.
• VAT mode: Changes the calculation mode for the transferred amount. In VAT mode, the amount is calculated based on the Split amount. In fixed mode, it is calculated as a percentage of the incoming amount.
• Exclude internal incomes: If you want to exclude internal transfers from the split, enable this option.

Configuration form:

Run the setup with the following command:

node ace qonto:setup

(back to top)

4. Manual Run

To manually execute the application, use the following command.

Options :

• --interactive or -i: Enables interactive mode, allowing you to review transfers before execution. Default: false.
• --dry: Runs in dry-run mode, where no transfers are made. Default activated if NODE_ENV=development.
• --interval[=value] : Defines the time interval for transaction retrieval. Possible values:
  • year
  • quarter
  • month
  • week (default)
  • day
  • hour
  • minute

Run manually with:

node ace qonto:split --interactive

(back to top)

5. Scheduled Run (Cron-like)

To automatically execute the application daily, use the built-in pm2 configuration:

pm2 start scheduler.config.cjs && pm2 save

You can modify the pm2 configuration by editing scheduler.config.cjs in the project root.

(back to top)

Commands

Additional commands are available to help manage the application's configuration. You can also use them if you don't want to restart the entire setup process.

qonto:watch - Manage watched accounts

This command allows you to manage the accounts monitored by the application. You can add or remove accounts to watch. The monitored accounts are used to retrieve transactions and incoming transfers.

Run with the following command:

node ace qonto:watch

(back to top)

qonto:exclude - Manage excluded accounts

This command allows you to manage accounts that should be excluded from income distribution. Excluded accounts will not be considered when splitting income. All transactions from these accounts will be ignored.

Run with the following command :

node ace qonto:exclude

(back to top)

Contact

• Kylian Mallet - @Kylian-Mallet - kylian.mallet@sklav.group
• Guillaume Varin - @GullmeVrn - guillaume.varin@sklav.group

(back to top)