Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

feat: customizable CSV column mapping for imports (#201) (#206)

Tássio Noronhafefc7c26aed9
diff --git a/backend/app/api/import_transactions.py b/backend/app/api/import_transactions.py
index ba9733ac..ad015713 100644
--- a/backend/app/api/import_transactions.py
+++ b/backend/app/api/import_transactions.py
@@ -1,3 +1,4 @@
+import json
import logging
from typing import Optional
@@ -23,6 +24,7 @@ async def preview_import(
flip_amount: bool = Form(False),
inflow_column: Optional[str] = Form(None),
outflow_column: Optional[str] = Form(None),
+ column_mapping: Optional[str] = Form(None),
session: AsyncSession = Depends(get_async_session),
user: User = Depends(current_active_user),
):
@@ -34,6 +36,23 @@ async def preview_import(
filename, len(content), file.content_type,
)
+ # column_mapping arrives as a JSON-encoded form field (Securo field -> CSV header)
+ parsed_mapping: Optional[dict] = None
+ if column_mapping:
+ try:
+ parsed_mapping = json.loads(column_mapping)
+ except json.JSONDecodeError:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail="Invalid column_mapping: must be a JSON object",
+ )
+ if not isinstance(parsed_mapping, dict):
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail="Invalid column_mapping: must be a JSON object",
+ )
+
+ parse_error: Optional[str] = None
try:
if filename.lower().endswith('.ofx') or filename.lower().endswith('.qfx'):
transactions = import_service.parse_ofx(content)
@@ -45,14 +64,24 @@ async def preview_import(
transactions = import_service.parse_camt(content)
detected_format = "camt"
elif filename.lower().endswith('.csv'):
- transactions = import_service.parse_csv(
- content,
- date_format=date_format,
- flip_amount=flip_amount,
- inflow_column=inflow_column,
- outflow_column=outflow_column,
- )
detected_format = "csv"
+ try:
+ transactions = import_service.parse_csv(
+ content,
+ date_format=date_format,
+ flip_amount=flip_amount,
+ inflow_column=inflow_column,
+ outflow_column=outflow_column,
+ column_mapping=parsed_mapping,
+ )
+ except ValueError as csv_err:
+ # The CSV's columns couldn't be auto-mapped. As long as we can
+ # still read its headers, return a soft failure so the UI can
+ # show the column-mapping dropdowns instead of a hard error.
+ if not import_service.detect_csv_columns(content):
+ raise
+ transactions = []
+ parse_error = str(csv_err)
else:
# Try to detect format
try:
@@ -91,7 +120,20 @@ async def preview_import(
session, user.id, transactions,
)
- return TransactionImportPreview(transactions=transactions, detected_format=detected_format)
+ # Expose CSV headers so the UI can offer accurate column-mapping dropdowns.
+ csv_columns: list[str] = []
+ if detected_format == "csv":
+ try:
+ csv_columns = import_service.detect_csv_columns(content)
+ except Exception:
+ csv_columns = []
+
+ return TransactionImportPreview(
+ transactions=transactions,
+ detected_format=detected_format,
+ csv_columns=csv_columns,
+ parse_error=parse_error,
+ )
@router.post("/import", status_code=status.HTTP_201_CREATED)
diff --git a/backend/app/schemas/transaction.py b/backend/app/schemas/transaction.py
index 20504082..d556ca13 100644
--- a/backend/app/schemas/transaction.py
+++ b/backend/app/schemas/transaction.py
@@ -152,6 +152,12 @@ class TransactionImport(TransactionBase):
class TransactionImportPreview(BaseModel):
transactions: list[TransactionImport]
detected_format: str
+ # CSV header column names, exposed so the UI can offer column-mapping
+ # dropdowns. Empty for non-CSV formats.
+ csv_columns: list[str] = []
+ # Set when a CSV's columns could not be auto-detected. The preview still
+ # succeeds (with no transactions) so the UI can show the mapping dropdowns.
+ parse_error: Optional[str] = None
class TransactionImportRequest(BaseModel):
diff --git a/backend/app/services/import_service.py b/backend/app/services/import_service.py
index 514fcf24..0b7742e8 100644
--- a/backend/app/services/import_service.py
+++ b/backend/app/services/import_service.py
@@ -266,6 +266,33 @@ DATE_FORMAT_MAP = {
'YYYY-MM-DD': '%Y-%m-%d',
}
+# Securo fields a CSV column can be mapped to. Used to validate the
+# user-supplied column_mapping and to drive the import-UI dropdowns.
+CSV_MAPPABLE_FIELDS = (
+ 'date', 'description', 'amount', 'type',
+ 'category', 'currency', 'fx_rate', 'inflow', 'outflow',
+)
+
+
+def _sniff_csv_dialect(text: str):
+ """Detect the CSV dialect (delimiter/quoting), falling back to comma."""
+ try:
+ return csv.Sniffer().sniff(text[:4096], delimiters=',;\t|')
+ except csv.Error:
+ return csv.excel
+
+
+def detect_csv_columns(content: bytes) -> list[str]:
+ """Return the CSV header column names exactly as they appear in the file.
+
+ Used by the import preview so the UI can offer accurate column-mapping
+ dropdowns instead of guessing headers client-side.
+ """
+ text = content.decode('utf-8-sig') # Handle BOM
+ dialect = _sniff_csv_dialect(text)
+ reader = csv.DictReader(io.StringIO(text), dialect=dialect)
+ return [f.strip() for f in (reader.fieldnames or []) if f and f.strip()]
+
def parse_csv(
content: bytes,
@@ -273,6 +300,7 @@ def parse_csv(
flip_amount: bool = False,
inflow_column: str | None = None,
outflow_column: str | None = None,
+ column_mapping: dict[str, str] | None = None,
) -> list[TransactionImport]:
"""Parse CSV file content and return transactions.
@@ -284,13 +312,11 @@ def parse_csv(
- date_format: explicit date format (DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD)
- flip_amount: negate all parsed amounts
- inflow_column/outflow_column: use split columns instead of single amount
+ - column_mapping: explicit Securo-field -> CSV-header map. Any field
+ present here overrides auto-detection; unmapped fields still auto-detect.
"""
text = content.decode('utf-8-sig') # Handle BOM
- sample = text[:4096]
- try:
- dialect = csv.Sniffer().sniff(sample, delimiters=',;\t|')
- except csv.Error:
- dialect = csv.excel # fallback to comma
+ dialect = _sniff_csv_dialect(text)
reader = csv.DictReader(io.StringIO(text), dialect=dialect)
# Normalize field names
@@ -305,31 +331,55 @@ def parse_csv(
currency_cols = ['currency', 'moeda', 'currency_code']
fx_rate_cols = ['fx_rate', 'fx_rate_used', 'taxa_cambio', 'exchange_rate', 'taxa']
+ # Normalize the user-supplied column mapping (Securo field -> CSV header).
+ mapping = {
+ field: value.lower().strip()
+ for field, value in (column_mapping or {}).items()
+ if field in CSV_MAPPABLE_FIELDS and value and value.strip()
+ }
+
def find_col(candidates):
for c in candidates:
if c in fieldnames:
return c
return None
- date_col = find_col(date_cols)
- desc_col = find_col(desc_cols)
+ def resolve_col(field, candidates):
+ """Resolve a CSV column for a Securo field.
+
+ An explicit user mapping always wins; otherwise fall back to
+ auto-detection against the known column-name candidates.
+ """
+ mapped = mapping.get(field)
+ if mapped:
+ if mapped not in fieldnames:
+ raise ValueError(
+ f"Mapped column '{mapped}' for field '{field}' not found in CSV. "
+ f"Available columns: {', '.join(fieldnames)}"
+ )
+ return mapped
+ return find_col(candidates)
+
+ date_col = resolve_col('date', date_cols)
+ desc_col = resolve_col('description', desc_cols)
- # In split mode, we don't require a single amount column
- use_split = inflow_column and outflow_column
- inflow_col = inflow_column.lower().strip() if inflow_column else None
- outflow_col = outflow_column.lower().strip() if outflow_column else None
+ # In split mode, we don't require a single amount column. The inflow/outflow
+ # columns may come from the explicit args or from the column mapping.
+ inflow_col = (inflow_column or mapping.get('inflow') or '').lower().strip() or None
+ outflow_col = (outflow_column or mapping.get('outflow') or '').lower().strip() or None
+ use_split = bool(inflow_col and outflow_col)
if use_split:
if inflow_col not in fieldnames or outflow_col not in fieldnames:
raise ValueError(f"Inflow/outflow columns not found in CSV. Available columns: {', '.join(fieldnames)}")
amount_col = None
else:
- amount_col = find_col(amount_cols)
+ amount_col = resolve_col('amount', amount_cols)
- type_col = find_col(type_cols)
- category_col = find_col(category_cols)
- currency_col = find_col(currency_cols)
- fx_rate_col = find_col(fx_rate_cols)
+ type_col = resolve_col('type', type_cols)
+ category_col = resolve_col('category', category_cols)
+ currency_col = resolve_col('currency', currency_cols)
+ fx_rate_col = resolve_col('fx_rate', fx_rate_cols)
if not date_col or not desc_col:
raise ValueError(
diff --git a/backend/tests/test_import_api.py b/backend/tests/test_import_api.py
index da126fbe..6d7fbbdd 100644
--- a/backend/tests/test_import_api.py
+++ b/backend/tests/test_import_api.py
@@ -1,3 +1,5 @@
+import json
+
import pytest
from httpx import AsyncClient
@@ -22,34 +24,109 @@ async def test_preview_csv_import(client: AsyncClient, auth_headers, test_accoun
@pytest.mark.asyncio
-async def test_preview_invalid_file(client: AsyncClient, auth_headers, test_account):
+async def test_preview_csv_returns_columns(client: AsyncClient, auth_headers, test_account):
+ """The preview response exposes the CSV header columns for the mapping UI."""
+ csv_content = b"Posted On,Memo Line,Movement\n2026-01-10,COFFEE,-12.50\n"
response = await client.post(
"/api/transactions/import/preview",
headers=auth_headers,
- files={"file": ("bad.csv", b"col1,col2,col3\na,b,c\n", "text/csv")},
+ files={"file": ("bank.csv", csv_content, "text/csv")},
+ data={"column_mapping": json.dumps({
+ "date": "Posted On",
+ "description": "Memo Line",
+ "amount": "Movement",
+ })},
+ )
+ assert response.status_code == 200
+ data = response.json()
+ assert data["csv_columns"] == ["Posted On", "Memo Line", "Movement"]
+ assert len(data["transactions"]) == 1
+ assert data["transactions"][0]["description"] == "COFFEE"
+ assert data["transactions"][0]["amount"] == "12.50"
+
+
+async def test_preview_csv_with_column_mapping(client: AsyncClient, auth_headers, test_account):
+ """A CSV with non-standard headers parses once columns are mapped."""
+ csv_content = b"transaction_date,details,value\n15/02/2026,GROCERY STORE,-80.00\n"
+ # Without a mapping the description column can't be auto-detected: the
+ # preview soft-fails (200) with a parse_error and no transactions.
+ fail = await client.post(
+ "/api/transactions/import/preview",
+ headers=auth_headers,
+ files={"file": ("export.csv", csv_content, "text/csv")},
+ )
+ assert fail.status_code == 200
+ assert fail.json()["parse_error"]
+ assert fail.json()["transactions"] == []
+
+ # With a mapping it parses successfully.
+ ok = await client.post(
+ "/api/transactions/import/preview",
+ headers=auth_headers,
+ files={"file": ("export.csv", csv_content, "text/csv")},
+ data={"column_mapping": json.dumps({
+ "date": "transaction_date",
+ "description": "details",
+ "amount": "value",
+ })},
+ )
+ assert ok.status_code == 200
+ data = ok.json()
+ assert len(data["transactions"]) == 1
+ assert data["transactions"][0]["description"] == "GROCERY STORE"
+ assert data["transactions"][0]["type"] == "debit"
+
+
+async def test_preview_invalid_column_mapping_json(client: AsyncClient, auth_headers, test_account):
+ """A malformed column_mapping payload returns a 400 instead of a 500."""
+ csv_content = b"date,description,amount\n2026-01-10,X,-1.00\n"
+ response = await client.post(
+ "/api/transactions/import/preview",
+ headers=auth_headers,
+ files={"file": ("export.csv", csv_content, "text/csv")},
+ data={"column_mapping": "{not valid json"},
)
assert response.status_code == 400
+ assert "column_mapping" in response.json()["detail"]
+
+
+async def test_preview_unrecognized_csv_soft_fails_with_columns(
+ client: AsyncClient, auth_headers, test_account
+):
+ """A CSV whose columns can't be auto-detected returns a soft failure (200)
+ with the detected columns, so the UI can offer column mapping."""
+ response = await client.post(
+ "/api/transactions/import/preview",
+ headers=auth_headers,
+ files={"file": ("bad.csv", b"col1,col2,col3\na,b,c\n", "text/csv")},
+ )
+ assert response.status_code == 200
data = response.json()
- assert "detail" in data
- assert data["detail"] # must not be empty
+ assert data["detected_format"] == "csv"
+ assert data["transactions"] == []
+ assert data["csv_columns"] == ["col1", "col2", "col3"]
+ assert data["parse_error"] # must not be empty
@pytest.mark.asyncio
-async def test_preview_invalid_file_returns_specific_error(
+async def test_preview_unrecognized_csv_parse_error_is_specific(
client: AsyncClient, auth_headers, test_account
):
- """Error response should tell the user what columns were found and what is expected."""
+ """The parse_error should tell the user what columns were found and what is expected."""
response = await client.post(
"/api/transactions/import/preview",
headers=auth_headers,
files={"file": ("bad.csv", b"foo,bar,baz\n1,2,3\n", "text/csv")},
)
- assert response.status_code == 400
- detail = response.json()["detail"]
+ assert response.status_code == 200
+ parse_error = response.json()["parse_error"]
# Should mention what columns were found in the file
- assert "foo" in detail
+ assert "foo" in parse_error
# Should mention what columns are expected
- assert "date" in detail and "description" in detail and "amount" in detail
+ assert "date" in parse_error and "description" in parse_error and "amount" in parse_error
@pytest.mark.asyncio
diff --git a/backend/tests/test_import_service.py b/backend/tests/test_import_service.py
index 7497524a..678ec4e6 100644
--- a/backend/tests/test_import_service.py
+++ b/backend/tests/test_import_service.py
@@ -9,7 +9,14 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.models.account import Account
from app.models.fx_rate import FxRate
from app.models.user import User
-from app.services.import_service import parse_csv, parse_ofx, parse_qif, parse_camt, import_transactions
+from app.services.import_service import (
+ detect_csv_columns,
+ parse_csv,
+ parse_ofx,
+ parse_qif,
+ parse_camt,
+ import_transactions,
+)
class TestParseCsv:
@@ -249,6 +256,214 @@ class TestParseCsv:
assert transactions[1].amount == Decimal("1200.00")
+class TestParseCsvColumnMapping:
+ """Tests for customizable CSV column mapping (issue #201)."""
+
+ def test_column_mapping_unrecognized_headers(self):
+ """A CSV with headers Securo can't auto-detect parses with an explicit mapping."""
+ csv_content = (
+ "Posted On,Memo Line,Movement\n"
+ "2026-01-10,COFFEE SHOP,-12.50\n"
+ "2026-01-11,PAYCHECK,3000.00\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={
+ "date": "Posted On",
+ "description": "Memo Line",
+ "amount": "Movement",
+ },
+ )
+ assert len(transactions) == 2
+ assert transactions[0].description == "COFFEE SHOP"
+ assert transactions[0].amount == Decimal("12.50")
+ assert transactions[0].type == "debit"
+ assert transactions[1].description == "PAYCHECK"
+ assert transactions[1].type == "credit"
+
+ def test_column_mapping_without_mapping_raises(self):
+ """The same unrecognized CSV fails without a mapping — proving the mapping is what fixes it."""
+ csv_content = "Posted On,Memo Line,Movement\n2026-01-10,COFFEE SHOP,-12.50\n"
+ with pytest.raises(ValueError):
+ parse_csv(csv_content.encode("utf-8"))
+
+ def test_column_mapping_overrides_autodetection(self):
+ """An explicit mapping wins over a column that would otherwise auto-detect."""
+ # Both `description` and `details` exist; mapping forces `details`.
+ csv_content = (
+ "date,description,details,amount\n"
+ "2026-01-10,WRONG,RIGHT,-10.00\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={"description": "details"},
+ )
+ assert len(transactions) == 1
+ assert transactions[0].description == "RIGHT"
+
+ def test_column_mapping_partial_falls_back_to_autodetect(self):
+ """Unmapped fields still auto-detect; only mapped fields are overridden."""
+ csv_content = (
+ "txn_date,description,amount\n"
+ "2026-01-10,GROCERIES,-55.00\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={"date": "txn_date"},
+ )
+ assert len(transactions) == 1
+ assert transactions[0].date == date(2026, 1, 10)
+ assert transactions[0].description == "GROCERIES"
+ assert transactions[0].amount == Decimal("55.00")
+
+ def test_column_mapping_missing_column_raises(self):
+ """Mapping a field to a column that doesn't exist raises a helpful error."""
+ csv_content = "date,description,amount\n2026-01-10,X,-1.00\n"
+ with pytest.raises(ValueError, match="nonexistent"):
+ parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={"amount": "nonexistent"},
+ )
+
+ def test_column_mapping_case_insensitive(self):
+ """Mapping values are matched case-insensitively against CSV headers."""
+ csv_content = "Date,Description,Amount\n2026-01-10,X,-1.00\n"
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={"date": "DATE", "description": "Description", "amount": "amount"},
+ )
+ assert len(transactions) == 1
+ assert transactions[0].amount == Decimal("1.00")
+
+ def test_column_mapping_split_inflow_outflow(self):
+ """Inflow/outflow split columns can be supplied via column_mapping."""
+ csv_content = (
+ "Posted On,Memo,Credits,Debits\n"
+ "2026-01-10,SALARY,5000.00,\n"
+ "2026-01-11,RENT,,1200.00\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={
+ "date": "Posted On",
+ "description": "Memo",
+ "inflow": "Credits",
+ "outflow": "Debits",
+ },
+ )
+ assert len(transactions) == 2
+ assert transactions[0].type == "credit"
+ assert transactions[0].amount == Decimal("5000.00")
+ assert transactions[1].type == "debit"
+ assert transactions[1].amount == Decimal("1200.00")
+
+ def test_column_mapping_currency_and_fx_rate(self):
+ """Currency and fx_rate columns can be mapped from non-standard headers."""
+ csv_content = (
+ "date,description,amount,ccy,exch\n"
+ "2026-01-10,HOTEL,-100.00,EUR,1.08\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={"currency": "ccy", "fx_rate": "exch"},
+ )
+ assert len(transactions) == 1
+ assert transactions[0].currency == "EUR"
+ assert transactions[0].fx_rate == Decimal("1.08")
+
+ def test_column_mapping_ignores_empty_values(self):
+ """Empty mapping values are ignored and fall back to auto-detection."""
+ csv_content = "date,description,amount\n2026-01-10,X,-1.00\n"
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={"date": "", "description": " "},
+ )
+ assert len(transactions) == 1
+ assert transactions[0].description == "X"
+
+ def test_column_mapping_type_column_drives_credit_debit(self):
+ """A mapped type column overrides the amount sign for credit/debit."""
+ # All amounts are positive — only the Direction column distinguishes them.
+ csv_content = (
+ "Booking Date,Counterparty,Net,Direction\n"
+ "2026-04-01,Whole Foods,55.00,debit\n"
+ "2026-04-02,Employer Inc,4200.00,credit\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={
+ "date": "Booking Date",
+ "description": "Counterparty",
+ "amount": "Net",
+ "type": "Direction",
+ },
+ )
+ assert len(transactions) == 2
+ assert transactions[0].type == "debit"
+ assert transactions[0].amount == Decimal("55.00")
+ assert transactions[1].type == "credit"
+ assert transactions[1].amount == Decimal("4200.00")
+
+ def test_column_mapping_with_explicit_date_format(self):
+ """Column mapping composes with an explicit date_format."""
+ csv_content = (
+ "Posting Date,Details,Amount\n"
+ "22/03/2026,Gym Membership,-60.00\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ date_format="DD/MM/YYYY",
+ column_mapping={
+ "date": "Posting Date",
+ "description": "Details",
+ "amount": "Amount",
+ },
+ )
+ assert len(transactions) == 1
+ assert transactions[0].date == date(2026, 3, 22)
+ assert transactions[0].description == "Gym Membership"
+
+ def test_column_mapping_semicolon_delimiter(self):
+ """Column mapping works on semicolon-delimited CSVs with comma decimals."""
+ csv_content = (
+ "Fecha;Concepto;Importe\n"
+ "2026-07-02;Nomina;3.500,00\n"
+ "2026-07-03;Hotel;-200,00\n"
+ )
+ transactions = parse_csv(
+ csv_content.encode("utf-8"),
+ column_mapping={
+ "date": "Fecha",
+ "description": "Concepto",
+ "amount": "Importe",
+ },
+ )
+ assert len(transactions) == 2
+ assert transactions[0].amount == Decimal("3500.00")
+ assert transactions[0].type == "credit"
+ assert transactions[1].amount == Decimal("200.00")
+ assert transactions[1].type == "debit"
+
+
+class TestDetectCsvColumns:
+ """Tests for detect_csv_columns — used to drive the import-UI mapping dropdowns."""
+
+ def test_detect_basic(self):
+ csv_content = b"Posted On,Memo Line,Movement\n2026-01-10,COFFEE,-12.50\n"
+ assert detect_csv_columns(csv_content) == ["Posted On", "Memo Line", "Movement"]
+
+ def test_detect_semicolon_delimiter(self):
+ csv_content = b"date;description;amount\n2026-01-10;COFFEE;-12.50\n"
+ assert detect_csv_columns(csv_content) == ["date", "description", "amount"]
+
+ def test_detect_strips_whitespace_and_bom(self):
+ csv_content = " date , description , amount \n2026-01-10,X,-1.00\n".encode("utf-8-sig")
+ assert detect_csv_columns(csv_content) == ["date", "description", "amount"]
+
+ def test_detect_empty_file(self):
+ assert detect_csv_columns(b"") == []
+
+
class TestParseQif:
"""Tests for the parse_qif function."""
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 2d534c93..94c146cc 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -367,13 +367,17 @@ export const transactions = {
flip_amount?: boolean
inflow_column?: string
outflow_column?: string
- }): Promise<{ transactions: ImportPreviewTransaction[]; detected_format: string }> => {
+ column_mapping?: Record<string, string>
+ }): Promise<{ transactions: ImportPreviewTransaction[]; detected_format: string; csv_columns?: string[]; parse_error?: string | null }> => {
const formData = new FormData()
formData.append('file', file)
if (options?.date_format) formData.append('date_format', options.date_format)
if (options?.flip_amount) formData.append('flip_amount', 'true')
if (options?.inflow_column) formData.append('inflow_column', options.inflow_column)
if (options?.outflow_column) formData.append('outflow_column', options.outflow_column)
+ if (options?.column_mapping && Object.keys(options.column_mapping).length > 0) {
+ formData.append('column_mapping', JSON.stringify(options.column_mapping))
+ }
const { data } = await api.post('/transactions/import/preview', formData)
return data
},
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index a7d84574..e4ee803c 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -647,6 +647,17 @@
"inflowColumn": "Inflow column",
"outflowColumn": "Outflow column",
"selectColumn": "Select column...",
+ "columnMapping": "Column mapping",
+ "columnMappingHint": "Map your CSV columns to Securo fields. Leave on auto-detect to keep the detected column.",
+ "columnAutoDetect": "Auto-detect",
+ "mappingNeeded": "We couldn't recognize your CSV columns automatically. Map them to Securo fields below to continue.",
+ "mapDate": "Date column",
+ "mapDescription": "Description column",
+ "mapAmount": "Amount column",
+ "mapType": "Type column",
+ "mapCategory": "Category column",
+ "mapCurrency": "Currency column",
+ "mapFxRate": "FX rate column",
"title": "Import",
"subtitle": "Bank statement",
"processing": "Processing file…",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index f481298f..cb1921be 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -647,6 +647,17 @@
"inflowColumn": "Coluna de entrada",
"outflowColumn": "Coluna de saída",
"selectColumn": "Selecionar coluna...",
+ "columnMapping": "Mapeamento de colunas",
+ "columnMappingHint": "Associe as colunas do seu CSV aos campos do Securo. Deixe em automático para manter a coluna detectada.",
+ "columnAutoDetect": "Detectar automaticamente",
+ "mappingNeeded": "Não reconhecemos as colunas do seu CSV automaticamente. Associe-as aos campos do Securo abaixo para continuar.",
+ "mapDate": "Coluna de data",
+ "mapDescription": "Coluna de descrição",
+ "mapAmount": "Coluna de valor",
+ "mapType": "Coluna de tipo",
+ "mapCategory": "Coluna de categoria",
+ "mapCurrency": "Coluna de moeda",
+ "mapFxRate": "Coluna de câmbio",
"title": "Importar",
"subtitle": "Extrato bancário",
"processing": "Processando arquivo…",
diff --git a/frontend/src/pages/import.tsx b/frontend/src/pages/import.tsx
index aa0406d9..716381b7 100644
--- a/frontend/src/pages/import.tsx
+++ b/frontend/src/pages/import.tsx
@@ -23,6 +23,17 @@ const TYPE_LABELS: Record<string, string> = {
investment: 'accounts.typeInvestment',
}
+// Securo fields a CSV column can be mapped to, in display order.
+const CSV_MAPPING_FIELDS = [
+ { key: 'date', label: 'import.mapDate' },
+ { key: 'description', label: 'import.mapDescription' },
+ { key: 'amount', label: 'import.mapAmount' },
+ { key: 'type', label: 'import.mapType' },
+ { key: 'category', label: 'import.mapCategory' },
+ { key: 'currency', label: 'import.mapCurrency' },
+ { key: 'fx_rate', label: 'import.mapFxRate' },
+] as const
+
function toReviewTransactions(txns: ImportPreviewTransaction[]): ImportReviewTransaction[] {
return txns.map((tx, i) => ({
...tx,
@@ -39,7 +50,7 @@ export default function ImportPage() {
const locale = i18n.language === 'en' ? 'en-US' : i18n.language
const queryClient = useQueryClient()
const fileInputRef = useRef<HTMLInputElement>(null)
- const [previewData, setPreviewData] = useState<{ transactions: ImportPreviewTransaction[]; detected_format: string } | null>(null)
+ const [previewData, setPreviewData] = useState<{ transactions: ImportPreviewTransaction[]; detected_format: string; csv_columns?: string[]; parse_error?: string | null } | null>(null)
const [reviewTransactions, setReviewTransactions] = useState<ImportReviewTransaction[]>([])
const [selectedAccount, setSelectedAccount] = useState('')
const [dragOver, setDragOver] = useState(false)
@@ -60,6 +71,7 @@ export default function ImportPage() {
const [csvSplitColumns, setCsvSplitColumns] = useState(false)
const [csvInflowColumn, setCsvInflowColumn] = useState('')
const [csvOutflowColumn, setCsvOutflowColumn] = useState('')
+ const [csvColumnMapping, setCsvColumnMapping] = useState<Record<string, string>>({})
const { data: accountsList } = useQuery({
queryKey: ['accounts'],
@@ -82,10 +94,11 @@ export default function ImportPage() {
})
const previewMutation = useMutation({
- mutationFn: ({ file, options }: { file: File; options?: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string } }) =>
+ mutationFn: ({ file, options }: { file: File; options?: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string; column_mapping?: Record<string, string> } }) =>
transactionsApi.previewImport(file, options),
onSuccess: (data) => {
setPreviewData(data)
+ setCsvHeaders(data.csv_columns ?? [])
setReviewTransactions(toReviewTransactions(data.transactions))
setSearchQuery('')
setFilterCategoryIds([])
@@ -163,6 +176,7 @@ export default function ImportPage() {
setCsvSplitColumns(false)
setCsvInflowColumn('')
setCsvOutflowColumn('')
+ setCsvColumnMapping({})
setCsvHeaders([])
}
@@ -170,35 +184,50 @@ export default function ImportPage() {
setFileName(file.name)
setCurrentFile(file)
resetCsvOptions()
-
- // Extract CSV headers for column mapping
- if (file.name.toLowerCase().endsWith('.csv')) {
- const reader = new FileReader()
- reader.onload = (e) => {
- const text = e.target?.result as string
- const firstLine = text.split('\n')[0]
- if (firstLine) {
- setCsvHeaders(firstLine.split(',').map(h => h.trim()))
- }
- }
- reader.readAsText(file)
- }
-
+ // CSV headers come back from the preview response (csv_columns), which
+ // parses the file server-side and handles any delimiter/quoting.
previewMutation.mutate({ file })
}
- const rePreview = useCallback(() => {
+ // Re-run the preview with the current CSV options. Accepts overrides so a
+ // change handler can pass its new value synchronously instead of waiting
+ // for the corresponding state update to flush.
+ const rePreview = useCallback((overrides?: {
+ date_format?: string
+ flip_amount?: boolean
+ split?: boolean
+ inflow?: string
+ outflow?: string
+ mapping?: Record<string, string>
+ }) => {
if (!currentFile) return
- const options: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string } = {}
- if (csvDateFormat) options.date_format = csvDateFormat
- if (csvFlipAmount) options.flip_amount = true
- if (csvSplitColumns && csvInflowColumn && csvOutflowColumn) {
- options.inflow_column = csvInflowColumn
- options.outflow_column = csvOutflowColumn
+ const dateFormat = overrides?.date_format ?? csvDateFormat
+ const flip = overrides?.flip_amount ?? csvFlipAmount
+ const split = overrides?.split ?? csvSplitColumns
+ const inflow = overrides?.inflow ?? csvInflowColumn
+ const outflow = overrides?.outflow ?? csvOutflowColumn
+ const mapping = overrides?.mapping ?? csvColumnMapping
+
+ const options: { date_format?: string; flip_amount?: boolean; inflow_column?: string; outflow_column?: string; column_mapping?: Record<string, string> } = {}
+ if (dateFormat) options.date_format = dateFormat
+ if (flip) options.flip_amount = true
+ if (split && inflow && outflow) {
+ options.inflow_column = inflow
+ options.outflow_column = outflow
}
+ const cleanMapping = Object.fromEntries(Object.entries(mapping).filter(([, v]) => v))
+ if (Object.keys(cleanMapping).length > 0) options.column_mapping = cleanMapping
previewMutation.mutate({ file: currentFile, options })
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [currentFile, csvDateFormat, csvFlipAmount, csvSplitColumns, csvInflowColumn, csvOutflowColumn])
+ }, [currentFile, csvDateFormat, csvFlipAmount, csvSplitColumns, csvInflowColumn, csvOutflowColumn, csvColumnMapping])
+
+ const handleMappingChange = useCallback((field: string, column: string) => {
+ setCsvColumnMapping(prev => {
+ const next = { ...prev, [field]: column }
+ rePreview({ mapping: next })
+ return next
+ })
+ }, [rePreview])
const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
const file = e.target.files?.[0]
@@ -371,13 +400,20 @@ export default function ImportPage() {
<Settings2 size={14} className="text-muted-foreground" />
<p className="text-xs font-medium text-muted-foreground">{t('import.csvOptions')}</p>
</div>
+
+ {previewData.parse_error && (
+ <div className="flex items-start gap-2 text-xs text-amber-700 bg-amber-50 border border-amber-200 px-3 py-2 rounded-lg mb-3">
+ <AlertCircle size={14} className="shrink-0 mt-0.5" />
+ <span>{t('import.mappingNeeded')}</span>
+ </div>
+ )}
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
<div>
<Label className="text-xs text-muted-foreground mb-1 block">{t('import.dateFormat')}</Label>
<select
className="w-full border border-border rounded-lg px-3 py-1.5 text-sm bg-card text-foreground focus:outline-none focus:ring-2 focus:ring-primary"
value={csvDateFormat}
- onChange={(e) => { setCsvDateFormat(e.target.value); setTimeout(rePreview, 0) }}
+ onChange={(e) => { setCsvDateFormat(e.target.value); rePreview({ date_format: e.target.value }) }}
>
<option value="">{t('import.dateFormatAuto')}</option>
<option value="DD/MM/YYYY">DD/MM/YYYY</option>
@@ -390,7 +426,7 @@ export default function ImportPage() {
type="checkbox"
id="flip-amount"
checked={csvFlipAmount}
- onChange={(e) => { setCsvFlipAmount(e.target.checked); setTimeout(rePreview, 0) }}
+ onChange={(e) => { setCsvFlipAmount(e.target.checked); rePreview({ flip_amount: e.target.checked }) }}
className="rounded border-border text-primary focus:ring-primary"
/>
<Label htmlFor="flip-amount" className="text-sm text-muted-foreground cursor-pointer">
@@ -402,7 +438,7 @@ export default function ImportPage() {
type="checkbox"
id="split-columns"
checked={csvSplitColumns}
- onChange={(e) => setCsvSplitColumns(e.target.checked)}
+ onChange={(e) => { setCsvSplitColumns(e.target.checked); rePreview({ split: e.target.checked }) }}
className="rounded border-border text-primary focus:ring-primary"
/>
<Label htmlFor="split-columns" className="text-sm text-muted-foreground cursor-pointer">
@@ -430,7 +466,7 @@ export default function ImportPage() {
<select
className="w-full border border-border rounded-md px-3 py-1.5 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
value={csvInflowColumn}
- onChange={(e) => { setCsvInflowColumn(e.target.value); setTimeout(rePreview, 0) }}
+ onChange={(e) => { setCsvInflowColumn(e.target.value); rePreview({ inflow: e.target.value }) }}
>
<option value="">{t('import.selectColumn')}</option>
{csvHeaders.map(h => <option key={h} value={h}>{h}</option>)}
@@ -441,7 +477,7 @@ export default function ImportPage() {
<select
className="w-full border border-border rounded-md px-3 py-1.5 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
value={csvOutflowColumn}
- onChange={(e) => { setCsvOutflowColumn(e.target.value); setTimeout(rePreview, 0) }}
+ onChange={(e) => { setCsvOutflowColumn(e.target.value); rePreview({ outflow: e.target.value }) }}
>
<option value="">{t('import.selectColumn')}</option>
{csvHeaders.map(h => <option key={h} value={h}>{h}</option>)}
@@ -449,6 +485,31 @@ export default function ImportPage() {
</div>
</div>
)}
+
+ {/* Column mapping — map CSV headers to Securo fields */}
+ {csvHeaders.length > 0 && (
+ <div className="mt-4 pt-4 border-t border-border">
+ <p className="text-xs font-medium text-muted-foreground">{t('import.columnMapping')}</p>
+ <p className="text-xs text-muted-foreground mt-0.5 mb-3">{t('import.columnMappingHint')}</p>
+ <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+ {CSV_MAPPING_FIELDS
+ .filter((f) => !(csvSplitColumns && f.key === 'amount'))
+ .map((f) => (
+ <div key={f.key}>
+ <Label className="text-xs text-muted-foreground mb-1 block">{t(f.label)}</Label>
+ <select
+ className="w-full border border-border rounded-md px-3 py-1.5 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
+ value={csvColumnMapping[f.key] ?? ''}
+ onChange={(e) => handleMappingChange(f.key, e.target.value)}
+ >
+ <option value="">{t('import.columnAutoDetect')}</option>
+ {csvHeaders.map((h) => <option key={h} value={h}>{h}</option>)}
+ </select>
+ </div>
+ ))}
+ </div>
+ </div>
+ )}
</div>
)}
@@ -490,7 +551,7 @@ export default function ImportPage() {
</button>
<Button
onClick={() => importMutation.mutate()}
- disabled={!selectedAccount || importMutation.isPending}
+ disabled={!selectedAccount || importMutation.isPending || reviewTransactions.length === 0}
className="gap-2"
>
<Upload size={14} />