Le chiavi API

Una chiave API è la credenziale che un gestionale, un middleware (come Zapier) o un sistema esterno usa per collegarsi alla API pubblica di Accordyx, in lettura o scrittura a seconda degli scope che le assegni.

Creare una chiave

1. Nel tab Chiavi API, premi Nuova chiave.
2. Nel dialog Nuova chiave API, inserisci un Nome che ti aiuti a riconoscerla (es. "Connettore ERP", "Zapier"), fino a 80 caratteri.
3. Spunta gli scope da assegnare: «Leggi controparti», «Leggi contratti», «Leggi scadenze», «Export CSV», «Crea/modifica controparti», «Crea contratti», «Gestisci webhook». Di default sono selezionati solo i quattro scope di lettura («Leggi controparti», «Leggi contratti», «Leggi scadenze», «Export CSV»): gli scope di scrittura e la gestione dei webhook li aggiungi tu, solo se servono.
4. Premi Crea chiave.
5. Nel dialog Chiave creata, copia subito la chiave mostrata: per sicurezza non sarà più visibile dopo la chiusura di questa finestra. Conferma con Ho copiato la chiave.

Da questo momento, in Accordyx resta salvato solo un prefisso della chiave (es. "ak_live_3f9a…") per riconoscerla in lista — mai la chiave completa.

Cosa consente ogni scope

• Leggi controparti, Leggi contratti, Leggi scadenze — lettura dei dati e, per i contratti, dell'elenco dei loro documenti.
• Export CSV — esportazione di controparti e contratti in CSV.
• Crea/modifica controparti — creazione e aggiornamento delle controparti.
• Crea contratti — creazione dei contratti per soli dati, caricamento del documento del contratto e aggiornamento di dati, stato e controparte di un contratto esistente: vedi Caricare e aggiornare contratti via API.
• Gestisci webhook — iscrizione e cancellazione dei webhook via API, necessaria anche per i trigger di Zapier.

I contratti creati o aggiornati tramite una chiave risultano fatti dalla persona che ha creato la chiave.

Cosa vedi in lista

Ogni chiave mostra nome, prefisso, scope assegnati, data di creazione e l'ultimo utilizzo, oppure "mai usata" se non è ancora stata chiamata. L'ultimo utilizzo si aggiorna al massimo una volta al minuto.

Revocare una chiave

1. Sulla riga della chiave, premi Revoca.
2. Conferma su Revoca chiave. Da questo momento le richieste che usano quella chiave vengono rifiutate immediatamente; l'operazione non è reversibile.

La chiave revocata resta visibile in lista con un badge "revocata", così mantieni lo storico di cosa è stato collegato nel tempo.

Limiti

Ogni chiave è limitata a 60 richieste al minuto; oltre questa soglia le richieste vengono rifiutate finché il minuto non si rinnova. Ogni organizzazione può avere al massimo 20 chiavi attive: le chiavi revocate non contano. Per gli altri limiti vedi Errori e limiti dell'API.

Problemi comuni

• "Limite di 20 chiavi attive raggiunto" — revoca le chiavi che non usi più, poi crea la nuova.
• La creazione della chiave viene rifiutata con un messaggio sulla funzione «API pubblica» — la API non è disponibile per la tua organizzazione: vedi L'API non è disponibile per la mia organizzazione.
• "Dai un nome alla chiave (es. "Connettore ERP")" — il campo Nome è obbligatorio.
• "Seleziona almeno uno scope" — devi spuntare almeno uno scope prima di creare la chiave.
• "Copia non riuscita: seleziona e copia manualmente" — se il pulsante di copia non funziona, seleziona il testo della chiave a mano prima di chiudere il dialog.