Chiave API: integrare un altro sistema nel tuo studio
Che cos’è
Sezione intitolata “Che cos’è”La chiave API consente a un altro sistema (un ERP, un foglio di calcolo automatico, un sito, una tua app) di consultare e inserire dati del tuo studio senza che nessuno debba digitare nulla. Ogni chiave agisce come un utente dello studio: può fare esattamente ciò che può fare quell’utente, e niente di più.
Quando usarlo
Sezione intitolata “Quando usarlo”- Un sistema gestionale deve leggere le vendite del giorno per la contabilità.
- Un sito o una tua app deve registrare clienti o consultare il catalogo.
- Un’automazione deve registrare spese o consultare i crediti da incassare.
Prima di iniziare
Sezione intitolata “Prima di iniziare”Solo chi amministra lo studio (con accesso completo o con l’autorizzazione a modificare Profili e Utenti) può creare, modificare e revocare le chiavi. Se non riesci a creare una chiave, chiedi al titolare dello studio di abilitarti in Accessi → Profili.
Ti consigliamo di creare prima un utente dedicato all’integrazione, con un profilo che abiliti solo le schermate necessarie all’altro sistema. La chiave eredita le autorizzazioni di questo utente.
Passo dopo passo
Sezione intitolata “Passo dopo passo”Passaggio 1 — Aprire la scheda API Key
Sezione intitolata “Passaggio 1 — Aprire la scheda API Key”In Impostazioni → Azienda, apri la scheda API Key. Qui trovi l’elenco delle chiavi già create, con l’utente associato a ciascuna, gli IP consentiti, la Validità e l’Ultimo utilizzo.
Passaggio 2 — Creare la chiave
Sezione intitolata “Passaggio 2 — Creare la chiave”Fai clic su Nuova chiave, inserisci il Nome e scegli l’Utente. In IP consentiti, inserisci un IP o un intervallo per riga per accettare chiamate solo da questi indirizzi (se il campo è vuoto, è accettato qualsiasi IP). In Validità, scegli Non scade mai oppure Scade il e seleziona una data: la chiave è valida fino alla fine di quel giorno. Fai clic su Crea chiave e copia la chiave con il pulsante di copia. Non verrà mostrata di nuovo.
L’altro sistema deve inviare la chiave con ogni chiamata, nell’intestazione Authorization, così:
Authorization: Bearer hk_... (sostituisci hk_... con la chiave completa).
Per usare la chiave con un’IA (Claude Code, Gemini CLI, Cursor), seleziona anche Consenti l’uso come connettore IA in Connettore IA. Senza questa opzione, la chiave funziona con le integrazioni, ma non con il connettore. Consulta l’articolo Connettore IA.
Passaggio 3 — Revocare una chiave
Sezione intitolata “Passaggio 3 — Revocare una chiave”Nell’elenco, fai clic sull’icona del cestino accanto alla chiave e conferma con Revoca. Il sistema che usava la chiave perderà l’accesso entro 30 secondi. Per modificare il nome, gli IP o la validità, usa l’icona della matita.
Cosa succede dopo
Sezione intitolata “Cosa succede dopo”- Tutte le modifiche apportate dall’altro sistema con la chiave vengono registrate nell’Audit con origine Chiave API, a nome dell’utente associato alla chiave.
- La chiave smette automaticamente di funzionare quando scade o quando il suo utente viene disattivato nello studio. Nell’elenco, appare come Scaduta o Utente inattivo.
- Una chiave non dà mai accesso a un’altra azienda, anche se il suo utente lavora anche in un altro studio.
Errori comuni e domande
Sezione intitolata “Errori comuni e domande”D: La chiave può fare qualsiasi cosa nel sistema? R: No. Ha le autorizzazioni del suo utente, solo in questo studio. Alcune aree non accettano mai chiavi, nemmeno quelle di un utente con accesso completo: accesso e cambio azienda, la schermata delle chiavi, la gestione di utenti e inviti, Heya, l’assistenza, i dashboard, le impostazioni generali dell’Azienda (logo, orari, festività, dominio, e-mail dei report) e le schermate della piattaforma. Se hai più integrazioni, crea un utente per ciascuna: nell’Audit, le modifiche risulteranno a nome dell’utente associato alla chiave.
D: Ho perso la chiave. Posso visualizzarla di nuovo? R: No. Il sistema conserva solo un’impronta della chiave, mai la chiave vera e propria. Revoca la chiave precedente e creane una nuova.
D: L’altro sistema riceve il messaggio “Questo IP non è autorizzato a usare questa chiave API.” Cosa devo fare? R: L’IP da cui effettua la chiamata non è incluso in IP consentiti. Modifica la chiave e aggiungi l’IP oppure lascia vuoto l’elenco per accettare qualsiasi IP.
D: L’altro sistema riceve il messaggio “Questa route non può essere usata con una chiave API.” Perché? R: Sta chiamando una delle aree che non accettano chiavi (vedi la prima domanda). Queste operazioni devono essere eseguite da una persona, dalla schermata.
D: Posso cambiare l’utente associato a una chiave? R: No. Revoca la chiave e creane un’altra con il nuovo utente.
D: L’elenco degli utenti per la nuova chiave è vuoto. Perché? R: Gli utenti del team della piattaforma non possono avere chiavi API e non vengono mostrati nell’elenco. Registra un utente dello studio (preferibilmente uno dedicato all’integrazione) e crea la chiave per lui.