API e integrazioni

Quando entri nel gestionale con il tuo nome utente e la tua password, ti trovi davanti la schermata principale. Sulla sinistra c'è il menu laterale, una colonna di voci su cui cliccare per navigare tra le varie parti del sistema.

Per arrivare alla sezione che ci interessa:

1. Guarda il menu a sinistra.
2. Cerca la voce "API e integrazioni" (in alcune versioni è all'interno di "Impostazioni").
3. Clicca sulla voce per aprire l'elenco delle chiavi e delle integrazioni configurate.

A questo punto la pagina si aggiorna e ti mostra l'elenco delle chiavi API esistenti (se ne hai già create) e i pulsanti per crearne di nuove.

Esempio: se la settimana scorsa hai creato una chiave per collegare il tuo sito web, la ritroverai qui nell'elenco, con il nome che le hai dato.

Se non trovi la voce "API e integrazioni" nel menu, di solito è una questione di permessi: la gestione delle chiavi è un'operazione delicata, spesso riservata agli amministratori. Contatta il tuo amministratore per farti abilitare.

Prima di mettere mano alla configurazione, vale la pena chiarire alcuni termini che ricorreranno in tutta la guida. Non serve impararli a memoria: torna qui ogni volta che un termine non ti è chiaro.

API REST

È il canale di comunicazione tra il gestionale e le tue altre applicazioni. Funziona tramite richieste fatte a indirizzi web speciali, chiamati endpoint. Ogni richiesta chiede al gestionale di fare qualcosa: darmi la lista dei contatti, crea un nuovo cliente, aggiorna questa pratica.

Endpoint

È l'indirizzo a cui si rivolge un'applicazione per uno scopo preciso. C'è un endpoint per i contatti, uno per le pratiche, uno per i prodotti, e così via. Ogni modulo esposto via API ha i propri endpoint.

Chiave API

È una specie di password speciale per i programmi. Quando un'applicazione esterna chiama il gestionale, deve presentare la sua chiave per dimostrare di essere autorizzata. Senza chiave valida, la richiesta viene rifiutata.

Lettura e scrittura

Una integrazione può avere il permesso di leggere i dati (consultarli senza modificarli) e/o di scriverli (crearli, aggiornarli, eliminarli). È buona pratica concedere solo i permessi davvero necessari.

Versioning

Le API hanno una versione (es. "v1"). Serve a garantire che, se in futuro il gestionale cambia il funzionamento delle API, le integrazioni già attive continuino a funzionare. La versione compare nell'indirizzo dell'endpoint.

Regola d'oro: una chiave API è come la chiave di casa. Va custodita, non condivisa via email o chat in chiaro, e può essere revocata in qualsiasi momento se sospetti che qualcuno la conosca.

Tutto ciò che un'integrazione può fare dipende dai permessi della sua chiave e dai moduli che hai deciso di esporre. Una chiave non potrà mai accedere a moduli che non le hai assegnato.

Nella parte superiore della schermata API e integrazioni trovi una serie di campi chiamati filtri di ricerca. Servono a trovare velocemente una chiave o un'integrazione, soprattutto quando ne hai create molte (una per il sito, una per l'e-commerce, una per un gestionale contabile, e così via).

I filtri non modificano, non disattivano e non cancellano nessuna chiave: nascondono temporaneamente quelle che non ti servono, mostrandoti solo le altre.

4.1 Ricerca per testo (nome integrazione)

Il campo di ricerca testuale è il filtro più semplice e più usato. Puoi digitare una parte del nome che hai dato alla chiave o all'integrazione, oppure una parola chiave usata nella descrizione. Il sistema mostra tutte le chiavi che contengono il testo digitato.

Esempi:
Scrivi sito → vedrai tutte le integrazioni con "sito" nel nome.
Scrivi shop → vedrai le chiavi legate al tuo e-commerce.

4.2 Ricerca per stato (attiva/revocata)

Ogni chiave ha uno stato: Attiva (funzionante) o Revocata/Disattivata (non più valida). Selezionando uno stato, il sistema mostra solo le chiavi in quella condizione. È utile, per esempio, per nascondere le chiavi ormai dismesse e concentrarti solo su quelle attive.

