You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -17,7 +17,9 @@ This project provides an importer from Israeli banks (via [israeli-bank-scrapers
17
17
18
18
4.**Reconciliation:** Optional reconciliation to adjust account balances automatically.
19
19
20
-
5.**Concurrent Processing:** Uses a queue (via [p-queue](https://www.npmjs.com/package/p-queue)) to manage scraping tasks concurrently.
20
+
5.**Credit Card / Multi-Account Mapping (Targets):** Supports mapping multiple scraped accounts/cards into one Actual account, or mapping each scraped card into its own Actual account (via `targets` and `accounts`).
21
+
22
+
6.**Concurrent Processing:** Uses a queue (via [p-queue](https://www.npmjs.com/package/p-queue)) to manage scraping tasks concurrently.
21
23
22
24
## Installation
23
25
@@ -42,25 +44,176 @@ services:
42
44
43
45
## Configuration
44
46
45
-
The application configuration is defined using JSON and validated against a schema. The key configuration file is `config.json` and its schema is described in `config.schema.json`.
47
+
The application configuration is defined using JSON and validated against a schema.
48
+
The main configuration file is `config.json`.
49
+
50
+
The configuration has **two independent top-level sections**:
51
+
1. `actual`: Configures the Actual Budget connection.
52
+
2. `banks`: Configures bank scrapers and account mappings.
53
+
54
+
---
55
+
56
+
### 1) `actual` configuration
57
+
58
+
This section configures the connection to your Actual Budget server and budget.
59
+
It is **always required**, regardless of how you configure banks or targets.
60
+
61
+
```json
62
+
{
63
+
"actual": {
64
+
"init": {
65
+
"dataDir": "./data",
66
+
"password": "your_actual_password",
67
+
"serverURL": "https://your-actual-server.com"
68
+
},
69
+
"budget": {
70
+
"syncId": "your_sync_id",
71
+
"password": "your_budget_password"
72
+
}
73
+
}
74
+
}
75
+
```
76
+
77
+
Nothing in this block changes when using `targets`, credit cards, or multi-account mappings.
78
+
79
+
---
80
+
81
+
### 2) `banks` configuration
82
+
83
+
The `banks` section defines:
84
+
- Which banks to scrape
85
+
- The credentials for each bank
86
+
- How scraped accounts/cards are mapped into Actual accounts
87
+
88
+
Each bank entry includes the credentials required by `israeli-bank-scrapers`
89
+
(e.g. `userCode`, `username`, `password`, etc.) and supports **multiple mapping modes**.
46
90
47
-
### Configuration Structure
91
+
#### Using `targets` (recommended)
48
92
49
-
- **actual:**
50
-
Contains settings for the Actual API integration:
51
-
- `init`: Initialization parameters (e.g., server URL, password).
52
-
- `budget`: Contains properties like `syncId` and `password` for synchronizing budgets.
93
+
A single bank scrape (for example `visaCal`) may return **multiple accounts/cards**.
94
+
Different users model these differently in Actual, so the importer supports `targets`.
53
95
54
-
- **banks:**
55
-
Defines bank-specific settings for each supported bank. Each entry typically requires:
56
-
- `actualAccountId`: The account identifier in Actual.
57
-
- `password`: The bank account password.
58
-
- Additional properties (e.g., `userCode`, `username`, or other bank-specific credentials) as required.
59
-
- `reconcile` (optional): A flag to enable balance reconciliation.
96
+
Each **target** represents:
97
+
- One Actual account
98
+
- One or more scraped accounts/cards that feed into it
60
99
61
-
Make sure your `config.json` follows the schema defined in `config.schema.json`.
100
+
For each target:
101
+
- Imported transactions = concatenation of transactions from selected cards
102
+
- Reconciliation (if enabled) = sum of balances of selected cards
103
+
(only cards with a valid numeric balance are included)
62
104
63
-
Example snippet:
105
+
---
106
+
107
+
#### Example A: One Actual account for all VisaCal cards (consolidated)
108
+
109
+
```json
110
+
{
111
+
"actual": {
112
+
"init": {
113
+
"dataDir": "./data",
114
+
"password": "your_actual_password",
115
+
"serverURL": "https://your-actual-server.com"
116
+
},
117
+
"budget": {
118
+
"syncId": "your_sync_id",
119
+
"password": "your_budget_password"
120
+
}
121
+
},
122
+
"banks": {
123
+
"visaCal": {
124
+
"username": "bank_username",
125
+
"password": "bank_password",
126
+
"targets": [
127
+
{
128
+
"actualAccountId": "actual-creditcards-all",
129
+
"reconcile": true,
130
+
"accounts": "all"
131
+
}
132
+
]
133
+
}
134
+
}
135
+
}
136
+
```
137
+
138
+
---
139
+
140
+
#### Example B: One Actual account per VisaCal card (separate accounts)
141
+
142
+
```json
143
+
{
144
+
"actual": {
145
+
"init": {
146
+
"dataDir": "./data",
147
+
"password": "your_actual_password",
148
+
"serverURL": "https://your-actual-server.com"
149
+
},
150
+
"budget": {
151
+
"syncId": "your_sync_id",
152
+
"password": "your_budget_password"
153
+
}
154
+
},
155
+
"banks": {
156
+
"visaCal": {
157
+
"username": "bank_username",
158
+
"password": "bank_password",
159
+
"targets": [
160
+
{
161
+
"actualAccountId": "actual-card-8538",
162
+
"reconcile": true,
163
+
"accounts": ["8538"]
164
+
},
165
+
{
166
+
"actualAccountId": "actual-card-7697",
167
+
"reconcile": true,
168
+
"accounts": ["7697"]
169
+
}
170
+
]
171
+
}
172
+
}
173
+
}
174
+
```
175
+
176
+
---
177
+
178
+
#### Example C: Grouped cards into a single Actual account (subset)
179
+
180
+
```json
181
+
{
182
+
"actual": {
183
+
"init": {
184
+
"dataDir": "./data",
185
+
"password": "your_actual_password",
186
+
"serverURL": "https://your-actual-server.com"
187
+
},
188
+
"budget": {
189
+
"syncId": "your_sync_id",
190
+
"password": "your_budget_password"
191
+
}
192
+
},
193
+
"banks": {
194
+
"visaCal": {
195
+
"username": "bank_username",
196
+
"password": "bank_password",
197
+
"targets": [
198
+
{
199
+
"actualAccountId": "actual-cal-primary",
200
+
"reconcile": true,
201
+
"accounts": ["8538", "7697"]
202
+
}
203
+
]
204
+
}
205
+
}
206
+
}
207
+
```
208
+
209
+
---
210
+
211
+
## Legacy configuration (single Actual account per bank)
212
+
213
+
This configuration style is **fully supported for backward compatibility**,
214
+
but does **not** allow fine-grained control over multiple cards/accounts.
215
+
216
+
It maps all scraped accounts from the bank into a single Actual account.
64
217
65
218
```json
66
219
{
@@ -87,11 +240,19 @@ Example snippet:
87
240
"username": "bank_username",
88
241
"password": "bank_password"
89
242
}
90
-
// Additional bank configurations go here...
91
243
}
92
244
}
93
245
```
94
246
247
+
---
248
+
249
+
## Notes
250
+
251
+
- The `actual` block is **always required** and independent of bank configuration.
252
+
- `targets`are optional but strongly recommended for credit-card providers.
253
+
- Duplicate transactions are prevented using a stable `imported_id`.
254
+
- Credit card balances are often negative; reconciliation uses the values as returned by the bank.
255
+
95
256
## License
96
257
97
258
This project is open-source. Please see the [LICENSE](./LICENSE) file for licensing details.
0 commit comments