Skip to content

Latest commit

 

History

History
127 lines (99 loc) · 5.57 KB

README.org

File metadata and controls

127 lines (99 loc) · 5.57 KB
Raw

You Need a Budget (https://www.ynab.com/) does not have integrations with many European banks (e.g. Finland OP or SPankki) but there is at least one free API that can grab data from them: GoCardless (https://gocardless.com/ formerly Nordigen).

This tool allows you to upload transactions from your bank account (if it is supported by GoCardless) to YNAB budget on a regular basis (e.g. crontab job could suffice). This is much easier than converting CSVs from banks and uploading them manually to YNAB.

Personally, I started to use that in July 2023 for my main YNAB Budget with OP and SPankki banks and not facing any issues anymore with it (have a separate cron job for each bank account that runs upload command 5 times per day).

Disclaimer

This tool is still in MVP state: developed poorly and fastest way possible. Alpha version I would say.

So these are things that may irritate you:

  • Too hard to start for a non-developer (getting all those IDs is still manual)
  • poor error handling (there are a lot of cases when you will encounter hard-to-understand errors because of a random bug, unexpected API response, etc..)

Before you start

Currently in order to use the tool you need at least Python version 3.11.

You also need to obtain credentials:

How-to

Clone this repository:

git clone https://github.com/axeoman/ynab-sync.git

Install with pip:

python -m pip install .

Go through quickstart script in order to obtain GoCardless Account ID and YNAB Budget and Account ID needed for ynab-sync upload to work:

ynab-sync quickstart

Run suggested by script command to add environment variables (example):

export GOCARDLESS_SECRET_ID=fa264...67322
export GOCARDLESS_SECRET_KEY=96d43...25200
export GOCARDLESS_COUNTRY=FI
export GOCARDLESS_ACCOUNT_ID=b62ca...fa9e2
export YNAB_TOKEN=D5rS4..SICe8
export YNAB_BUDGET_ID=6c4e2...bd8ad
export YNAB_ACCOUNT_ID=adf05...262e

You can use upload command now in order to download transactions from GoCardless Account and upload them to YNAB budget/account (remove –dry-run if you happy with result table):

ynab-sync upload --date-from=2023-08-01 --dry-run

You could also pass credentials and ids directly to the command:

$ ynab-sync help upload
usage: ynab-sync upload [-d|--date-from] [--date-to] [-y|--ynab-token] [--ynab-budget-id] [--ynab-account-id] [-g|--gocardless-secret-id] [--gocardless-secret-key] [--gocardless-account-id] [--dry-run]

Commands

  • ynab-sync upload - grabs transactions from GoCardless account for the desired period and uploads it to YNAB.
  • ynab-sync quickstart - interactive CLI that will help you to get an account/budget id and configure GoCardless integration with your bank. Note! You need to run this once per bank connection.

If you are curious you can also use those (ynab-sync quickstart should be enough to start)

  • ynab-sync gocardless banks - list of banks that needed for next step (auth)
  • ynab-sync gocardless generate_bank_auth_link - creates http link in order to auth with your bank
  • ynab-sync gocardless list_requisition_account - get GOCARDLESS_ACCOUNT_ID that is necessary for upload command
  • ynab-sync ynab budgets - lists budgets in your YNAB account (YNAB_BUDGET_ID)
  • ynab-sync ynab accounts - lists accounts in your YNAB budget (YNAB_ACCOUNT_ID)

Docker usage

Probably the fastest way to use it in any environment is to use a docker container (that is how I currently use it for myself).

  • clone this repository (or grab latest release if it’s broken)
git clone https://github.com/axeoman/ynab-sync.git
  • Store you credentials in .env file e.g. sandbox.env (example) and run following commands
  • Build docker container
docker build -t ynab-sync .
  • Run docker container. Note: it will grab all transactions from 7 days before the current date (consult Dockerfile for details)
docker run --env-file=sandbox.env --rm ynab-sync

Getting budget and account ids

Development

I have an e2e happy path test: feel free to submit a PR :)

API Used

TODOs

  • [X] MVP
  • [X] end-to-end automated tests based on results of MVP
  • [X] separate cli from logic
  • [X] add useful commands (building links, getting GoCardless and YNAB account/budget information)
  • [X] add packaging
  • [X] add a simple interactive command that provides you with .env file and all necessary variables to get bank data
  • [ ] refactor API classes

Initial requirements

  • Upload fresh bank transactions to YNAB
  • Supported banks: OP, Spankki
  • Should be stateless
  • Runs a command (with appeal https://github.com/larryhastings/appeal) (can be used in cron): Params:
    • YNAB auth token
    • YNAB budget_id
    • YNAB account_id
    • secrets from GoCardless
    • account_id / name of the bank institution to upload
    • transactions time range
  • Command should report number of imported and duplicated transactions
  • Nice to have:
    • command that builds authorization link (might be needed every 3 months)
    • command that provide budget_id/account_id information (list of available with name)