Conservare le chiavi revocate (invece di eliminarle subito) ti permette di mantenere uno storico: capirai a colpo d'occhio quali integrazioni hai usato in passato.

4.3 Ricerca per modulo collegato

Se hai assegnato alle chiavi l'accesso a moduli diversi (contatti, pratiche, prodotti, ticket, documenti…), puoi filtrare l'elenco in base al modulo. Vedrai solo le chiavi abilitate a quel modulo.

Esempio: selezionando il modulo "Contatti" vedrai solo le integrazioni autorizzate a leggere o scrivere l'anagrafica clienti.

4.4 Ricerca per date

Puoi filtrare anche in base alle date: data di creazione della chiave, data di scadenza (se impostata) o data dell'ultimo utilizzo. Di solito imposti un intervallo (dal… al…) e il sistema mostra solo le chiavi che vi rientrano.

Attenzione: se imposti un intervallo sbagliato (es. dal 10/01 al 09/01) l'elenco può risultare vuoto. Allarga l'intervallo o usa "Reset filtri".

4.5 Il pulsante "Cerca"

Dopo aver impostato uno o più filtri, per applicarli devi cliccare su "Cerca". Il sistema legge i valori impostati, aggiorna l'elenco e mostra solo le chiavi che corrispondono ai criteri scelti.

Se modifichi un filtro (ad esempio cambi lo stato o il testo), ricordati di cliccare di nuovo su "Cerca" per aggiornare i risultati.

4.6 Il pulsante "Reset filtri"

Per tornare a vedere tutte le chiavi senza alcun filtro attivo, clicca su "Reset filtri": tutti i campi vengono svuotati e l'elenco torna completo.

Se non trovi una chiave che sai esistere, nel 99% dei casi è rimasto attivo un filtro (spesso quello sullo stato "Attiva", che nasconde le chiavi revocate). Il primo passo è sempre cliccare su "Reset filtri".

Una volta impostati (o azzerati) i filtri, nella parte centrale della pagina viene mostrato l'elenco delle chiavi API e integrazioni: una tabella in righe (una per chiave/integrazione) e colonne (le informazioni di ciascuna). Da qui puoi aprire, modificare, sospendere/revocare e, quando previsto, eliminare le chiavi.

Se ti senti "perso", torna sempre alla schermata principale di API e integrazioni: da qui raggiungi qualunque integrazione e tutte le funzioni più usate.

5.1 Struttura generale dell'elenco

L'elenco mostra a colpo d'occhio le informazioni più importanti: una riga di intestazione (in alto) con i nomi delle colonne e tante righe di dati, una per chiave. A seconda della configurazione, le colonne possono includere nome, moduli collegati, permessi (lettura/scrittura), stato, data di creazione, ultimo utilizzo e le icone delle azioni.

Non è necessario capire tutte le colonne subito: inizia da quelle più familiari (nome, stato, moduli) e scopri le altre con calma.

5.2 Le colonne principali

Nome dell'integrazione

Il nome leggibile che hai assegnato alla chiave (es. "Sito web", "E-commerce", "Importazione contatti"). Più il nome è chiaro, più sarà facile capire a cosa serve ogni chiave.

Chiave (parziale)

Per sicurezza, la colonna mostra solo una parte della chiave (es. le ultime quattro cifre) e mai la chiave completa. La chiave intera viene mostrata una sola volta, al momento della creazione.

Moduli collegati

Indica a quali moduli la chiave ha accesso (contatti, pratiche, prodotti, ticket, documenti…). È fondamentale per capire cosa può "toccare" quell'integrazione.

Permessi

Mostra se la chiave può solo leggere o anche scrivere i dati. Una sigla o un'icona ti dice subito il livello di accesso.

Stato

Indica se la chiave è Attiva o Revocata/Sospesa. Solo le chiavi attive funzionano.

Ultimo utilizzo

La data e l'ora dell'ultima volta che la chiave è stata usata. Utile per capire se un'integrazione è ancora viva o ormai abbandonata.

