Chiavi API
Una chiave API consente al sito, all'app o al Suo server di lavorare con il progetto senza accedere all'interfaccia: inviare eventi, leggere profili, gestire segmenti, percorsi e campagne. Le chiavi si creano e si revocano nella sezione «Impostazioni» → «Chiavi API».
La sezione è visibile a «Proprietario», «Amministratore» e «Manager». Possono creare e revocare chiavi il «Proprietario» e l'«Amministratore».
Tipi di chiave
| Scrittura | Segreta | |
|---|---|---|
| Inizia con | cdp_wk_ |
cdp_sk_ |
| Cosa consente | solo l'invio di eventi | l'invio di eventi e le azioni nel progetto secondo i permessi scelti |
| Dove usarla | codice del sito, app mobile, server | solo il Suo server |
| Può essere mostrata a terzi | sì, è visibile nel codice delle pagine del sito | no, va tenuta segreta |
| Limite di richieste | 6000 al minuto | 1200 al minuto (predefinito) |
La chiave di scrittura è pubblica per natura: si trova nel codice di ogni pagina del sito. Con essa si possono solo inviare eventi, quindi una fuga non dà accesso ai dati. Per impedire che un sito altrui invii eventi a Suo nome, nella sezione «Sito web» è possibile indicare i domini da cui la chiave viene accettata: vedi Collegamento del sito.
La chiave segreta dà accesso lato server ai dati del progetto. Non la inserisca mai nel codice delle pagine, nelle app mobili o nei repository pubblici.
Come creare una chiave
- Apra «Chiavi API».
- Nella scheda «Nuova chiave» inserisca il «Nome»: servirà a capire in seguito dove viene usata la chiave, ad esempio «Sito web» o «Server del negozio online».
- Scelga il «Tipo»: Scrittura o Segreta.
- Per una chiave segreta selezioni i «Permessi della chiave»: solo quelli realmente necessari all'integrazione.
- Faccia clic su «Crea chiave».
Subito dopo la creazione, la chiave completa compare in cima alla pagina. Faccia clic su «Copia» e la conservi, ad esempio in un gestore di password o nelle variabili d'ambiente del server. La chiave segreta viene mostrata una sola volta: ne conserviamo solo l'impronta e non è possibile recuperarla. Se la perde, ne crei una nuova e revochi quella vecchia.
La chiave di scrittura per il sito è più comodo crearla direttamente nella sezione «Sito web»: lì viene inserita subito nel codice di installazione ed è disponibile in qualsiasi momento (vedi Collegamento del sito).
Nella tabella delle chiavi sono visibili il nome, chi l'ha creata e quando, il tipo, l'inizio della chiave (ad esempio cdp_sk_a1b2…), il numero di permessi e l'ora dell'ultimo utilizzo.
Permessi della chiave segreta
Si possono concedere alla chiave solo i permessi di cui si dispone. I permessi valgono per l'intero progetto: non è possibile limitare la chiave a singoli percorsi o segmenti.
| Permesso | Cosa consente |
|---|---|
| Lettura dei profili | il profilo per identificatore e i suoi eventi |
| Dati personali non mascherati | email, telefono e altri dati personali in chiaro; senza questo permesso vengono mascherati |
| Modifica di profili e consensi | consensi alle comunicazioni, collegamento a Telegram |
| Eliminazione dei profili (GDPR) | eliminazione del profilo su richiesta del cliente |
| Catalogo di eventi e attributi | elenco degli eventi e delle proprietà dei profili |
| Lettura / modifica dei segmenti | visualizzazione, creazione, modifica, eliminazione e ricalcolo dei segmenti |
| Lettura di percorsi e report; modifica delle bozze e iscrizione dei partecipanti; pubblicazione, pausa e archiviazione dei percorsi | lavoro con i percorsi |
| Lettura di campagne e report; creazione e modifica; avvio, pausa e annullamento | lavoro con le campagne |
| Lettura del catalogo prodotti e delle raccomandazioni; caricamento ed eliminazione dei prodotti | prodotti e raccomandazioni |
| Analisi | report |
Esempio: a una chiave per sincronizzare i clienti VIP dal CRM bastano i permessi «Lettura dei segmenti» e «Modifica dei segmenti».
Tutte le azioni eseguite tramite una chiave segreta vengono registrate nel registro attività del progetto a nome della chiave: vedi Impostazioni del progetto, piano e registro attività.
Come revocare una chiave
- Trovi la chiave nella tabella e faccia clic su «Revoca».
- Confermi l'azione.
Le richieste con questa chiave smettono subito di funzionare (risposta 401). La chiave revocata resta nell'elenco con l'etichetta «Revocata», così da conservarne la cronologia. Non può essere ripristinata: se necessario, ne crei una nuova.
Revochi subito la chiave se potrebbe essere finita in mani estranee, se un dipendente che vi aveva accesso ha lasciato l'azienda o se l'integrazione non è più in uso.
Da sapere
- Limiti. Se si supera il limite di richieste o la quota mensile di eventi del piano, l'API risponde
429. Distribuisca gli invii in modo uniforme e ripeta la richiesta dopo una pausa. - Sostituzione sicura della chiave. Crei una nuova chiave, la aggiorni sul server, verifichi che le richieste arrivino (campo «Ultimo utilizzo») e solo dopo revochi quella vecchia.
- Una chiave per ogni integrazione. In questo modo il registro attività mostra chi ha fatto cosa e, in caso di fuga, basta revocare una sola chiave.
- Come inviare eventi e chiamare l'API dal server è spiegato nell'articolo Integrazione lato server.