115 lines
2.8 KiB
Markdown
115 lines
2.8 KiB
Markdown
# BAC Statement Tools
|
|
|
|
Tools for processing BAC Costa Rica credit card statement PDFs.
|
|
|
|
## Dependencies
|
|
|
|
- Python 3.10+
|
|
- pdfplumber (>=0.10.0)
|
|
- matplotlib (>=3.5.0) - optional, for graphs
|
|
|
|
## Extraction
|
|
|
|
Extract transactions from statement PDFs to JSON.
|
|
|
|
```bash
|
|
python bac_extract.py <pdf_file> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `-o, --output`: Output JSON path (default: transactions.json)
|
|
- `--pretty`: Pretty-print JSON output
|
|
- `-v, --verbose`: Enable debug logging
|
|
|
|
**Examples:**
|
|
```bash
|
|
python bac_extract.py statement.pdf --pretty
|
|
python bac_extract.py statement.pdf -o output.json -v
|
|
```
|
|
|
|
## Analysis
|
|
|
|
Analyze extracted transactions with category breakdowns and graphs.
|
|
|
|
```bash
|
|
python bac_analyze.py <json_files...> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `--graph {bar,pie,timeline,all}`: Generate graph(s)
|
|
- `-o, --output`: Output file for graph (default: spending_<type>.png)
|
|
- `--show`: Display graph interactively
|
|
- `--categories`: Custom categories file (default: categories.json)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Text summary
|
|
python bac_analyze.py transactions.json
|
|
|
|
# Analyze multiple statements
|
|
python bac_analyze.py *.json
|
|
|
|
# Generate all graphs
|
|
python bac_analyze.py *.json --graph all
|
|
|
|
# Generate bar chart with custom output
|
|
python bac_analyze.py *.json --graph bar -o spending.png
|
|
|
|
# Use custom categories
|
|
python bac_analyze.py *.json --categories my_categories.json
|
|
```
|
|
|
|
## Categories
|
|
|
|
Create a `categories.json` file to customize spending categories. Each category maps to a list of merchant name patterns (case-insensitive substring match).
|
|
|
|
```json
|
|
{
|
|
"Groceries": ["SUPERMARKET", "WALMART", "FRESH MARKET"],
|
|
"Gas": ["SERVICENTRO", "DELTA", "SHELL"],
|
|
"Restaurants": ["RESTAURANT", "CAFE", "PIZZA", "SUSHI"],
|
|
"Transportation": ["UBER", "TAXI", "PARKING"],
|
|
"Entertainment": ["CINEMA", "NETFLIX", "STEAM"],
|
|
"Utilities": ["ELECTRIC", "WATER", "INTERNET"],
|
|
"Subscriptions": ["SPOTIFY", "YOUTUBE", "CHATGPT"]
|
|
}
|
|
```
|
|
|
|
Transactions not matching any pattern are categorized as "Other".
|
|
|
|
## Output Format
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"source_file": "statement.pdf",
|
|
"extraction_date": "2025-01-15T12:00:00Z",
|
|
"statement_date": "2025-01-10",
|
|
"total_transactions": 5
|
|
},
|
|
"card_holders": [
|
|
{
|
|
"card_suffix": "1234",
|
|
"name": "CARD HOLDER NAME"
|
|
}
|
|
],
|
|
"purchases": [
|
|
{
|
|
"reference": "123456789012",
|
|
"date": "2025-01-09",
|
|
"description": "EXAMPLE STORE",
|
|
"location": null,
|
|
"currency": "CRC",
|
|
"amount_crc": 1234.56,
|
|
"amount_usd": null
|
|
}
|
|
],
|
|
"other_charges": [],
|
|
"voluntary_services": [],
|
|
"summary": {
|
|
"purchases": { "total_crc": 50000.00, "total_usd": 0.00, "count": 5 },
|
|
"other_charges": { "total_crc": 0.00, "total_usd": 0.00, "count": 0 },
|
|
"voluntary_services": { "total_crc": 0.00, "total_usd": 0.00, "count": 0 }
|
|
}
|
|
}
|
|
```
|