Se una chiave non risulta utilizzata da molto tempo, valuta di revocarla: ridurre il numero di chiavi attive aumenta la sicurezza.

5.3 Colori e indicatori visivi

L'elenco usa alcuni indicatori visivi che ti fanno capire a colpo d'occhio lo stato di ogni chiave. Non devi ricordare nulla a memoria: basta guardare i colori.

• Verde → chiave attiva e funzionante;
• Grigio → chiave revocata o disattivata;
• Arancione → chiave in scadenza (se hai impostato una data di scadenza vicina);
• Rosso → chiave scaduta e quindi non più valida.

Passando il mouse sopra un'icona o un badge può comparire un tooltip, una piccola finestra di testo che ne spiega il significato (es. "Solo lettura · moduli: Contatti, Pratiche").

5.4 Ordinare l'elenco

Puoi ordinare le chiavi cliccando sull'intestazione di una colonna (es. "Ultimo utilizzo" o "Nome"). Una piccola freccia accanto al nome della colonna indica l'ordine: verso l'alto (crescente) o verso il basso (decrescente).

Esempio: cliccando su "Ultimo utilizzo" vedi subito le integrazioni usate più di recente (o, al secondo clic, quelle ferme da più tempo).

5.5 Pagine dell'elenco (paginazione)

Se le chiavi sono molte, l'elenco è suddiviso in più pagine. In fondo alla tabella trovi i numeri di pagina e i pulsanti per andare avanti/indietro o saltare a una pagina specifica.

Se non vedi una chiave che ti aspetti, verifica di trovarti alla prima pagina e non su una pagina successiva.

5.6 Le azioni sulla singola chiave

Nell'ultima parte di ogni riga (di solito a destra) trovi un menu Azioni (icona "▾") con le operazioni disponibili: Apri/Modifica, Rigenera chiave, Revoca/Sospendi ed Elimina (solo quando le regole del gestionale lo permettono).

Nel capitolo successivo vedremo in dettaglio ognuna di queste azioni.

Dall'elenco puoi svolgere tutte le operazioni principali sulla singola integrazione: aprire, modificare, rigenerare, revocare ed eliminare (quando consentito). In alto è quasi sempre presente un pulsante per creare una nuova chiave.

Se non sei sicuro di cosa faccia un'icona, passaci sopra il mouse: spesso compare un tooltip che spiega il significato del pulsante (es. "Rigenera chiave", "Revoca integrazione").

6.1 Aprire / visualizzare una chiave

Per vedere tutti i dettagli di una chiave devi prima aprirla, tramite il menu delle azioni (icona "▾") nell'ultima colonna della riga, scegliendo "Apri" o "Modifica". Verrai portato nella scheda dell'integrazione, dove vedi nome, moduli collegati, permessi, stato e statistiche di utilizzo.

Per motivi di sicurezza, aprendo una chiave esistente non vedrai più la chiave per intero: il valore completo è visibile solo al momento della creazione (o della rigenerazione). Se l'hai persa, dovrai rigenerarla.

6.2 Creare una nuova chiave

La creazione non parte dalla riga, ma da un pulsante dedicato in alto a destra: "Nuova chiave API" o "Nuova integrazione". Cliccandolo, il gestionale ti guida nella scelta del nome, dei moduli e dei permessi.

Vedremo tutti i passaggi della creazione, in dettaglio, in un capitolo dedicato.

6.3 Modificare una chiave

Per cambiare il nome, aggiungere o togliere moduli o aggiornare i permessi usi la modifica, dal menu Azioni o dall'interno della scheda. I campi diventano editabili. Dopo le modifiche clicca sempre su "Salva", altrimenti le modifiche andranno perse.

Modificare i permessi di una chiave esistente ha effetto immediato su tutte le applicazioni che la usano: assicurati che il sito o l'e-commerce collegato non smetta di funzionare se togli un modulo o passi da scrittura a sola lettura.

6.4 Rigenerare una chiave

