satispay-tc 1.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- satispay_tc-1.0.1/LICENSE +25 -0
- satispay_tc-1.0.1/PKG-INFO +378 -0
- satispay_tc-1.0.1/README.md +360 -0
- satispay_tc-1.0.1/pyproject.toml +32 -0
- satispay_tc-1.0.1/setup.cfg +4 -0
- satispay_tc-1.0.1/src/satispay_tc/__init__.py +7 -0
- satispay_tc-1.0.1/src/satispay_tc/__main__.py +5 -0
- satispay_tc-1.0.1/src/satispay_tc/cli.py +182 -0
- satispay_tc-1.0.1/src/satispay_tc/config.py +42 -0
- satispay_tc-1.0.1/src/satispay_tc/exporters/__init__.py +5 -0
- satispay_tc-1.0.1/src/satispay_tc/exporters/qif_exporter.py +41 -0
- satispay_tc-1.0.1/src/satispay_tc/exporters/rejected_exporter.py +54 -0
- satispay_tc-1.0.1/src/satispay_tc/models.py +52 -0
- satispay_tc-1.0.1/src/satispay_tc/parsers/__init__.py +20 -0
- satispay_tc-1.0.1/src/satispay_tc/parsers/base.py +20 -0
- satispay_tc-1.0.1/src/satispay_tc/parsers/csv_parser.py +79 -0
- satispay_tc-1.0.1/src/satispay_tc/parsers/xlsx_parser.py +159 -0
- satispay_tc-1.0.1/src/satispay_tc/processors/__init__.py +6 -0
- satispay_tc-1.0.1/src/satispay_tc/processors/deduplicator.py +41 -0
- satispay_tc-1.0.1/src/satispay_tc/processors/normalizer.py +158 -0
- satispay_tc-1.0.1/src/satispay_tc/processors/splitter.py +84 -0
- satispay_tc-1.0.1/src/satispay_tc/utils/__init__.py +5 -0
- satispay_tc-1.0.1/src/satispay_tc/utils/logger.py +50 -0
- satispay_tc-1.0.1/src/satispay_tc/utils/ui.py +99 -0
- satispay_tc-1.0.1/src/satispay_tc.egg-info/PKG-INFO +378 -0
- satispay_tc-1.0.1/src/satispay_tc.egg-info/SOURCES.txt +28 -0
- satispay_tc-1.0.1/src/satispay_tc.egg-info/dependency_links.txt +1 -0
- satispay_tc-1.0.1/src/satispay_tc.egg-info/entry_points.txt +2 -0
- satispay_tc-1.0.1/src/satispay_tc.egg-info/top_level.txt +1 -0
- satispay_tc-1.0.1/tests/test_pipeline.py +435 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
This is free and unencumbered software released into the public domain.
|
|
2
|
+
|
|
3
|
+
Anyone is free to copy, modify, publish, use, compile, sell, or
|
|
4
|
+
distribute this software, either in source code form or as a compiled
|
|
5
|
+
binary, for any purpose, commercial or non-commercial, and by any
|
|
6
|
+
means.
|
|
7
|
+
|
|
8
|
+
In jurisdictions that recognize copyright laws, the author or authors
|
|
9
|
+
of this software dedicate any and all copyright interest in the
|
|
10
|
+
software to the public domain. We make this dedication for the benefit
|
|
11
|
+
of the public at large and to the detriment of our heirs and
|
|
12
|
+
successors. We intend this dedication to be an overt act of
|
|
13
|
+
relinquishment in perpetuity of all present and future rights to this
|
|
14
|
+
software under copyright law.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
19
|
+
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
20
|
+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
21
|
+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
22
|
+
OTHER DEALINGS IN THE SOFTWARE.
|
|
23
|
+
|
|
24
|
+
For more information, please refer to <https://unlicense.org>
|
|
25
|
+
|
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: satispay-tc
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Convertitore di esportazioni Satispay (Excel/CSV) in formato QIF per software di finanza personale
|
|
5
|
+
Author: Elliot
|
|
6
|
+
License-Expression: Unlicense
|
|
7
|
+
Project-URL: Homepage, https://github.com/gabriprinciott/satispay-tc
|
|
8
|
+
Project-URL: Repository, https://github.com/gabriprinciott/satispay-tc
|
|
9
|
+
Project-URL: Bug Tracker, https://github.com/gabriprinciott/satispay-tc/issues
|
|
10
|
+
Keywords: satispay,qif,personal-finance,buoni-pasto,accounting,converter
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Topic :: Office/Business :: Financial :: Accounting
|
|
14
|
+
Requires-Python: >=3.10
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# Satispay Transaction Converter (`satispay-tc`)
|
|
20
|
+
|
|
21
|
+
> 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.
|
|
22
|
+
|
|
23
|
+
[](https://www.python.org/)
|
|
24
|
+
[](https://unlicense.org/)
|
|
25
|
+
[](#9-requisiti-di-sistema)
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 1. Panoramica e Motivazione
|
|
30
|
+
|
|
31
|
+
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.
|
|
32
|
+
|
|
33
|
+
In Italia, numerose aziende erogano i **buoni pasto** direttamente nell'applicazione **Satispay**. All'interno dell'app coesistono due saldi distinti:
|
|
34
|
+
|
|
35
|
+
1. **Disponibilità:** il saldo personale ricaricato dal conto corrente bancario dell'utente.
|
|
36
|
+
2. **Buoni Pasto:** il carnet di buoni pasto aziendali utilizzabili presso gli esercenti convenzionati.
|
|
37
|
+
|
|
38
|
+
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.
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 2. Caratteristiche Principali
|
|
45
|
+
|
|
46
|
+
- **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.
|
|
47
|
+
- **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.
|
|
48
|
+
- **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`.
|
|
49
|
+
- **Deduplicazione robusta basata su ID:** gestione di report multipli con periodi sovrapposti tramite identificatore univoco normalizzato, con precedenza per le registrazioni approvate.
|
|
50
|
+
- **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`).
|
|
51
|
+
- **Zero dipendenze esterne obbligatorie:** sviluppato esclusivamente con la libreria standard di Python (`zipfile`, `xml.etree`, `csv`, `decimal`, `datetime`, `argparse`).
|
|
52
|
+
- **Doppia modalità di utilizzo:** eseguibile direttamente da repository clonato oppure installabile come pacchetto CLI standard via `pip`.
|
|
53
|
+
- **Logging e reportistica chiari:** output a colori nel terminale e log persistente su file con rotazione automatica (`logs/satispay_tc.log`).
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 3. Come Funziona la Pipeline
|
|
58
|
+
|
|
59
|
+
Il processo di elaborazione si articola nelle seguenti fasi:
|
|
60
|
+
|
|
61
|
+

|
|
62
|
+
|
|
63
|
+
*(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))*
|
|
64
|
+
|
|
65
|
+
### Esempio di Scomposizione di Pagamento Misto
|
|
66
|
+
|
|
67
|
+
Consideriamo una transazione originale registrata da Satispay:
|
|
68
|
+
|
|
69
|
+
- **Esercente:** Ristorante Il Forno
|
|
70
|
+
- **Importo totale:** `-48.00 €`
|
|
71
|
+
- **Quota Disponibilità:** `-24.00 €`
|
|
72
|
+
- **Quota Buoni Pasto:** `-24.00 €`
|
|
73
|
+
|
|
74
|
+
L'applicazione genera:
|
|
75
|
+
|
|
76
|
+
1. Un **movimento contabile** di `-24.00` in `disponibilita.qif` con Payee `Ristorante Il Forno` e causale indicizzata.
|
|
77
|
+
2. Un **movimento contabile** di `-24.00` in `buoni_pasto.qif` con Payee `Ristorante Il Forno` e causale indicizzata.
|
|
78
|
+
|
|
79
|
+
> **Nota:** I due movimenti generati derivano dalla **scomposizione contabile di una singola transazione originale**, non da due pagamenti separati effettuati dall'utente.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 4. Specifiche del Formato di Input
|
|
84
|
+
|
|
85
|
+
L'applicazione elabora i report generati dalla funzione di esportazione dell'app mobile Satispay (sezione *Transazioni* → *Esporta*).
|
|
86
|
+
|
|
87
|
+
### Struttura delle Colonne Attese
|
|
88
|
+
|
|
89
|
+
| Colonna | Significato | Gestione in `satispay-tc` |
|
|
90
|
+
| :--- | :--- | :--- |
|
|
91
|
+
| **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. |
|
|
92
|
+
| **Nome** | Denominazione dell'attività commerciale o controparte | Mappata nel campo Payee (`P`) del file QIF. Se assente, viene usato un segnaposto descrittivo. |
|
|
93
|
+
| **Descrizione** | Descrizione opzionale o nota inserita dall'utente | Integrata nel campo Memo (`M`) del file QIF. |
|
|
94
|
+
| **Importo** | Importo totale della transazione originale (es. `-€48,00`) | Usato come riferimento per la quadratura contabile. |
|
|
95
|
+
| **Tipo** | Tipologia dell'operazione (es. `🏬 a un Negozio`) | Campo informativo non vincolante per il calcolo contabile. |
|
|
96
|
+
| **Stato** | Esito della transazione (es. `✅ Approvato`, `❌ Annullato`) | Determina l'approvazione del movimento. |
|
|
97
|
+
| **Disponibilità** | Quota addebitata sul conto disponibilità personale | Se non nulla, genera il movimento in `disponibilita.qif`. |
|
|
98
|
+
| **Buoni Pasto** | Quota addebitata sui buoni pasto aziendali | Se non nulla, genera il movimento in `buoni_pasto.qif`. |
|
|
99
|
+
| **Disponibilità dopo la transazione** | Saldo progressivo della disponibilità | Campo informativo, ignorato ai fini della conversione. |
|
|
100
|
+
| **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. |
|
|
101
|
+
|
|
102
|
+
### Tolleranza del Parser
|
|
103
|
+
|
|
104
|
+
- **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.
|
|
105
|
+
- **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.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 5. Regole Contabili e Convalida
|
|
110
|
+
|
|
111
|
+
### 5.1 Verifica di Quadratura Contabile
|
|
112
|
+
|
|
113
|
+
Per ogni transazione approvata, l'applicazione applica la seguente verifica con aritmetica esatta `Decimal`:
|
|
114
|
+
|
|
115
|
+
**Importo = Disponibilità + Buoni Pasto**
|
|
116
|
+
|
|
117
|
+
Tutti gli importi vengono valutati con il rispettivo segno algebrico originale (negativo per gli addebiti/uscite, positivo per eventuali rimborsi/accrediti).
|
|
118
|
+
|
|
119
|
+
- **Se i valori corrispondono:** la transazione supera la convalida e viene scomposta nei movimenti contabili.
|
|
120
|
+
- **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.
|
|
121
|
+
|
|
122
|
+
### 5.2 Allocazioni Nulle o Assenti
|
|
123
|
+
|
|
124
|
+
La tabella seguente illustra la scomposizione contabile nei vari scenari possibili:
|
|
125
|
+
|
|
126
|
+
| Importo originale | Disponibilità | Buoni Pasto | Movimento in `disponibilita.qif` | Movimento in `buoni_pasto.qif` | Esito |
|
|
127
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
128
|
+
| `-20.00 €` | `-20.00 €` | `0.00 €` (o vuoto) | Generato (`-20.00`) | Nessuno | Approvato e convertito |
|
|
129
|
+
| `-20.00 €` | `0.00 €` (o vuoto) | `-20.00 €` | Nessuno | Generato (`-20.00`) | Approvato e convertito |
|
|
130
|
+
| `-48.00 €` | `-24.00 €` | `-24.00 €` | Generato (`-24.00`) | Generato (`-24.00`) | Approvato e convertito |
|
|
131
|
+
| `-20.00 €` | vuoto / `0.00 €` | vuoto / `0.00 €` | Nessuno | Nessuno | Scartato (incoerenza contabile) |
|
|
132
|
+
| `0.00 €` | `0.00 €` | `0.00 €` | Nessuno | Nessuno | Nessun movimento contabile |
|
|
133
|
+
|
|
134
|
+
> **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.
|
|
135
|
+
|
|
136
|
+
### 5.3 Gestione degli Stati di Transazione
|
|
137
|
+
|
|
138
|
+
L'applicazione classifica gli stati rilevati nel report come segue:
|
|
139
|
+
|
|
140
|
+
- **Stati approvati:** contengono l'emoji `✅` oppure le parole chiave `approvato`, `approved`, `accettato`, `ok` (confronto non sensibile al maiuscolo/minuscolo).
|
|
141
|
+
- **Stati non approvati:** stati esplicitamente negativi (es. `❌ Annullato`, `Rifiutato`, `Fallito`), transazioni pendenti (`In attesa`) o con campo stato mancante/vuoto.
|
|
142
|
+
|
|
143
|
+
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`.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 6. Deduplicazione e Integrità dei Dati
|
|
148
|
+
|
|
149
|
+
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).
|
|
150
|
+
|
|
151
|
+
### Meccanismo di Deduplicazione
|
|
152
|
+
|
|
153
|
+
1. **Normalizzazione dell'ID:** ogni transazione viene identificata tramite il valore della colonna ID, normalizzato rimuovendo spazi superflui e uniformando il testo in minuscolo.
|
|
154
|
+
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:
|
|
155
|
+
- Se un record precedente non era approvato e ne viene rilevato uno successivo approvato, il record approvato sostituisce quello non approvato.
|
|
156
|
+
- Negli altri casi, viene mantenuto il primo record incontrato e i duplicati successivi vengono scartati con apposita segnalazione di log.
|
|
157
|
+
- Se due record con lo stesso ID presentano dati discordanti (es. importi o date differenti), viene emesso un avviso di warning esplicito nei log.
|
|
158
|
+
3. **Persistenza basata sui file sorgente:**
|
|
159
|
+
- La deduplicazione opera **in memoria** ricostruendo l'insieme delle transazioni dai file presenti nella cartella di input (`workspace`).
|
|
160
|
+
- L'applicazione **non utilizza un database persistente separato**.
|
|
161
|
+
- Di conseguenza, finché i vecchi file sorgente rimangono nella cartella `workspace`, l'idempotenza è garantita ad ogni riesecuzione.
|
|
162
|
+
- 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.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 7. Struttura dei File di Output
|
|
167
|
+
|
|
168
|
+
I file vengono salvati nella cartella specificata (default: `./out`):
|
|
169
|
+
|
|
170
|
+
### 1. `disponibilita.qif` e `buoni_pasto.qif`
|
|
171
|
+
|
|
172
|
+
File in formato standard QIF (*Quicken Interchange Format*) con codifica UTF-8:
|
|
173
|
+
|
|
174
|
+
```text
|
|
175
|
+
!Type:Bank
|
|
176
|
+
D11/04/2026
|
|
177
|
+
T-24.00
|
|
178
|
+
PRistorante Il Forno
|
|
179
|
+
MPranzo [Disponibilità] (Satispay ID: 019ad0fe-572d-7db7-912c-0abc8a4b08db)
|
|
180
|
+
^
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
- `!Type:Bank`: intestazione standard per conti bancari / liquidità.
|
|
184
|
+
- `D<data>`: data formattata (default `%d/%m/%Y`, personalizzabile tramite `-d`). I movimenti sono ordinati cronologicamente in senso crescente.
|
|
185
|
+
- `T<importo>`: importo contabile con due cifre decimali e punto come separatore.
|
|
186
|
+
- `P<beneficiario>`: nome dell'esercente o controparte.
|
|
187
|
+
- `M<memo>`: descrizione originale accompagnata dal tag del conto (`[Disponibilità]` o `[Buoni Pasto]`) e dall'ID transazione Satispay per tracciabilità e riconciliazione.
|
|
188
|
+
- `^`: terminatore di record standard QIF.
|
|
189
|
+
|
|
190
|
+
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.
|
|
191
|
+
|
|
192
|
+
### 2. `transazioni_scartate.csv`
|
|
193
|
+
|
|
194
|
+
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):
|
|
195
|
+
|
|
196
|
+
| Colonna | Descrizione |
|
|
197
|
+
| :--- | :--- |
|
|
198
|
+
| `ID` | Identificativo univoco della transazione |
|
|
199
|
+
| `Data` | Timestamp completo dell'operazione |
|
|
200
|
+
| `Esercente` | Nome dell'esercente |
|
|
201
|
+
| `Descrizione` | Eventuale nota o memo |
|
|
202
|
+
| `Importo_Totale` | Totale della transazione originale |
|
|
203
|
+
| `Disponibilita` | Quota indicata per la disponibilità |
|
|
204
|
+
| `Buoni_Pasto` | Quota indicata per i buoni pasto |
|
|
205
|
+
| `Stato_Rilevato` | Stato originale ed eventuale dettaglio dell'incoerenza |
|
|
206
|
+
| `File_Origine` | Nome del file da cui la riga è stata estratta |
|
|
207
|
+
|
|
208
|
+
### 3. `logs/satispay_tc.log`
|
|
209
|
+
|
|
210
|
+
Log diagnostico dettagliato con livello `DEBUG` e rotazione automatica (fino a 5 MB per file, 3 backup conservati).
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 8. Limiti Noti dei Report Satispay
|
|
215
|
+
|
|
216
|
+
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).
|
|
217
|
+
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.
|
|
218
|
+
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.
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 9. Requisiti di Sistema
|
|
223
|
+
|
|
224
|
+
- **Python:** versione `3.10` o superiore.
|
|
225
|
+
- **Dipendenze esterne obbligatorie:** nessuna. L'applicazione utilizza unicamente moduli inclusi nella libreria standard di Python.
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 10. Installazione ed Esecuzione
|
|
230
|
+
|
|
231
|
+
È possibile utilizzare `satispay-tc` in quattro modalità differenti:
|
|
232
|
+
|
|
233
|
+
### Scenario A: Installazione da repository locale (consigliata)
|
|
234
|
+
|
|
235
|
+
Clonare il repository e installare il pacchetto nel proprio ambiente:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
git clone https://github.com/gabriprinciott/satispay-tc.git
|
|
239
|
+
cd satispay-tc
|
|
240
|
+
python3 -m pip install .
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Il comando `satispay-tc` sarà immediatamente disponibile nel terminale.
|
|
244
|
+
|
|
245
|
+
### Scenario B: Esecuzione standalone diretta (senza installazione)
|
|
246
|
+
|
|
247
|
+
Se si preferisce eseguire l'applicazione al volo senza installare alcun pacchetto nel sistema o nel virtual environment:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
git clone https://github.com/gabriprinciott/satispay-tc.git
|
|
251
|
+
cd satispay-tc
|
|
252
|
+
python3 main.py
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
L'entry point `main.py` include automaticamente la cartella `src` nel percorso di risoluzione dei moduli.
|
|
256
|
+
|
|
257
|
+
### Scenario C: Installazione in modalità sviluppo (editable)
|
|
258
|
+
|
|
259
|
+
Per contribuire al codice sorgente o testare modifiche locali in tempo reale:
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
git clone https://github.com/gabriprinciott/satispay-tc.git
|
|
263
|
+
cd satispay-tc
|
|
264
|
+
python3 -m pip install -e .
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Ogni modifica apportata ai file in `src/` avrà effetto immediato sull'esecuzione del comando `satispay-tc`.
|
|
268
|
+
|
|
269
|
+
### Scenario D: Installazione da PyPI
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
python3 -m pip install satispay-tc
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## 11. Guida Rapida all'Uso
|
|
278
|
+
|
|
279
|
+
### 1. Come esportare i dati da Satispay (Android / iOS)
|
|
280
|
+
|
|
281
|
+
1. Aprire l'applicazione **Satispay** sullo smartphone.
|
|
282
|
+
2. Accedere alla scheda **Profilo** o **Transazioni** e selezionare **Vedi tutte**.
|
|
283
|
+
3. Premere sull'icona **Esporta** in alto a destra.
|
|
284
|
+
4. Selezionare l'intervallo temporale desiderato (massimo 1 anno per volta).
|
|
285
|
+
5. Selezionare il formato **Excel** (`.xlsx`) oppure **CSV**.
|
|
286
|
+
6. Copiare il file scaricato all'interno della cartella `workspace/` del progetto.
|
|
287
|
+
|
|
288
|
+
### 2. Esecuzione base
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
# Se installato con pip:
|
|
292
|
+
satispay-tc
|
|
293
|
+
|
|
294
|
+
# Se eseguito standalone da sorgente:
|
|
295
|
+
python3 main.py
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
L'applicazione leggerà automaticamente tutti i file presenti in `./workspace` e depositerà i file QIF in `./out`.
|
|
299
|
+
|
|
300
|
+
### 3. Esecuzione con parametri personalizzati
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
# Specificare cartelle di input e output personalizzate con log dettagliati
|
|
304
|
+
satispay-tc -i /percorso/miei_report -o /percorso/destinazione -v
|
|
305
|
+
|
|
306
|
+
# Impostare un formato data ISO per i file QIF
|
|
307
|
+
satispay-tc -d "%Y-%m-%d"
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
## 12. Riferimento Argomenti CLI
|
|
313
|
+
|
|
314
|
+
```text
|
|
315
|
+
usage: satispay-tc [-h] [-i INPUT] [-o OUTPUT] [-d DATE_FORMAT] [-v]
|
|
316
|
+
|
|
317
|
+
Convertitore di esportazioni Satispay (Excel / CSV) in formato QIF per software di finanza personale.
|
|
318
|
+
|
|
319
|
+
options:
|
|
320
|
+
-h, --help Mostra questo messaggio di aiuto ed esce
|
|
321
|
+
-i, --input INPUT Cartella contenente i file di esportazione Satispay
|
|
322
|
+
(default: ./workspace, relativo alla cartella di lavoro corrente)
|
|
323
|
+
-o, --output OUTPUT Cartella in cui salvare i file generati
|
|
324
|
+
(default: ./out, relativo alla cartella di lavoro corrente)
|
|
325
|
+
-d, --date-format DATE_FORMAT
|
|
326
|
+
Formato data da utilizzare nei file QIF (default: %d/%m/%Y)
|
|
327
|
+
-v, --verbose Abilita log dettagliati di debug sia a console che su file
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
> **Suggerimento:** I percorsi predefiniti `./workspace` e `./out` sono relativi alla directory da cui viene invocato il comando (*current working directory*).
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## 13. Sviluppo e Test
|
|
335
|
+
|
|
336
|
+
### Esecuzione della Suite di Test
|
|
337
|
+
|
|
338
|
+
Il progetto adotta `unittest` della libreria standard. Per eseguire la suite completa di test:
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
python3 -m unittest discover tests
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
I test coprono:
|
|
345
|
+
- Parsing nativo di file CSV con differenti delimitatori (`;`, `,`, tabulazione) ed encoding.
|
|
346
|
+
- Parsing nativo OpenXML (`.xlsx`, `.xlsm`).
|
|
347
|
+
- Normalizzazione degli importi in valuta europea e seriali data Excel.
|
|
348
|
+
- Validazione contabile con precisione `Decimal` e rilevamento delle anomalie.
|
|
349
|
+
- Scomposizione dei conti (solo Disponibilità, solo Buoni Pasto, mista, saldo singolo).
|
|
350
|
+
- Deduplicazione e gestione di record discordanti.
|
|
351
|
+
- Generazione conforme di file QIF e report CSV degli scarti.
|
|
352
|
+
- Integrazione end-to-end della CLI.
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## 14. Risoluzione dei Problemi (Troubleshooting)
|
|
357
|
+
|
|
358
|
+
### Il comando `satispay-tc` non viene trovato dopo l'installazione
|
|
359
|
+
- 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`).
|
|
360
|
+
- In alternativa, attivare il virtual environment in cui è avvenuta l'installazione prima di eseguire il comando, oppure eseguire tramite `python3 -m satispay_tc.cli`.
|
|
361
|
+
|
|
362
|
+
### Errore `Nessun file di dati trovato in ./workspace`
|
|
363
|
+
- 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`).
|
|
364
|
+
|
|
365
|
+
### File Excel non elaborato o errore di lettura
|
|
366
|
+
- Assicurarsi che il file esportato da Satispay non sia danneggiato (provare a riesportarlo dall'app).
|
|
367
|
+
|
|
368
|
+
### Un file QIF non viene generato (`disponibilita.qif` o `buoni_pasto.qif`)
|
|
369
|
+
- 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.
|
|
370
|
+
|
|
371
|
+
### Transazioni mancanti nei file QIF
|
|
372
|
+
- 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.
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## 15. Licenza
|
|
377
|
+
|
|
378
|
+
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).
|