Le API (Application Programming Interface) di RecallAI permettono al tuo software, gestionale o sito web di comunicare direttamente con il sistema di recall. Per accedere alle API serve una API Key, una chiave univoca che identifica e autorizza le richieste. Ecco come crearla e usarla in sicurezza.
Cos'e una API Key e a Cosa Serve
Una API Key e una stringa alfanumerica lunga e complessa che funziona come una password per le comunicazioni machine-to-machine. Quando il tuo gestionale vuole inviare un contatto a RecallAI o recuperare lo stato di un recall, include la API Key nella richiesta per dimostrare di essere autorizzato.
A differenza di username e password (usati dagli umani), la API Key e pensata per essere usata dai software in modo automatico, senza intervento manuale.
Creare una API Key in RecallAI
Passo 1: Accedi alle Impostazioni
Dal menu principale, vai in Impostazioni, poi Integrazioni, poi API. Questa sezione e accessibile solo agli amministratori dell'account.
Passo 2: Genera una Nuova Key
Clicca su "Nuova API Key" e compila:
- Nome: un nome descrittivo che ti aiuti a ricordare a cosa serve (es. "Integrazione gestionale studio", "Sito web prenotazioni")
- Permessi: seleziona le operazioni che questa key puo eseguire. Il principio del minimo privilegio suggerisce di dare solo i permessi strettamente necessari
- Scadenza (opzionale): puoi impostare una data di scadenza per key temporanee
Passo 3: Copia e Salva la Key
Importante: la API Key viene mostrata una sola volta al momento della creazione. Copiala e salvala in un luogo sicuro (un password manager, ad esempio). Se la perdi, dovrai generarne una nuova.
Permessi Disponibili
RecallAI offre permessi granulari per le API Key:
- contacts:read - leggere i dati dei contatti
- contacts:write - creare e modificare contatti
- recalls:read - leggere lo stato dei recall
- recalls:write - creare e modificare recall
- campaigns:read - leggere i dati delle campagne
- campaigns:write - creare e gestire campagne
- reports:read - accedere ai report e alle statistiche
- webhooks:manage - gestire i webhook
Per un'integrazione tipica con un gestionale che deve solo inviare contatti e leggere gli esiti dei recall, servono: contacts:write e recalls:read.
Usare la API Key nelle Richieste
La API Key va inclusa nell'header Authorization di ogni richiesta HTTP:
Header: Authorization: Bearer LA_TUA_API_KEY
Tutte le richieste devono essere fatte via HTTPS (mai HTTP). RecallAI rifiuta automaticamente le connessioni non crittografate.
Best Practice di Sicurezza
- Non condividere mai la key via email o chat: usa un password manager o un sistema di gestione segreti
- Una key per integrazione: non usare la stessa key per il gestionale e per il sito web. Se una viene compromessa, puoi revocarla senza impattare l'altra
- Non inserire la key nel codice sorgente: usa variabili d'ambiente o file di configurazione non versionati
- Monitora l'utilizzo: dalla sezione API puoi vedere quante richieste vengono fatte con ogni key e da quali IP
- Ruota le key periodicamente: ogni 6-12 mesi, genera una nuova key e disattiva la vecchia
- Revoca immediatamente le key compromesse: se sospetti che una key sia stata esposta, revocala subito dal pannello
Rate Limiting
Per proteggere il servizio, le API hanno limiti di frequenza:
- 100 richieste al minuto per key (sufficiente per la maggior parte delle integrazioni)
- 5.000 richieste all'ora per key
- Limiti piu alti disponibili per i piani Enterprise
Se raggiungi il limite, la risposta avra codice 429 (Too Many Requests) con un header che indica quando riprovare.
Risorse per Sviluppatori
La documentazione completa delle API e disponibile nel pannello RecallAI, con esempi di codice in Python, PHP, JavaScript e cURL. Se il tuo sviluppatore ha bisogno di supporto, il team tecnico di RecallAI e disponibile per consulenze di integrazione. Scopri tutte le opzioni di integrazione.