La rigenerazione sostituisce il valore della chiave con uno nuovo. Si usa quando temi che la chiave sia stata compromessa o quando l'hai persa. Dal menu Azioni clicca "Rigenera chiave": il sistema chiede conferma e mostra il nuovo valore una sola volta.

Dopo la rigenerazione, la vecchia chiave smette immediatamente di funzionare. Ricordati di aggiornare il nuovo valore in tutte le applicazioni che la usano, altrimenti l'integrazione si interromperà.

6.5 Revocare / sospendere una chiave

La revoca disattiva la chiave senza eliminarla: resta nell'elenco con stato "Revocata", ma non funziona più. È l'azione consigliata quando un'integrazione non serve più o quando vuoi bloccarla in fretta. Dal menu Azioni clicca "Revoca" (o "Sospendi"); il sistema chiede conferma.

La revoca è reversibile in molti casi (puoi riattivare la chiave), mentre l'eliminazione è definitiva. In caso di dubbio, revoca prima di eliminare.

6.6 Eliminare una chiave

L'eliminazione rimuove definitivamente la chiave dal sistema. Per sicurezza è in genere consentita solo dopo aver revocato la chiave, così da evitare cancellazioni accidentali di integrazioni ancora attive. Alla conferma, la chiave viene rimossa in modo irreversibile.

Non eliminare una chiave se non sei sicuro che nessuna applicazione la stia ancora usando: le chiamate di quelle applicazioni verranno rifiutate e l'integrazione si bloccherà.

6.7 Riepilogo delle azioni

Dall'elenco puoi aprire (vedere i dettagli), modificare (nome, moduli, permessi), rigenerare (nuovo valore), revocare (disattivare) ed eliminare (solo se revocata e strettamente necessario).

Flusso consigliato: 1) crea la chiave · 2) usala e modificane i permessi se serve · 3) rigenerala se sospetti una compromissione · 4) revocala quando non serve più · 5) eliminala solo dopo un periodo di sicurezza.

La creazione di una chiave API è il primo passo per collegare un'applicazione esterna al gestionale. Il sistema ti guida attraverso pochi passaggi semplici: dai un nome, scegli i moduli, imposti i permessi, salvi e copi la chiave.

