301 lines
8.5 KiB
Markdown
301 lines
8.5 KiB
Markdown
# Example Bank CSV Files
|
|
|
|
## Format 1: Date, Description, Amount
|
|
|
|
This is the most common format from bank exports.
|
|
|
|
### Example: `bank_export_standard.csv`
|
|
```csv
|
|
Date,Description,Amount
|
|
2024-01-02,ACH WITHDRAWAL - RENT PAYMENT,5000.00
|
|
2024-01-03,DEPOSIT - ACME CORP PAYMENT,15000.50
|
|
2024-01-04,ELECTRONIC PAYMENT - UTILITIES,850.25
|
|
2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC",1250.00
|
|
2024-01-08,BANK FEE,25.00
|
|
2024-01-10,DEPOSIT - CUSTOMER ABC LLC,3500.00
|
|
2024-01-12,ACH WITHDRAWAL - PAYROLL,12500.00
|
|
2024-01-15,WIRE TRANSFER OUT - SUPPLIER PAYMENT,8900.00
|
|
2024-01-16,DEPOSIT - RETURNED CHECK,500.00
|
|
2024-01-18,ONLINE PAYMENT - LOAN PAYMENT,2000.00
|
|
2024-01-20,ACH WITHDRAWAL - TAXES QUARTERLY,5000.00
|
|
2024-01-22,DEPOSIT - CONSULTING SERVICES,4500.00
|
|
2024-01-25,CHECK #1002 - EQUIPMENT LEASE,1800.00
|
|
2024-01-28,BANK INTEREST CREDIT,150.00
|
|
2024-01-30,ACH WITHDRAWAL - INSURANCE,750.00
|
|
```
|
|
|
|
**How it's parsed:**
|
|
- Debit: Single amount (interpreted as DEBIT/withdrawal)
|
|
- Credit: Single amount (if negative, interpreted as CREDIT/deposit)
|
|
- All amounts are assumed DEBIT by default
|
|
- Date format: YYYY-MM-DD
|
|
|
|
---
|
|
|
|
## Format 2: Date, Description, Debit, Credit
|
|
|
|
This format explicitly shows debits and credits, common in business bank statements.
|
|
|
|
### Example: `bank_export_debit_credit.csv`
|
|
```csv
|
|
Date,Description,Debit,Credit
|
|
2024-01-02,ACH WITHDRAWAL - RENT PAYMENT,5000.00,
|
|
2024-01-03,DEPOSIT - ACME CORP PAYMENT,,15000.50
|
|
2024-01-04,ELECTRONIC PAYMENT - UTILITIES,850.25,
|
|
2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC",1250.00,
|
|
2024-01-08,BANK FEE,25.00,
|
|
2024-01-10,DEPOSIT - CUSTOMER ABC LLC,,3500.00
|
|
2024-01-12,ACH WITHDRAWAL - PAYROLL,12500.00,
|
|
2024-01-15,WIRE TRANSFER OUT - SUPPLIER PAYMENT,8900.00,
|
|
2024-01-16,DEPOSIT - RETURNED CHECK,,500.00
|
|
2024-01-18,ONLINE PAYMENT - LOAN PAYMENT,2000.00,
|
|
2024-01-20,ACH WITHDRAWAL - TAXES QUARTERLY,5000.00,
|
|
2024-01-22,DEPOSIT - CONSULTING SERVICES,,4500.00
|
|
2024-01-25,CHECK #1002 - EQUIPMENT LEASE,1800.00,
|
|
2024-01-28,BANK INTEREST CREDIT,,150.00
|
|
2024-01-30,ACH WITHDRAWAL - INSURANCE,750.00,
|
|
```
|
|
|
|
**How it's parsed:**
|
|
- If Debit column has value: transaction type is DEBIT, amount is Debit value
|
|
- If Credit column has value: transaction type is CREDIT, amount is Credit value
|
|
- Both columns cannot have values in same row
|
|
- Empty string or 0 in column means no transaction
|
|
|
|
---
|
|
|
|
## Format 3: With Quoted Descriptions (Commas in Description)
|
|
|
|
Handles bank statements where description contains commas.
|
|
|
|
### Example: `bank_export_quoted.csv`
|
|
```csv
|
|
Date,Description,Amount
|
|
2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC, Springfield, IL",1250.00
|
|
2024-01-10,"DEPOSIT - CUSTOMER ABC LLC, Invoice #INV-2024-001, Reference: PO-5555",3500.00
|
|
2024-02-01,"WIRE TRANSFER - VENDOR XYZ, Invoice #INV-12345, Amount $8900, Reference Code ABC123",8900.00
|
|
2024-02-15,"ACH PAYMENT - MULTIPLE INVOICES, Details: INV-001 $500, INV-002 $750, INV-003 $1000",2250.00
|
|
```
|
|
|
|
**Key Features:**
|
|
- Descriptions with commas are wrapped in quotes: `"Description, with, commas"`
|
|
- Quotes are properly handled by the CSV parser
|
|
- Real-world bank statements often include detailed transaction info
|
|
|
|
---
|
|
|
|
## Format 4: Mixed with Escaped Quotes
|
|
|
|
Handles descriptions that contain both commas AND quotes.
|
|
|
|
### Example: `bank_export_escaped_quotes.csv`
|
|
```csv
|
|
Date,Description,Amount
|
|
2024-01-20,"VENDOR INVOICE - Widget Corp, Item: ""Ultra Premium Widgets"", Qty: 500",2500.00
|
|
2024-02-10,"CUSTOMER DEPOSIT - ABC Corp, Receipt: ""2024-Feb-Invoice"", Amount: USD 5000",5000.00
|
|
```
|
|
|
|
**Key Features:**
|
|
- Quotes inside quoted strings are escaped with double-quotes: `"The ""thing"" is..."`
|
|
- Parser handles these correctly
|
|
- Uncommon but can appear in detailed bank statements
|
|
|
|
---
|
|
|
|
## API Request Examples
|
|
|
|
### Parse CSV (Form Data)
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
|
|
-F "file=@bank_export_standard.csv"
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"count": 15,
|
|
"transactions": [
|
|
{
|
|
"transactionDate": "2024-01-02",
|
|
"description": "ACH WITHDRAWAL - RENT PAYMENT",
|
|
"transactionType": "DEBIT",
|
|
"amount": 5000.00
|
|
},
|
|
{
|
|
"transactionDate": "2024-01-03",
|
|
"description": "DEPOSIT - ACME CORP PAYMENT",
|
|
"transactionType": "DEBIT",
|
|
"amount": 15000.50
|
|
},
|
|
...
|
|
],
|
|
"message": "Parsed 15 transaction(s) from CSV"
|
|
}
|
|
```
|
|
|
|
### Import Transactions (JSON)
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/bank-transactions/import \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"bankAccountId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"transactions": [
|
|
{
|
|
"transactionDate": "2024-01-02",
|
|
"description": "ACH WITHDRAWAL - RENT PAYMENT",
|
|
"transactionType": "DEBIT",
|
|
"amount": 5000.00,
|
|
"referenceNumber": "ACH-123456",
|
|
"oppositeParty": "Landlord LLC"
|
|
},
|
|
{
|
|
"transactionDate": "2024-01-03",
|
|
"description": "DEPOSIT - ACME CORP PAYMENT",
|
|
"transactionType": "DEBIT",
|
|
"amount": 15000.50,
|
|
"referenceNumber": "INV-2024-001",
|
|
"oppositeParty": "Acme Corp"
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"imported": 2,
|
|
"message": "Successfully imported 2 transaction(s)"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Common Bank CSV Exports
|
|
|
|
### Chase Business Banking
|
|
Typically uses: `Date, Description, Amount`
|
|
- Date format: MM/DD/YYYY
|
|
- Description includes transaction type and details
|
|
- Single amount column (positive = debit)
|
|
|
|
### Bank of America
|
|
Typically uses: `Date, Description, Debit, Credit`
|
|
- Date format: MM/DD/YYYY
|
|
- Description is brief
|
|
- Explicit debit/credit columns
|
|
|
|
### Wells Fargo Business
|
|
Typically uses: `Date, Description, Amount`
|
|
- Date format: M/D/YYYY
|
|
- Description is detailed
|
|
- Amount is always positive
|
|
|
|
### Quickbooks Export
|
|
Typically uses: `Date, Reference, Amount, Description`
|
|
- Can be remapped to standard format
|
|
- Date format: M/D/YYYY
|
|
- Amount includes sign (negative = credit)
|
|
|
|
---
|
|
|
|
## Data Quality Notes
|
|
|
|
### Best Practices for CSV Uploads
|
|
|
|
1. **Remove headers:** API expects headers in first row
|
|
2. **Check date format:** Should be YYYY-MM-DD or MM/DD/YYYY
|
|
3. **Consistent amounts:** All positive numbers (debit/credit indicated by column)
|
|
4. **No special formatting:** Avoid currency symbols ($), commas in amounts (500.00, not 500,00)
|
|
5. **Quoted descriptions:** Use quotes if description contains commas
|
|
6. **No summary rows:** Remove total/balance rows at end of file
|
|
|
|
### Invalid Examples (Will Fail)
|
|
|
|
```csv
|
|
Date,Description,$Amount
|
|
1/2/24,Rent Payment,"$5,000.00"
|
|
1/3/24,Deposit,15000.50
|
|
```
|
|
**Problems:**
|
|
- Currency symbol in header ($Amount)
|
|
- Non-standard date format (1/2/24)
|
|
- Currency formatting in amount ($5,000.00)
|
|
|
|
### Valid Examples (Will Succeed)
|
|
|
|
```csv
|
|
Date,Description,Amount
|
|
2024-01-02,Rent Payment,5000.00
|
|
2024-01-03,Deposit,15000.50
|
|
```
|
|
|
|
---
|
|
|
|
## Testing Workflow
|
|
|
|
### Step 1: Prepare CSV
|
|
Use one of the example files above or export from your bank.
|
|
|
|
### Step 2: Parse for Preview
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
|
|
-F "file=@bank_export.csv"
|
|
```
|
|
Review the parsed transactions in the response.
|
|
|
|
### Step 3: Adjust if Needed
|
|
If parsing fails, check:
|
|
- CSV has required columns (Date, Description, Amount or Debit/Credit)
|
|
- Date format is standard (YYYY-MM-DD or MM/DD/YYYY)
|
|
- Descriptions with commas are quoted
|
|
- No extra rows (headers, totals, etc.)
|
|
|
|
### Step 4: Import
|
|
Once happy with preview, send parsed transactions to import endpoint.
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/bank-transactions/import \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"bankAccountId": "your-account-uuid",
|
|
"transactions": [... from parse response ...]
|
|
}'
|
|
```
|
|
|
|
### Step 5: Verify in UI
|
|
Log in and check that transactions appear in:
|
|
- Bank Transactions list view
|
|
- Bank Account details
|
|
- Cash position report
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "CSV must have 'Date' and 'Description' columns"
|
|
- Check header row for exact column names
|
|
- Use: `Date` and `Description` (case-sensitive)
|
|
- Or: `date`, `description` (lowercase works too)
|
|
|
|
### "CSV must have 'Amount' or 'Debit'/'Credit' columns"
|
|
- Format 1: Include `Amount` column
|
|
- Format 2: Include both `Debit` AND `Credit` columns
|
|
- Cannot mix formats in same file
|
|
|
|
### "CSV file is empty"
|
|
- Check that file was uploaded successfully
|
|
- File must have at least header + 1 data row
|
|
|
|
### "Cannot read property 'toLowerCase' of null"
|
|
- Likely missing required columns
|
|
- Verify CSV header row has Date and Description
|
|
|
|
### Transactions show with wrong type (DEBIT vs CREDIT)
|
|
- In Format 1 (single Amount column), all treated as DEBIT
|
|
- Use Format 2 (Debit/Credit columns) for mixed transaction types
|
|
- Or ensure negative amounts are handled correctly
|