Metadata-Version: 2.4
Name: satispay-tc
Version: 1.0.1
Summary: Convertitore di esportazioni Satispay (Excel/CSV) in formato QIF per software di finanza personale
Author: Elliot
License-Expression: Unlicense
Project-URL: Homepage, https://github.com/gabriprinciott/satispay-tc
Project-URL: Repository, https://github.com/gabriprinciott/satispay-tc
Project-URL: Bug Tracker, https://github.com/gabriprinciott/satispay-tc/issues
Keywords: satispay,qif,personal-finance,buoni-pasto,accounting,converter
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Satispay Transaction Converter (`satispay-tc`)

> Convertitore CLI da report esportati da **Satispay** (Excel `.xlsx`, `.xlsm` e `.csv`) a file **QIF** (*Quicken Interchange Format*) per software di finanza personale, con scomposizione contabile automatica tra **Disponibilità** personale e **Buoni Pasto** aziendali.

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://unlicense.org/)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero%20external-success.svg)](#9-requisiti-di-sistema)

---

## 1. Panoramica e Motivazione

La gestione trasparente delle finanze personali tramite applicazioni dedicate (come **Sure**, **Firefly III**, **GnuCash**, **Actual Budget** o **MoneyManagerEx**) richiede che ogni flusso di cassa sia attribuito al conto corretto.

In Italia, numerose aziende erogano i **buoni pasto** direttamente nell'applicazione **Satispay**. All'interno dell'app coesistono due saldi distinti:

1. **Disponibilità:** il saldo personale ricaricato dal conto corrente bancario dell'utente.
2. **Buoni Pasto:** il carnet di buoni pasto aziendali utilizzabili presso gli esercenti convenzionati.

Quando si effettua un pagamento (ad esempio al supermercato o al ristorante), Satispay consente il **pagamento misto**: parte dell'importo viene scalata dai Buoni Pasto e l'eventuale eccedenza viene addebitata sulla Disponibilità personale. L'estratto conto di Satispay aggrega l'operazione in un'unica transazione.

I comuni software di finanza personale non possono associare una singola transazione a due conti patrimoniali differenti senza un passaggio di scomposizione. **`satispay-tc`** automatizza questo processo, separando ogni transazione originale nei rispettivi **movimenti contabili** ed esportandoli in file QIF pronti per l'importazione.

---

## 2. Caratteristiche Principali

- **Scomposizione contabile automatica:** suddivisione accurata di ogni transazione tra `disponibilita.qif` e `buoni_pasto.qif`. Se un conto ha allocazione pari a zero, nessun movimento fittizio viene generato per quel conto.
- **Verifica rigorosa della quadratura contabile:** convalida aritmetica con precisione decimale esatta (`Decimal`) della formula **Importo = Disponibilità + Buoni Pasto**. Le anomalie non vengono ignorate ma isolate.
- **Filtro degli stati transazione:** elaborazione esclusiva delle transazioni confermate (`✅ Approvato`, `Approved`, `Accettato`, `OK`). Le transazioni annullate, respinte o incoerenti vengono tracciate in `transazioni_scartate.csv`.
- **Deduplicazione robusta basata su ID:** gestione di report multipli con periodi sovrapposti tramite identificatore univoco normalizzato, con precedenza per le registrazioni approvate.
- **Supporto multi-formato con autodetection:** elaborazione trasparente di file Excel (`.xlsx`, `.xlsm`) e file di testo (`.csv`) con rilevamento automatico di delimitatore (`;`, `,`, tabulazione) ed encoding (`UTF-8`, `UTF-8-SIG`, `CP1252`, `Latin-1`).
- **Zero dipendenze esterne obbligatorie:** sviluppato esclusivamente con la libreria standard di Python (`zipfile`, `xml.etree`, `csv`, `decimal`, `datetime`, `argparse`).
- **Doppia modalità di utilizzo:** eseguibile direttamente da repository clonato oppure installabile come pacchetto CLI standard via `pip`.
- **Logging e reportistica chiari:** output a colori nel terminale e log persistente su file con rotazione automatica (`logs/satispay_tc.log`).

---

## 3. Come Funziona la Pipeline

Il processo di elaborazione si articola nelle seguenti fasi:

