FlexiProject offre un’API REST con cui un altro sistema può leggere e modificare i dati dell’organizzazione — alimentare un rapporto di BI, sincronizzare i progetti con un ERP o automatizzare un’attività ripetitiva. La descrizione completa degli endpoint si trova su developers.flexi-project.com.
Per chiamare l’API serve un token di accesso personale (token API). Lo crei tu stesso nel tuo profilo, nella scheda API, e funziona con i tuoi permessi: l’API mostra esattamente i dati che vedi nell’applicazione, e niente di più.
Token di accesso personale
Chi può creare un token
Un token viene creato, per il proprio account, da un utente con licenza Completa (vedi Licenze d’uso) e da un amministratore di sistema; la scheda API è visibile solo a loro. Non serve alcun permesso di amministratore. Il token porta con sé i permessi del suo proprietario, quindi raggiunge gli stessi progetti e gli stessi campi che il proprietario vede nell’applicazione. Due persone con ruoli diversi ottengono risultati diversi dalla stessa richiesta.
Un token smette di funzionare quando l’account viene disattivato, rimosso dall’organizzazione o bloccato, quindi non serve ripulire i token quando qualcuno se ne va.
Creare un token
- Apri il menu dell’avatar, scegli Profilo utente e passa alla scheda API (vedi Profilo utente).
- Clicca su Nuovo token.
- Inserisci un Nome — fino a 100 caratteri. Il nome dovrebbe indicare quale integrazione serve il token, perché è l’unico modo per distinguere in seguito i tuoi token.
- Imposta la Data di scadenza. La più vicina è domani, la più lontana tra 365 giorni da oggi, e il campo si apre su 30 giorni. Il token scade alla fine del giorno scelto.
- Clicca su Crea token.
Copia subito il token
La finestra Il token di accesso personale è stato creato mostra il valore completo una sola volta, con un avviso: Copia il token e conservalo in un luogo sicuro: dopo la chiusura di questa finestra non sarà più possibile leggerlo. Il pulsante Copia copia il valore negli appunti, e tu lo incolli direttamente nel sistema che lo userà. Dopo la chiusura della finestra nessuno può recuperare il valore — né tu, né un amministratore, né l’assistenza. Se perdi un token, eliminalo e creane uno nuovo.
Elenco dei token
La scheda API elenca i tuoi token nelle colonne Nome, Token, Creato il e Scade il. La colonna Token mostra solo i primi caratteri del valore — abbastanza per abbinare un token a quello salvato in un’integrazione.
La colonna Scade il avverte in anticipo: un token che scade entro sette giorni riporta un’etichetta con il numero di giorni rimasti, uno che scade oggi mostra scade oggi, e uno scaduto mostra scaduto. Un token scaduto resta nell’elenco finché non lo elimini, ma non autentica più nulla.
Puoi avere fino a dieci token attivi alla volta. Raggiunto il limite, l’applicazione rifiuta di crearne un altro, con il messaggio Hai già 10 token di accesso personali attivi. Elimina un token inutilizzato per crearne uno nuovo. I token scaduti non contano nel limite.
Eliminare un token
L’icona del cestino nella riga di un token lo elimina dopo la conferma. L’applicazione avverte che le integrazioni che lo utilizzano smetteranno di funzionare immediatamente — ed è proprio così, alla loro richiesta successiva. L’eliminazione non può essere annullata; sostituire un token significa sempre creare un nuovo token con un nuovo valore.
Usare un token
Il token API non viene inviato a ogni richiesta. Lo scambi una volta con un token di accesso e da quel momento usi il token di accesso.
Invia una richiesta POST a /api/user/token/personal con il tuo indirizzo e-mail e il valore del token:
POST /api/user/token/personal
Content-Type: application/json
{ "email": "anna.kowalska@example.com", "token": "fpat_…" }La risposta contiene l’access_token, il suo tipo, l’identificatore dell’organizzazione a cui appartiene il token e il numero di secondi per cui è valido. Invia il token di accesso nell’intestazione Authorization delle chiamate successive e ripeti lo scambio alla sua scadenza.
L’indirizzo e-mail deve appartenere all’account che ha creato il token, ed è il token stesso a decidere in quale organizzazione entri — se lavori in più di una, crea un token separato in ciascuna.
I tentativi falliti ripetuti sono limitati: dopo dieci tentativi falliti per lo stesso indirizzo e-mail, quelli successivi vengono rifiutati per quindici minuti. Se un’integrazione comincia all’improvviso a ricevere rifiuti in massa, controlla il valore salvato invece di riprovare in un ciclo.
Lo scambio di un token API funziona anche quando l’accesso con password è disattivato, perché non è una persona ad accedere (vedi Metodi di accesso).
