Il problema
Freelance, web agency e consulenti IT lavorano con strumenti sparsi: uno per i clienti, uno per i preventivi, un foglio di calcolo per i rinnovi dei domini, un quaderno per gli accessi ai server. In Italia c’è un ostacolo in più. Ogni fattura deve essere emessa in XML FatturaPA e inviata tramite il Sistema di Interscambio (SDI), e la maggior parte dei CRM non lo fa. BalanceAI è nato come CRM della mia attività di consulenza. Poi l’ho ricostruito perché potessero usarlo anche altre aziende.
Cosa ho costruito
Ho realizzato una piattaforma gestionale multi-tenant che riunisce in un unico posto clienti, preventivi, fatture e la parte tecnica del lavoro.
- Nucleo multi-tenant — ogni azienda lavora su dati isolati, perché ogni query è filtrata per tenant. Un pannello di superamministrazione gestisce i tenant, così la stessa installazione può servire una sola azienda o essere offerta come SaaS.
- Fatturazione elettronica italiana — l’app genera l’XML FatturaPA 1.2.1 e lo invia tramite l’API di fatturazione elettronica di Aruba, con il token di accesso conservato in cache per ogni tenant. Pagamenti e scadenze vengono seguiti su ogni fattura.
- Dal preventivo alla fattura — i preventivi con più righe e sconti diventano una fattura in un solo passaggio, così niente va riscritto due volte.
- Domini e server — date di rinnovo, controlli WHOIS automatici e collegamento all’API di cPanel/WHM, così domini e account di hosting in scadenza si vedono prima che diventino un problema per il cliente.
- Cassaforte cifrata — credenziali dei server, password dei clienti e note private sono salvate con AES-256-CBC e un IV casuale nuovo per ogni valore.
- Ricerca clienti con l’AI — scrivi il nome di un’azienda o una partita IVA e un modello OpenAI (GPT-4o mini come predefinito) restituisce indirizzo, PEC e codice SDI in JSON rigoroso per precompilare la scheda cliente. I campi sconosciuti tornano vuoti invece di essere inventati.
- Importazione in blocco — i dati esistenti si importano da file Excel, CSV, Word e PDF.
Con cosa è fatto
Node.js ed Express, con pagine EJS generate dal server e Bootstrap 5 nel front end. I dati stanno in MySQL o MariaDB. Il codice è diviso in 26 router, uno per modulo, e 16 modelli di dati. Gli accessi usano sessioni con password protette da hash bcrypt. Integrazioni: fatturazione elettronica Aruba, WHOIS, cPanel/WHM e API di OpenAI, la cui chiave è salvata cifrata per ogni tenant. Si installa su una VPS dietro Nginx oppure su un hosting cPanel.
Perché è fatto così
BalanceAI è nato come CRM per una sola azienda. La versione 2.0.0 lo ha reso multi-tenant con uno script di migrazione. Lo script aggiunge una colonna tenant a ogni tabella e assegna tutti i record esistenti al tenant 1. I dati reali di anni di utilizzo sono rimasti intatti, e lo stesso codice è diventato un prodotto che altre agenzie possono usare. La regola che ne è derivata è semplice: nessuna query parte senza il filtro per tenant.