![Pipeline di elaborazione delle transazioni](https://raw.githubusercontent.com/gabriprinciott/satispay-tc/master/docs/images/processing-pipeline.svg)

*(Il sorgente originale del diagramma è conservato in formato Mermaid nel file [`docs/processing-pipeline.mmd`](https://github.com/gabriprinciott/satispay-tc/blob/master/docs/processing-pipeline.mmd))*

### Esempio di Scomposizione di Pagamento Misto

Consideriamo una transazione originale registrata da Satispay:

- **Esercente:** Ristorante Il Forno
- **Importo totale:** `-48.00 €`
- **Quota Disponibilità:** `-24.00 €`
- **Quota Buoni Pasto:** `-24.00 €`

L'applicazione genera:

1. Un **movimento contabile** di `-24.00` in `disponibilita.qif` con Payee `Ristorante Il Forno` e causale indicizzata.
2. Un **movimento contabile** di `-24.00` in `buoni_pasto.qif` con Payee `Ristorante Il Forno` e causale indicizzata.

> **Nota:** I due movimenti generati derivano dalla **scomposizione contabile di una singola transazione originale**, non da due pagamenti separati effettuati dall'utente.

---

## 4. Specifiche del Formato di Input

L'applicazione elabora i report generati dalla funzione di esportazione dell'app mobile Satispay (sezione *Transazioni* → *Esporta*).

### Struttura delle Colonne Attese

| Colonna | Significato | Gestione in `satispay-tc` |
| :--- | :--- | :--- |
| **Data** | Data e ora della transazione | Convertita nel formato data QIF (default: `DD/MM/YYYY`). Riconosce formati testuali (`MM/DD/YYYY HH:mm`, `DD/MM/YYYY HH:mm`, ISO) e seriali numerici float nativi di Excel. |
| **Nome** | Denominazione dell'attività commerciale o controparte | Mappata nel campo Payee (`P`) del file QIF. Se assente, viene usato un segnaposto descrittivo. |
| **Descrizione** | Descrizione opzionale o nota inserita dall'utente | Integrata nel campo Memo (`M`) del file QIF. |
| **Importo** | Importo totale della transazione originale (es. `-€48,00`) | Usato come riferimento per la quadratura contabile. |
| **Tipo** | Tipologia dell'operazione (es. `🏬 a un Negozio`) | Campo informativo non vincolante per il calcolo contabile. |
| **Stato** | Esito della transazione (es. `✅ Approvato`, `❌ Annullato`) | Determina l'approvazione del movimento. |
| **Disponibilità** | Quota addebitata sul conto disponibilità personale | Se non nulla, genera il movimento in `disponibilita.qif`. |
| **Buoni Pasto** | Quota addebitata sui buoni pasto aziendali | Se non nulla, genera il movimento in `buoni_pasto.qif`. |
| **Disponibilità dopo la transazione** | Saldo progressivo della disponibilità | Campo informativo, ignorato ai fini della conversione. |
| **ID (Comunicalo all'Assistenza Clienti in caso di problemi)** | UUID univoco della transazione Satispay | Utilizzato per la **deduplicazione** (normalizzato) e riportato nel campo Memo (`M`) del QIF. Riconosciuto anche con alias `ID`, `Id`, `Transaction ID`. Se mancante, viene generato un fingerprint hash deterministico. |

### Tolleranza del Parser

- **Report a saldo singolo (senza colonna Buoni Pasto):** se il report proviene da un account privato senza convenzione buoni pasto e non contiene le colonne `Disponibilità` e `Buoni Pasto`, l'intero importo viene automaticamente attribuito alla Disponibilità senza generare errori di quadratura.
- **File temporanei di lock:** file di blocco creati da editor di fogli di calcolo (come `.~lock.*#` di LibreOffice o `~$*` di Microsoft Excel) vengono rilevati e ignorati automaticamente.

---

## 5. Regole Contabili e Convalida

### 5.1 Verifica di Quadratura Contabile

Per ogni transazione approvata, l'applicazione applica la seguente verifica con aritmetica esatta `Decimal`:

**Importo = Disponibilità + Buoni Pasto**

Tutti gli importi vengono valutati con il rispettivo segno algebrico originale (negativo per gli addebiti/uscite, positivo per eventuali rimborsi/accrediti).

- **Se i valori corrispondono:** la transazione supera la convalida e viene scomposta nei movimenti contabili.
- **Se i valori non corrispondono:** la transazione viene contrassegnata come **incoerente**, esclusa dalla generazione dei file QIF e registrata in `transazioni_scartate.csv` con la dicitura `[Incoerenza contabile: Importo != Disp + BP]`. L'errore viene registrato nei log e l'elaborazione dei restanti record prosegue regolarmente.

### 5.2 Allocazioni Nulle o Assenti

La tabella seguente illustra la scomposizione contabile nei vari scenari possibili:

| Importo originale | Disponibilità | Buoni Pasto | Movimento in `disponibilita.qif` | Movimento in `buoni_pasto.qif` | Esito |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `-20.00 €` | `-20.00 €` | `0.00 €` (o vuoto) | Generato (`-20.00`) | Nessuno | Approvato e convertito |
| `-20.00 €` | `0.00 €` (o vuoto) | `-20.00 €` | Nessuno | Generato (`-20.00`) | Approvato e convertito |
| `-48.00 €` | `-24.00 €` | `-24.00 €` | Generato (`-24.00`) | Generato (`-24.00`) | Approvato e convertito |
| `-20.00 €` | vuoto / `0.00 €` | vuoto / `0.00 €` | Nessuno | Nessuno | Scartato (incoerenza contabile) |
| `0.00 €` | `0.00 €` | `0.00 €` | Nessuno | Nessuno | Nessun movimento contabile |

> **Importante:** Le celle vuote (`None`) e i valori numerici espliciti pari a zero (`0.00`) vengono trattati in modo identico come allocazione contabile nulla (`Decimal("0.00")`). I movimenti QIF vengono creati **esclusivamente** per i conti con quota strettamente diversa da zero.

### 5.3 Gestione degli Stati di Transazione

L'applicazione classifica gli stati rilevati nel report come segue:

- **Stati approvati:** contengono l'emoji `✅` oppure le parole chiave `approvato`, `approved`, `accettato`, `ok` (confronto non sensibile al maiuscolo/minuscolo).
- **Stati non approvati:** stati esplicitamente negativi (es. `❌ Annullato`, `Rifiutato`, `Fallito`), transazioni pendenti (`In attesa`) o con campo stato mancante/vuoto.

Tutte le transazioni non approvate vengono scartate dalla conversione QIF e salvate in `transazioni_scartate.csv`, preservando l'esatto testo dello stato originale nel campo `Stato_Rilevato`.

---

## 6. Deduplicazione e Integrità dei Dati

L'applicazione supporta il posizionamento simultaneo nella cartella `workspace` di più file di esportazione con intervalli temporali sovrapposti (ad esempio report semestrali o annuali parzialmente coincidenti).

### Meccanismo di Deduplicazione

1. **Normalizzazione dell'ID:** ogni transazione viene identificata tramite il valore della colonna ID, normalizzato rimuovendo spazi superflui e uniformando il testo in minuscolo.
2. **Deduplicazione in memoria:** durante ogni esecuzione, i record di tutti i file di input vengono aggregati. In presenza di righe con lo stesso ID:
   - Se un record precedente non era approvato e ne viene rilevato uno successivo approvato, il record approvato sostituisce quello non approvato.
   - Negli altri casi, viene mantenuto il primo record incontrato e i duplicati successivi vengono scartati con apposita segnalazione di log.
   - Se due record con lo stesso ID presentano dati discordanti (es. importi o date differenti), viene emesso un avviso di warning esplicito nei log.
3. **Persistenza basata sui file sorgente:**
   - La deduplicazione opera **in memoria** ricostruendo l'insieme delle transazioni dai file presenti nella cartella di input (`workspace`).
   - L'applicazione **non utilizza un database persistente separato**.
   - Di conseguenza, finché i vecchi file sorgente rimangono nella cartella `workspace`, l'idempotenza è garantita ad ogni riesecuzione.
   - Se i vecchi file vengono rimossi dalla cartella e viene successivamente inserito un nuovo export che copre date già elaborate, le transazioni duplicate verranno ri-esportate nei nuovi file QIF.

---

## 7. Struttura dei File di Output

I file vengono salvati nella cartella specificata (default: `./out`):

### 1. `disponibilita.qif` e `buoni_pasto.qif`

File in formato standard QIF (*Quicken Interchange Format*) con codifica UTF-8:

```text
!Type:Bank
D11/04/2026
T-24.00
PRistorante Il Forno
MPranzo [Disponibilità] (Satispay ID: 019ad0fe-572d-7db7-912c-0abc8a4b08db)
^
```

- `!Type:Bank`: intestazione standard per conti bancari / liquidità.
- `D<data>`: data formattata (default `%d/%m/%Y`, personalizzabile tramite `-d`). I movimenti sono ordinati cronologicamente in senso crescente.
- `T<importo>`: importo contabile con due cifre decimali e punto come separatore.
- `P<beneficiario>`: nome dell'esercente o controparte.
- `M<memo>`: descrizione originale accompagnata dal tag del conto (`[Disponibilità]` o `[Buoni Pasto]`) e dall'ID transazione Satispay per tracciabilità e riconciliazione.
- `^`: terminatore di record standard QIF.

Se per uno dei due conti non è presente alcun movimento utile, il rispettivo file QIF non viene creato e la console emette una notifica informativa.

### 2. `transazioni_scartate.csv`

File delimitato da punto e virgola (`;`) che raccoglie tutte le transazioni scartate (sia quelle non approvate da Satispay, sia quelle che hanno fallito la verifica di quadratura contabile):

| Colonna | Descrizione |
| :--- | :--- |
| `ID` | Identificativo univoco della transazione |
| `Data` | Timestamp completo dell'operazione |
| `Esercente` | Nome dell'esercente |
| `Descrizione` | Eventuale nota o memo |
| `Importo_Totale` | Totale della transazione originale |
| `Disponibilita` | Quota indicata per la disponibilità |
| `Buoni_Pasto` | Quota indicata per i buoni pasto |
| `Stato_Rilevato` | Stato originale ed eventuale dettaglio dell'incoerenza |
| `File_Origine` | Nome del file da cui la riga è stata estratta |

### 3. `logs/satispay_tc.log`

Log diagnostico dettagliato con livello `DEBUG` e rotazione automatica (fino a 5 MB per file, 3 backup conservati).

---

## 8. Limiti Noti dei Report Satispay

1. **Esportazione manuale dall'app (assenza di API pubbliche per privati):** Satispay non fornisce API pubbliche per gli utenti privati consumer. L'estrazione dei report richiede l'uso della funzione di esportazione presente nell'app mobile (intervallo massimo: 1 anno per singolo export).
2. **Assenza dei movimenti in entrata (ricariche e accrediti):** i report esportati da Satispay contengono **esclusivamente le transazioni di spesa e rimborso verso esercenti/privati**. Gli accrediti aziendali periodici di buoni pasto e le ricariche del saldo personale effettuate tramite addebito SDD su conto corrente **non sono inclusi** nel file esportato.
3. **Riconciliazione dei saldi:** i file QIF generati rappresentano fedelmente i movimenti presenti negli estratti conto sorgente, ma non costituiscono un bilancio completo a saldo zero. L'utente deve registrare separatamente nel proprio software di finanza personale i movimenti di accredito iniziali e le ricariche periodiche per ottenere la quadratura del saldo contabile.

---

## 9. Requisiti di Sistema

- **Python:** versione `3.10` o superiore.
- **Dipendenze esterne obbligatorie:** nessuna. L'applicazione utilizza unicamente moduli inclusi nella libreria standard di Python.

---

## 10. Installazione ed Esecuzione

È possibile utilizzare `satispay-tc` in quattro modalità differenti:

### Scenario A: Installazione da repository locale (consigliata)

Clonare il repository e installare il pacchetto nel proprio ambiente:

```bash
git clone https://github.com/gabriprinciott/satispay-tc.git
cd satispay-tc
python3 -m pip install .
```

Il comando `satispay-tc` sarà immediatamente disponibile nel terminale.

### Scenario B: Esecuzione standalone diretta (senza installazione)

Se si preferisce eseguire l'applicazione al volo senza installare alcun pacchetto nel sistema o nel virtual environment:

```bash
git clone https://github.com/gabriprinciott/satispay-tc.git
cd satispay-tc
python3 main.py
```

L'entry point `main.py` include automaticamente la cartella `src` nel percorso di risoluzione dei moduli.

### Scenario C: Installazione in modalità sviluppo (editable)

Per contribuire al codice sorgente o testare modifiche locali in tempo reale:

```bash
git clone https://github.com/gabriprinciott/satispay-tc.git
cd satispay-tc
python3 -m pip install -e .
```

Ogni modifica apportata ai file in `src/` avrà effetto immediato sull'esecuzione del comando `satispay-tc`.

### Scenario D: Installazione da PyPI

```bash
python3 -m pip install satispay-tc
```

---

## 11. Guida Rapida all'Uso

### 1. Come esportare i dati da Satispay (Android / iOS)

1. Aprire l'applicazione **Satispay** sullo smartphone.
2. Accedere alla scheda **Profilo** o **Transazioni** e selezionare **Vedi tutte**.
3. Premere sull'icona **Esporta** in alto a destra.
4. Selezionare l'intervallo temporale desiderato (massimo 1 anno per volta).
5. Selezionare il formato **Excel** (`.xlsx`) oppure **CSV**.
6. Copiare il file scaricato all'interno della cartella `workspace/` del progetto.

### 2. Esecuzione base

```bash
# Se installato con pip:
satispay-tc

# Se eseguito standalone da sorgente:
python3 main.py
```

L'applicazione leggerà automaticamente tutti i file presenti in `./workspace` e depositerà i file QIF in `./out`.

### 3. Esecuzione con parametri personalizzati

```bash
# Specificare cartelle di input e output personalizzate con log dettagliati
satispay-tc -i /percorso/miei_report -o /percorso/destinazione -v

# Impostare un formato data ISO per i file QIF
satispay-tc -d "%Y-%m-%d"
```

---

## 12. Riferimento Argomenti CLI

```text
usage: satispay-tc [-h] [-i INPUT] [-o OUTPUT] [-d DATE_FORMAT] [-v]

Convertitore di esportazioni Satispay (Excel / CSV) in formato QIF per software di finanza personale.

options:
  -h, --help            Mostra questo messaggio di aiuto ed esce
  -i, --input INPUT     Cartella contenente i file di esportazione Satispay
                        (default: ./workspace, relativo alla cartella di lavoro corrente)
  -o, --output OUTPUT   Cartella in cui salvare i file generati
                        (default: ./out, relativo alla cartella di lavoro corrente)
  -d, --date-format DATE_FORMAT
                        Formato data da utilizzare nei file QIF (default: %d/%m/%Y)
  -v, --verbose         Abilita log dettagliati di debug sia a console che su file
```

> **Suggerimento:** I percorsi predefiniti `./workspace` e `./out` sono relativi alla directory da cui viene invocato il comando (*current working directory*).

---

## 13. Sviluppo e Test

### Esecuzione della Suite di Test

Il progetto adotta `unittest` della libreria standard. Per eseguire la suite completa di test:

```bash
python3 -m unittest discover tests
```

I test coprono:
- Parsing nativo di file CSV con differenti delimitatori (`;`, `,`, tabulazione) ed encoding.
- Parsing nativo OpenXML (`.xlsx`, `.xlsm`).
- Normalizzazione degli importi in valuta europea e seriali data Excel.
- Validazione contabile con precisione `Decimal` e rilevamento delle anomalie.
- Scomposizione dei conti (solo Disponibilità, solo Buoni Pasto, mista, saldo singolo).
- Deduplicazione e gestione di record discordanti.
- Generazione conforme di file QIF e report CSV degli scarti.
- Integrazione end-to-end della CLI.

---

## 14. Risoluzione dei Problemi (Troubleshooting)

### Il comando `satispay-tc` non viene trovato dopo l'installazione
- Assicurarsi che la directory degli script dell'utente di Python sia inclusa nella variabile d'ambiente `PATH` del sistema (su Linux/macOS solitamente `~/.local/bin`, su Windows `%APPDATA%\Python\PythonXX\Scripts`).
- In alternativa, attivare il virtual environment in cui è avvenuta l'installazione prima di eseguire il comando, oppure eseguire tramite `python3 -m satispay_tc.cli`.

### Errore `Nessun file di dati trovato in ./workspace`
- Verificare che i file scaricati da Satispay siano stati inseriti all'interno della cartella `workspace` e non abbiano estensioni non riconosciute (le estensioni supportate sono `.xlsx`, `.xlsm`, `.csv`).

### File Excel non elaborato o errore di lettura
- Assicurarsi che il file esportato da Satispay non sia danneggiato (provare a riesportarlo dall'app).

### Un file QIF non viene generato (`disponibilita.qif` o `buoni_pasto.qif`)
- Se nell'intervallo temporale analizzato tutte le spese sono state coperte al 100% da un solo conto (es. tutti pagamenti tramite Buoni Pasto), l'applicazione non genera un file vuoto per il conto non movimentato. Questo comportamento è voluto.

### Transazioni mancanti nei file QIF
- Verificare il file `out/transazioni_scartate.csv`: se una transazione non aveva stato approvato (`❌ Annullato`, respinte) oppure presentava un'incoerenza contabile tra totale e quote, è stata registrata tra gli scarti con l'indicazione esatta del motivo.

---

## 15. Licenza

Questo progetto è rilasciato nel pubblico dominio sotto licenza **The Unlicense**. È possibile consultare il testo completo nel file [`LICENSE`](https://github.com/gabriprinciott/satispay-tc/blob/master/LICENSE).
