Sync ActualBudget via SimpleFIN
PREREQUISITES
- A SimpleFIN Token is required during setup
- The ActualBduget Budget ID is required during setup
- ActualBudget needs to be installed and running
- Have your SimpleFin setup key handy. These are 1 time use only, so if for some reason you abort your setup early, you may need to generate a new one. If you re-run config, after a succesful setup, you won't need to change this unless you've deleted it from SimpleFin (stores the AccessKey returned).
- Once you get everything running, you may (optionally) configure a system cron to run this automatically.
IMPORTANT NOTES
- SimpleFin data updates one time / day, for each linked account. The time that it updates may vary, even from day to day (based on the bank and upstream provider, MX).
- The first run syncs back to the start of the current month. I would reconcile all accounts up to the start of the current month, either manually or via CSV import, and then run this.
- You will want to check (for the first run) for any transactions right around the 1st of the current month, to make sure nothing is left out.
- Future runs start from 5 days prior to the previous run, to catch any that processed later. No duplicate transactions will be created in Actual.
- The max length of history returned varies from bank to bank, so I would make sure to run this monthly at a minimum. Some have a number of transactions limit, others return between 2-6 months of history.
- You can reset all your settings by deleting the config.json file, and the budget folder, if you wish. This will not delete previous transactions from Actual.
TODO
- Better security for storage of SimpleFIN AccessKey
- Allow custom date ranges for sync
USAGE
-
Sync - If the app hasn't been configured yet, you'll be run through the setup steps, otherwise it will sync the current month for all accounts.
node app.js
-
Setup - Change your SimpleFIN token, which budget file to use, your Actual Budget url, Actual Budget Password,and how the accounts are linked.
node app.js --setup
-
Link - Change or add any new linked accounts
node app.js --link
TROUBLESHOOTING
-
I've had some users report trouble using .local addresses to connect. If you run into this and are able, a reverse proxy might be of assistance.
-
I've had a couple users report segfaults using Node v21.x. I haven't been able to recreate, but for those that have, switching to Node 20.x, deleting and re-cloning, and setting up again (with a new SimpleFin setup token) has fixed the issue both times.
-
Be sure you have a budget, with encryption password (or leave blank with none), that has at least 1 account. You MUST have at least 1 account created, so you have something to map SimpleFin accounts to.