API nel gestionale edile: quando servono davvero, come importare ed esportare i dati di cantiere, cosa chiedere su sicurezza, SdI e privacy GPS.
Un gestionale edile con API permette ad altri programmi di leggere e scrivere i dati di cantiere in automatico: ore lavorate, presenze, materiali, costi, documenti. Così non devi copiarli a mano da un sistema all’altro. Non sempre però ti serve un’API vera e propria. Per molte imprese edili e di impiantistica bastano un buon export in Excel o CSV, un’importazione guidata e qualche automazione. In questa guida trovi quando l’API serve davvero e come importare ed esportare i dati senza errori. Vedi anche cosa chiedere al fornitore su sicurezza, fatturazione elettronica e privacy delle timbrature GPS.
In breve
- L’API serve quando i dati devono passare spesso e da soli tra due sistemi, per esempio dalle timbrature al consulente paghe o alla contabilità.
- Per molti flussi bastano export e import di file (Excel, CSV) o automazioni senza codice. Sono soluzioni più semplici ed economiche.
- Prima di collegare, metti ordine nei dati: codici cantiere, anagrafiche operai e voci di costo uguali in tutti i sistemi.
- Sulla sicurezza chiedi cose precise: autenticazione con OAuth2 o token, connessione HTTPS cifrata e permessi limitati per ogni integrazione.
- Se i dati GPS escono dal gestionale, la privacy resta un tuo obbligo: trasferisci solo l’evento della timbratura, mai uno storico continuo delle posizioni.
Indice
- Cosa sono le API in un gestionale edile
- Quando ti serve davvero un’integrazione
- Quattro modi per far parlare i tuoi sistemi
- Importare i dati di cantiere senza errori
- Esportare i dati di cantiere: cosa e verso chi
- Sicurezza delle API: cosa chiedere al fornitore
- Fatturazione elettronica e SdI
- Timbrature GPS e privacy quando i dati escono dal gestionale
- Il nostro punto di vista
- Edilgestya: i dati di cantiere in un unico gestionale
- Domande frequenti
- Fonti
Cosa sono le API in un gestionale edile
API sta per Application Programming Interface. In pratica è una porta d’ingresso controllata. Un altro programma bussa, si identifica e chiede un dato preciso: “dammi le ore del cantiere Via Roma di ottobre”. Oppure ne consegna uno: “registra questo DDT del fornitore”.
La differenza con un export di file è semplice:
- con l’export qualcuno scarica un file, lo apre, lo controlla e lo carica altrove;
- con l’API i due sistemi si parlano da soli, a orari fissi o appena succede qualcosa.
La maggior parte delle API moderne è di tipo REST. Il dato viaggia su HTTPS in un formato leggibile, di solito JSON. Anche la pubblica amministrazione usa questo modello. L’Agenzia delle Entrate, per esempio, espone per i registratori telematici un servizio REST su connessione HTTPS con TLS 1.2 verso il Sistema di Interscambio.
Per un’impresa edile il punto non è la tecnologia. Il punto è quale dato deve passare, verso chi e quanto spesso.
Quando ti serve davvero un’integrazione
Prima di chiedere “avete le API?”, fai l’elenco dei flussi reali della tua azienda. Ecco i più comuni nel settore edile e impiantistico.
| Flusso | Da dove a dove | Frequenza tipica | Soluzione più adatta |
|---|---|---|---|
| Ore e presenze operai | Gestionale → consulente del lavoro | Mensile | Export Excel/CSV con tracciato concordato |
| Costi di cantiere | Gestionale → contabilità | Settimanale o mensile | Export o API, in base ai volumi |
| Anagrafiche operai e cantieri | Contabilità/paghe → gestionale | All’avvio, poi raramente | Importazione guidata da file |
| Materiali e DDT | Fornitori/magazzino → gestionale | Giornaliera | API o importazione periodica |
| Posizione dei mezzi | Dispositivo GPS → gestionale | Continua | Modulo integrato o API del fornitore telematico |
| Preventivo accettato, fattura emessa | Gestionale → CRM o email | A evento | Automazione via webhook |
| Fatture elettroniche | Gestionale → SdI | A ogni fattura | Canale accreditato o intermediario |
La regola pratica è questa. Se un flusso avviene una volta al mese e lo controlla una persona, un buon export basta. Se avviene ogni giorno, su molti cantieri, e un errore di copia costa caro, allora un’integrazione automatica si ripaga.
Un modo veloce per misurare il problema: conta quante ore al mese l’ufficio passa a ricopiare dati. Poi chiediti quante ore degli operai non vengono registrate affatto. Per la seconda domanda puoi usare il nostro calcolatore del costo delle ore non registrate.
Quattro modi per far parlare i tuoi sistemi
Non esiste solo “API sì o no”. Ci sono quattro livelli, dal più semplice al più impegnativo.
| Metodo | Come funziona | Pro | Contro | Quando sceglierlo |
|---|---|---|---|---|
| Export/Import di file | Scarichi un Excel o CSV e lo carichi altrove | Semplice, nessun costo tecnico | Manuale, rischio di versioni diverse | Flussi mensili, pochi dati |
| Automazione via webhook | Il gestionale avvisa un altro strumento quando succede un evento | Senza codice, veloce da attivare | Solo per eventi semplici | Notifiche, aggiornamento CRM, email |
| API REST | Due software si scambiano dati in automatico | Dati sempre allineati, nessuna copia | Serve un tecnico per configurarla | Flussi giornalieri, volumi alti |
| Integrazione su misura | Uno sviluppo dedicato al tuo caso | Copre esigenze particolari | Costo e tempi più alti | Sistemi vecchi o tracciati unici |
Export e import di file
È il punto di partenza per quasi tutte le ditte. Funziona bene se il file ha sempre le stesse colonne, nello stesso ordine e con gli stessi codici. Il consulente del lavoro, per esempio, vuole quasi sempre un tracciato preciso: matricola, data, cantiere, ore ordinarie, straordinari, trasferte. Concordalo una volta e non cambiarlo più.
Automazioni via webhook
Un webhook è un avviso automatico. Quando nel gestionale succede un evento, il sistema invia un messaggio a un altro strumento. Strumenti come Zapier, Make o n8n ricevono questi avvisi e li trasformano in azioni: una mail al cliente, una riga in un foglio, un’attività nel CRM. Per chi vuole automatizzare preventivi, richieste e follow-up senza sviluppo, una buona base è capire come funziona l’automazione dei flussi CRM nelle imprese che lavorano a domicilio o in cantiere.
API REST
Serve quando i dati devono restare allineati ogni giorno, senza intervento umano. Per esempio, un’impresa con più cantieri aperti e un magazzino centrale. Ogni scarico di materiale deve finire subito sul costo del cantiere giusto.
Integrazione su misura
È la strada per i casi particolari: un vecchio gestionale contabile senza API, un tracciato del consulente molto specifico, un portale fornitore chiuso. Qui conta avere un fornitore che risponda in italiano e valuti il caso con te.
Importare i dati di cantiere senza errori
L’importazione iniziale è il momento più delicato. Se entrano dati sporchi, i report usciranno sbagliati per mesi. Segui questi passi in ordine.
- Scegli cosa importare davvero. Anagrafiche operai attivi, cantieri aperti, mezzi, clienti e fornitori in uso. Lo storico chiuso può restare in archivio.
- Unifica i codici. Ogni cantiere deve avere un codice unico, uguale in contabilità, paghe e gestionale. Lo stesso vale per gli operai: usa la matricola, non il nome.
- Pulisci il file. Togli righe doppie, celle unite, spazi in fondo ai nomi. Usa un solo formato data (gg/mm/aaaa) e la virgola come separatore dei decimali.
- Fai una prova su pochi record. Importa 10 operai e 2 cantieri. Controlla che nomi, codici e qualifiche siano arrivati giusti.
- Importa tutto e verifica i totali. Confronta il numero di righe e qualche totale (per esempio le ore di un mese) tra il file di partenza e il gestionale.
- Blocca la fonte vecchia. Da quel giorno i dati si inseriscono solo nel nuovo sistema. Due fonti aperte creano due verità.
Anche foto, verbali e documenti vanno caricati con un ordine chiaro: cantiere, data, tipo di documento. Vale anche per i materiali visivi prodotti da terzi. Se affidi il monitoraggio dell’avanzamento con drone per le fasi di inizio, metà e fine lavori, archivia ogni ripresa nel cantiere e nella fase giusti. Così resta collegata al controllo avanzamento.
Esportare i dati di cantiere: cosa e verso chi
L’export è il flusso più usato ogni mese. Ecco cosa esce di solito da un gestionale edile e a chi serve.
- Consulente del lavoro: ore per operaio, giorno e cantiere, con straordinari, assenze e trasferte.
- Commercialista o contabilità interna: costi per cantiere divisi per manodopera, materiali, mezzi e subappalti.
- Direzione lavori e committente: rapportini di intervento firmati, foto datate, avanzamento lavori.
- Titolare: margini per cantiere, confronto tra preventivo e consuntivo, produttività delle squadre.
Due consigli pratici. Primo: esporta sempre con gli stessi filtri e lo stesso periodo, così i numeri restano confrontabili mese dopo mese. Secondo: tieni una copia dell’export inviato al consulente. Se una busta paga viene contestata, sai esattamente quali dati sono partiti. Per capire quali report contano davvero per tempi e costi, leggi la nostra guida al software di cantiere per controllare tempi e costi.
Sicurezza delle API: cosa chiedere al fornitore
Un’API apre una porta sui dati della tua azienda: costi, paghe, posizioni, clienti. Deve essere una porta con serratura. Per la pubblica amministrazione, l’AgID ha pubblicato le linee guida su tecnologie e standard per la sicurezza delle API. Anche un’impresa privata le può usare come riferimento serio. I pattern di sicurezza AgID descrivono come proteggere lo scambio tra chi chiede i dati e chi li fornisce.
Non serve essere informatici per fare le domande giuste:
- Come si autentica chi si collega? Cerca risposte come OAuth2 o token firmati (JWT). Una password condivisa via mail non basta.
- La connessione è cifrata? Deve essere HTTPS con TLS 1.2 o superiore.
- Posso limitare i permessi? Un’integrazione con il consulente deve leggere solo le ore, non i margini di cantiere.
- Posso revocare un accesso? Se cambi consulente o fornitore, chiudi la sua chiave in un minuto.
- C’è un registro degli accessi? Devi poter sapere chi ha letto o modificato cosa, e quando.
Non servono per forza soluzioni complesse. L’AgID chiarisce nelle sue domande frequenti sull’interoperabilità che l’autenticazione dei client con MTLS non è obbligatoria. Esistono strade più leggere e comunque sicure.
Fatturazione elettronica e SdI
La fattura elettronica è un caso a parte. Le regole tecniche dell’Agenzia delle Entrate la definiscono come un documento informatico in formato strutturato, trasmesso per via telematica al Sistema di Interscambio. Il collegamento diretto con lo SdI richiede un canale accreditato e requisiti tecnici precisi.
Per questo molti software gestionali si appoggiano a un intermediario già accreditato. Non è un difetto. Chiedi però al fornitore tre cose chiare:
- trasmette le fatture direttamente o tramite un intermediario?
- dove vengono conservate le fatture e per quanto tempo?
- come ricevi notifiche di scarto e fatture passive?
Nel caso di Edilgestya, i moduli per fatturazione elettronica e SAL sono in arrivo. Oggi la fatturazione resta nel tuo sistema contabile. Il gestionale ti dà i dati di cantiere già ordinati da cui partire.
Timbrature GPS e privacy quando i dati escono dal gestionale
Qui l’integrazione tocca la legge. Le timbrature GPS sono dati personali. Se le passi a un altro sistema, gli obblighi privacy viaggiano con loro.
Il Garante si è occupato proprio di un caso simile. In un provvedimento sulla geolocalizzazione dei tecnici, l’app di rilevazione geografica si interfacciava con il gestionale aziendale tramite un web service dedicato. È lo stesso schema di un’integrazione via API. La lezione per un’impresa edile è concreta:
- trasferisci l’evento, non il percorso. Al consulente servono ora di entrata, ora di uscita e cantiere. Non la posizione dell’operaio durante la giornata;
- scrivi a cosa serve il dato. L’informativa ai lavoratori deve dire che la posizione serve alla timbratura di cantiere, non al controllo del comportamento;
- limita chi riceve cosa. Ogni sistema collegato riceve solo i campi che gli servono.
Se hai dubbi su un caso specifico, come mezzi assegnati a una persona o reperibilità, parlane con il tuo consulente del lavoro o con il DPO prima di attivare l’integrazione. Trovi il quadro completo nella nostra guida sulla normativa per la geolocalizzazione dei dipendenti. Per il lato pratico c’è quella sulla timbratura GPS degli operai in cantiere.
Il nostro punto di vista
Ogni settimana parliamo con titolari e uffici che ci chiedono delle API. Quasi sempre, dietro la domanda c’è un altro problema: i dati sono sparsi. Le ore stanno sui fogli dei capicantiere, i costi in un Excel, i mezzi in un altro portale. Collegare tre sistemi disordinati con un’API sposta solo il disordine più in fretta.
Per questo partiamo da un’altra domanda: quanti dati possono vivere in un posto solo? In Edilgestya planning, timbrature GPS da smartphone, mezzi, materiali, foto, documenti e rapportini firmati stanno nello stesso gestionale cloud. Operai, capocantiere e ufficio lavorano con le stesse informazioni, aggiornate in automatico. Meno sistemi da collegare vuol dire meno integrazioni da mantenere e meno errori di copia.
I collegamenti verso l’esterno restano utili, soprattutto verso paghe e contabilità. Ma diventano semplici quando il dato di partenza è già pulito. Su questo dato lavora anche la nostra analisi economica con intelligenza artificiale: ti avvisa per tempo quando il margine di un cantiere scende. Senza un dato unico, nessun algoritmo può farlo bene.
Il nostro consiglio è pratico. Prima unifica i dati di cantiere. Poi decidi quali flussi verso l’esterno meritano un’automazione. Se un collegamento è davvero particolare, ne parliamo insieme con il supporto tecnico in italiano.
— Ufficio
Edilgestya: i dati di cantiere in un unico gestionale
Se vuoi meno file da ricopiare e più dati pronti da esportare, Edilgestya raccoglie in un’unica piattaforma cloud tutto quello che succede in cantiere. Non serve hardware dedicato per le timbrature: gli operai usano l’app sul loro smartphone.
I prezzi sono pubblici:
- Edilgestya: 49 € al mese di canone fisso
- Utenti ufficio: 35 € al mese per utente da 1 a 5, con prezzo per utente che scende al crescere del numero, fino a 15 € dal 36° utente
- Operai (app di cantiere): 8 € al mese per operaio
- Tracciamento flotta GPS: 10 € al mese per mezzo
- Analisi economica IA: 49 € al mese per azienda
- Personalizzazioni su misura: 40 € l’ora
Un esempio: un’impresa con 3 utenti in ufficio e 20 operai spende 49 € + 105 € + 160 €, cioè 314 € al mese. Con l’analisi economica IA il totale diventa 363 € al mese. Scopri il modulo di gestione cantieri o calcola il tuo canone sulla pagina prezzi di Edilgestya →
Stai ancora confrontando soluzioni? Leggi come scegliere un gestionale cloud per imprese edili e cosa deve fare un software di gestione cantieri.
Domande frequenti
Una piccola ditta edile ha bisogno delle API?
Quasi mai all’inizio. Con pochi cantieri e un consulente del lavoro esterno, un export mensile ben fatto copre l’esigenza. L’API diventa utile quando i flussi sono giornalieri e i volumi crescono.
Quali dati di cantiere conviene importare quando cambio gestionale?
Importa anagrafiche operai attivi, cantieri aperti, mezzi, clienti e fornitori in uso. Lo storico dei cantieri chiusi può restare in archivio. Prima dell’import unifica i codici e fai una prova su pochi record.
In che formato esporto le ore per il consulente del lavoro?
Di solito in Excel o CSV, con un tracciato concordato con il consulente: matricola, data, cantiere, ore ordinarie, straordinari, assenze e trasferte. Una volta deciso il tracciato, non cambiarlo. Così ogni mese il file è subito leggibile.
Posso passare i dati GPS delle timbrature a un altro software?
Sì, ma solo i dati che servono allo scopo dichiarato, come ora e cantiere della timbratura. Evita di trasferire storici continui delle posizioni. L’informativa ai lavoratori deve descrivere anche questi passaggi. Nei casi dubbi chiedi al consulente del lavoro o al DPO.
Cosa rende sicura un’API?
Un’autenticazione robusta, come OAuth2 o token firmati, una connessione HTTPS con TLS 1.2 o superiore e permessi limitati per ogni integrazione. Serve anche poter revocare gli accessi e consultare un registro di chi ha usato i dati.
Fonti
- Agenzia delle Entrate: specifiche invio dati da registratore telematico al SdI
- Agenzia delle Entrate: regole tecniche per la fattura elettronica
- AgID: Linee guida tecnologie e standard per la sicurezza delle API
- AgID: Linee guida interoperabilità, pattern di sicurezza
- AgID: domande frequenti sull’interoperabilità
- Garante Privacy: provvedimento sulla geolocalizzazione dei tecnici