Crea una chiave diversa per ogni applicazione (una per il sito, una per l'e-commerce, ecc.). Così, se devi bloccarne una, le altre continuano a funzionare e capisci subito quale integrazione fa cosa.

7.1 Dove si trova il pulsante "Nuova chiave API"

Cerca il pulsante dedicato in alto a destra nella schermata API e integrazioni: si chiama "Nuova chiave API" o "Nuova integrazione". Cliccandolo si apre la scheda di configurazione.

Esempio: devi collegare il modulo di contatto del tuo sito? Clicca "Nuova chiave API" per iniziare.

7.2 Dare un nome all'integrazione

Il primo campo è il nome. Scegline uno chiaro e riconoscibile, perché lo ritroverai nell'elenco e nel registro delle chiamate.

Esempi di buoni nomi: "Sito vetrina - modulo contatti", "E-commerce - sincronizzazione ordini", "Software contabilità - export fatture".

Evita nomi generici come "Chiave 1" o "Test": tra qualche mese non ricorderai a cosa servivano.

7.3 Scegliere i moduli da esporre

Indichi quali moduli la chiave potrà raggiungere: contatti/clienti, pratiche, prodotti, ticket, documenti e gli altri moduli attivi nel tuo gestionale. Seleziona solo i moduli davvero necessari all'integrazione.

Più moduli esponi, più ampia è la "superficie" accessibile dall'esterno. Per sicurezza, concedi a ogni chiave solo i moduli indispensabili al suo scopo.

Esempio: se il sito deve solo registrare nuovi contatti, abilita il solo modulo "Contatti". Non c'è bisogno di esporre pratiche o documenti.

7.4 Impostare i permessi (lettura/scrittura)

Per ogni modulo scegli il livello di accesso: sola lettura (l'integrazione può consultare i dati ma non cambiarli) oppure lettura e scrittura (può anche creare, aggiornare ed eventualmente eliminare).

Applica il principio del minimo privilegio: se un'applicazione deve solo leggere il catalogo prodotti per mostrarlo sul sito, dalle la sola lettura. La scrittura serve solo quando l'esterno deve davvero modificare i dati del gestionale.

Esempio: un e-commerce che invia gli ordini al gestionale ha bisogno della scrittura sul modulo ordini; un sito che mostra il listino ha bisogno della sola lettura sui prodotti.

7.5 Scadenza e limiti

Se il gestionale lo prevede, puoi impostare una data di scadenza per la chiave (dopo la quale smette di funzionare) ed eventuali limiti di utilizzo, come il numero massimo di chiamate al minuto. Sono strumenti di sicurezza utili per le integrazioni temporanee o per evitare sovraccarichi.

Una scadenza è particolarmente utile per le chiavi date a fornitori esterni o per progetti a termine: la chiave si disattiva da sola, senza che tu debba ricordartene.

7.6 Salvare e copiare la chiave

Completati i campi, clicca su "Salva". Il sistema genera la chiave e la mostra per intero una sola volta: copiala subito e incollala nell'applicazione che la userà (o consegnala a chi sviluppa il tuo sito in modo sicuro).

Una volta chiusa la finestra, la chiave completa non sarà più visibile. Se non l'hai copiata, dovrai rigenerarla. Non inviarla mai via email o chat in chiaro.

7.7 Riepilogo della creazione

1. Clicca su "Nuova chiave API".
2. Dai un nome chiaro all'integrazione.
3. Seleziona i moduli da esporre.
4. Imposta i permessi (lettura/scrittura) per ciascun modulo.
5. Imposta eventuale scadenza e limiti.
6. Clicca "Salva" e copia subito la chiave.

Una chiave ben configurata (nome chiaro, moduli minimi, permessi giusti) è più facile da gestire e molto più sicura nel tempo.

Questa parte è un po' più tecnica e interessa soprattutto chi sviluppa l'integrazione. Se non sei un programmatore, ti basta sapere che da qui si trovano gli indirizzi e le regole da passare a chi realizza il collegamento.

8.1 Cosa sono gli endpoint per modulo

Ogni modulo esposto ha i propri endpoint, cioè gli indirizzi web a cui un'applicazione si rivolge per operare su quel modulo. Tipicamente trovi un endpoint per ottenere l'elenco (es. tutti i contatti), uno per il singolo elemento (un contatto specifico), uno per crearne uno nuovo e uno per aggiornarlo.

Esempio (concettuale): un endpoint dei contatti potrebbe avere un indirizzo del tipo /api/v1/contatti. La parte "/contatti" indica il modulo, la parte "/v1" indica la versione.

8.2 Leggere i dati (GET)

La lettura serve a far uscire i dati dal gestionale verso l'applicazione esterna. È l'operazione più sicura, perché non modifica nulla. Si usa, ad esempio, per mostrare sul sito il catalogo prodotti o lo stato di una pratica.

Quando un endpoint restituisce molti risultati, di solito li suddivide in pagine (paginazione), proprio come gli elenchi dentro il gestionale. L'applicazione richiede una pagina per volta.

8.3 Scrivere i dati (creazione e aggiornamento)

La scrittura serve a far entrare dati nel gestionale: creare un nuovo contatto, registrare un ordine, aggiornare una richiesta. Richiede che la chiave abbia il permesso di scrittura sul modulo interessato.

La scrittura modifica i dati reali del gestionale. Prima di attivarla in produzione, conviene fare delle prove con dati di test, così da evitare di inserire informazioni errate o duplicate.

8.4 Come avviene l'autenticazione

Ogni richiesta deve presentare la chiave API, di solito inserita in un'apposita intestazione della richiesta (es. un campo "Authorization" o "X-API-Key"). Il gestionale verifica che la chiave sia valida, attiva e abilitata al modulo richiesto; in caso contrario la richiesta viene rifiutata.

L'autenticazione avviene sempre su connessione cifrata (HTTPS): i dati e la chiave viaggiano protetti. Non usare mai le API su connessioni non sicure.

8.5 Versioning delle API

Le API hanno una versione indicata nell'indirizzo (es. "v1"). Il versioning garantisce stabilità: anche se in futuro vengono introdotte novità in una nuova versione, le integrazioni costruite sulla versione precedente continuano a funzionare senza modifiche urgenti.

Quando svilupperai una nuova integrazione, scegli la versione più recente disponibile. Le versioni vecchie restano attive per non rompere le integrazioni esistenti, ma con il tempo possono essere dismesse: la documentazione segnala sempre la versione consigliata.

8.6 La documentazione tecnica

Dalla sezione API e integrazioni puoi raggiungere la documentazione degli endpoint: elenca per ogni modulo gli indirizzi disponibili, i dati che si possono leggere o scrivere e gli esempi di richiesta e risposta. È il riferimento da consegnare a chi sviluppa l'integrazione.

Non serve che tu capisca ogni dettaglio: ti basta sapere dove si trova la documentazione per passarla al tecnico. Spesso un link "Documentazione API" è presente proprio in questa schermata.

8.7 Provare un endpoint

Alcune versioni includono uno strumento di prova direttamente nella schermata: selezioni un endpoint, indichi la chiave e vedi subito la risposta del gestionale. È utilissimo per verificare che la chiave funzioni e che i permessi siano corretti, prima di collegare l'applicazione vera.

Esempio: provi l'endpoint di lettura dei contatti con la tua chiave; se ricevi l'elenco, la chiave funziona; se ricevi un errore di autorizzazione, controlla moduli e permessi.

Le API trovano applicazione concreta nel collegamento del gestionale ai tuoi strumenti quotidiani. Vediamo gli scenari più comuni, sempre in modo neutro e adattabile a qualsiasi attività.

9.1 Collegare il sito web (form contatti)

Lo scenario più frequente: quando un visitatore compila il modulo di contatto del tuo sito, i dati possono essere inviati automaticamente al gestionale e diventare un nuovo contatto in anagrafica, senza che nessuno li ricopi a mano.

1. Crea una chiave API abilitata al solo modulo Contatti, con permesso di scrittura.
2. Consegna chiave e documentazione a chi gestisce il sito.
3. Il sito userà l'endpoint dei contatti per creare la nuova anagrafica a ogni invio del modulo.

Ogni contatto arrivato dal sito comparirà nell'anagrafica clienti come qualsiasi altro: potrai aprirgli una pratica, inviargli comunicazioni e seguirne lo storico.

9.2 Collegare un e-commerce

Con un negozio online puoi sincronizzare due flussi: dal gestionale al sito (es. il catalogo prodotti e i prezzi, in sola lettura) e dal sito al gestionale (gli ordini e i nuovi clienti, in scrittura).

Esempio: il sito legge il listino dal gestionale per mostrarlo aggiornato; quando un cliente acquista, l'ordine viene scritto nel gestionale, dove prosegue la lavorazione come una normale richiesta.

Per un e-commerce conviene usare due chiavi separate (o una chiave con permessi calibrati per modulo): sola lettura sui prodotti, scrittura su ordini e clienti. Così riduci i rischi in caso di problemi.

9.3 Collegare altre applicazioni

Allo stesso modo puoi collegare software di contabilità, strumenti di marketing, app interne o servizi di automazione. Il principio è sempre lo stesso: una chiave dedicata, i moduli minimi necessari e i permessi giusti.

Se usi piattaforme di automazione "no-code", spesso basta incollare la chiave API e l'indirizzo dell'endpoint: non serve programmare. Verifica però sempre che la connessione sia cifrata e che la chiave abbia solo i permessi indispensabili.

9.4 Consenso e GDPR nelle integrazioni

Quando i dati dei clienti entrano nel gestionale tramite API (per esempio dal modulo del sito), valgono le stesse regole sulla privacy del resto del gestionale. È importante che il sito raccolga i consensi necessari e che li trasmetta insieme ai dati, così da poterli archiviare correttamente.

Non importare anagrafiche o contatti senza una base giuridica adeguata. Invia al gestionale solo i dati per cui hai raccolto il consenso, e registra il consenso insieme al contatto: l'integrazione deve rispettare il GDPR come ogni altra parte del sistema.

9.5 Collegamenti con gli altri moduli

Le API si appoggiano ai moduli che già conosci. Capire i collegamenti ti aiuta a scegliere cosa esporre:

• Anagrafica clienti/contatti: il modulo più esposto, per registrare e leggere i contatti dal sito o dall'e-commerce;
• Documenti: per scambiare file con applicazioni esterne (con attenzione ai permessi e alla privacy);
• Pratiche: per creare o aggiornare lavorazioni a partire da richieste esterne;
• Ticket: per ricevere richieste di assistenza dal sito e farle confluire nella coda del gestionale;
• Calendario: per integrare prenotazioni o appuntamenti raccolti online;
• Comunicazioni email/SMS: per innescare invii a seguito di eventi esterni;
• Area riservata clienti: complementare alle API, offre ai clienti un accesso diretto già pronto, senza dover sviluppare nulla.

Prima di costruire un'integrazione complessa, verifica se l'Area riservata clienti copre già la tua esigenza: in molti casi evita di dover sviluppare codice personalizzato.

Le API aprono una porta verso il gestionale: vanno quindi gestite con attenzione. Questa parte raccoglie le regole pratiche per tenere tutto sotto controllo.

10.1 Buone pratiche di sicurezza

• Crea una chiave diversa per ogni applicazione: così puoi bloccarne una senza fermare le altre.
• Concedi solo i moduli e i permessi indispensabili (principio del minimo privilegio).
• Usa la sola lettura ogni volta che l'applicazione non deve modificare dati.
• Non condividere mai una chiave via email o chat in chiaro; usa canali sicuri.
• Usa sempre connessioni cifrate (HTTPS).
• Revoca le chiavi che non usi più, invece di lasciarle attive.

Meno chiavi attive hai, più è facile tenerle sotto controllo. Fai una "pulizia" periodica revocando le integrazioni dismesse.

10.2 Il registro delle chiamate (log)

Il gestionale tiene traccia delle chiamate API in un registro (log): per ogni chiamata trovi data e ora, chiave usata, modulo e tipo di operazione (lettura/scrittura) ed esito (riuscita o errore). È lo strumento principale per monitorare chi accede ai dati e per diagnosticare i problemi.

Esempio: se il sito segnala che i contatti non arrivano, controlli il registro: vedrai se le chiamate vengono rifiutate (chiave errata o permesso mancante) o se semplicemente non arrivano.

10.3 Rotazione e scadenza delle chiavi

La rotazione consiste nel sostituire periodicamente le chiavi con valori nuovi (tramite la rigenerazione), come misura di sicurezza. Impostare una scadenza alle chiavi temporanee aiuta a non dimenticarne nessuna attiva.

Programma la rotazione delle chiavi più sensibili (quelle con permessi di scrittura su molti moduli) e coordina sempre il cambio con chi gestisce l'applicazione, così non si interrompe il servizio.

10.4 Cosa fare se una chiave è compromessa

Se sospetti che una chiave sia finita nelle mani sbagliate (pubblicata per errore, condivisa con un ex collaboratore, presente in un sistema violato):

1. Revoca subito la chiave o rigenerala: il vecchio valore smette di funzionare all'istante.
2. Consulta il registro per verificare se ci sono stati accessi sospetti.
3. Aggiorna il nuovo valore nell'applicazione legittima che usava la chiave.
4. Se necessario, restringi i permessi della nuova chiave.

In caso di dubbio, agisci sempre per primo sulla sicurezza: meglio interrompere temporaneamente un'integrazione che lasciare attiva una chiave potenzialmente compromessa.

Le risposte alle domande più comuni quando si lavora con le API e le integrazioni. Spesso, se qualcosa non ti è chiaro, la risposta è proprio qui.

11.1 Cos'è esattamente un'API?

È un modo standard con cui due programmi si scambiano informazioni automaticamente. Le API del gestionale permettono ad applicazioni esterne (il tuo sito, un e-commerce, un gestionale contabile) di leggere e, se autorizzate, scrivere i dati senza inserimenti manuali.

11.2 Devo saper programmare per usare le API?

Per configurare le chiavi e i permessi no: lo fai dall'interfaccia, seguendo questa guida. Per collegare un'applicazione su misura, di solito serve un tecnico o uno sviluppatore, a cui consegnerai la chiave e la documentazione. Con le piattaforme di automazione "no-code", spesso basta incollare chiave e indirizzo.

11.3 Quali moduli posso esporre?

Potenzialmente ogni modulo del gestionale: contatti/clienti, pratiche, prodotti, ticket, documenti e altri. Decidi tu, per ogni chiave, quali rendere accessibili.

Esponi solo i moduli che servono davvero a quella specifica integrazione.

11.4 Ho perso la chiave, come la recupero?

Non si recupera: per sicurezza la chiave completa è mostrata una sola volta, alla creazione. Se l'hai persa, usa "Rigenera chiave" dal menu Azioni per ottenerne una nuova, poi aggiornala nell'applicazione che la usa.

11.5 L'integrazione ha smesso di funzionare. Perché?

Le cause più comuni: la chiave è stata revocata o è scaduta, è stata rigenerata (e l'applicazione usa ancora il vecchio valore), oppure le sono stati tolti il modulo o il permesso necessari.

Soluzione rapida: controlla lo stato della chiave nell'elenco, verifica moduli e permessi nella sua scheda e consulta il registro delle chiamate per vedere l'errore esatto.

11.6 Ricevo un errore di autorizzazione. Cosa significa?

Significa che la richiesta è arrivata, ma il gestionale l'ha rifiutata. Di solito perché la chiave non è valida, è revocata/scaduta, oppure non è abilitata a quel modulo o a quel tipo di operazione (es. prova a scrivere con permessi di sola lettura).

Apri la scheda della chiave e verifica: stato Attiva, modulo incluso, permesso corretto (lettura/scrittura).

11.7 Lettura o scrittura: quale permesso scelgo?

Scegli sola lettura se l'applicazione deve solo consultare i dati (es. mostrare il catalogo sul sito). Scegli lettura e scrittura solo se deve anche crearli o modificarli (es. registrare ordini o contatti). Nel dubbio, parti dalla sola lettura.

11.8 Posso collegare il mio sito al gestionale?

Sì. È uno degli usi più comuni: il modulo contatti del sito invia i nuovi contatti all'anagrafica, e un e-commerce può sincronizzare ordini e clienti. Ti basta creare una chiave con i moduli e i permessi giusti e consegnarla a chi gestisce il sito.

11.9 Cosa succede quando cambia la versione delle API?

Grazie al versioning, le integrazioni costruite su una versione continuano a funzionare anche se ne esce una nuova. Le versioni vecchie restano attive per compatibilità e vengono dismesse solo con ampio preavviso: la documentazione indica sempre la versione consigliata.

11.10 Le API rispettano la privacy e il GDPR?

Sì, valgono le stesse regole del resto del gestionale: accesso protetto da chiave, connessione cifrata e tracciabilità nel registro. Sei però tu a dover assicurare che i dati inviati tramite API (es. dal sito) siano raccolti con i consensi necessari e trasmessi correttamente.

11.11 Meglio revocare o eliminare una chiave?

Quasi sempre meglio revocare: disattivi subito la chiave ma la conservi nell'elenco (e nello storico). L'eliminazione è definitiva e va usata solo quando sei certo che la chiave non serva più a nessuno.

11.12 Dove posso trovare altre informazioni?

Puoi consultare la documentazione tecnica degli endpoint (raggiungibile da questa sezione), gli altri argomenti di questo manuale e la sezione "Suggerimenti" presente nei vari moduli del gestionale.

Ricorda: una buona integrazione nasce da una buona configurazione. Nome chiaro, moduli minimi, permessi giusti e chiave custodita con cura: con queste quattro regole eviti la maggior parte dei problemi.