API e webhook
Aggiornato:
Chiavi API con durata ed elenco IP, webhook e il feed BI in Impostazioni → Integrazioni e API.
Apri Impostazioni in FiattoIn questo articolo
Oltre a SSO/SCIM e al collegamento contabile, Fiatto offre un'API REST, webhook e un feed BI. Li gestisci come amministratore in Impostazioni → Integrazioni e API (/dashboard/settings/integraties).
Passaggi
- Apri Impostazioni (menu dell'account) → scheda Integrazioni e API.
- In Chiavi API crea una chiave: dai un nome, scegli la Durata (30, 90 o 180 giorni oppure 1 anno) e, se vuoi, compila Indirizzi IP consentiti (un indirizzo o intervallo CIDR per riga). Fai clic su Crea chiave e copia subito la chiave: la vedi una sola volta. Nella sandbox la chiave ha
_test_nel nome e funziona solo nell'ambiente di prova. - Mantieni i permessi ridotti al minimo. Una chiave API (scope
api) funziona su/api/v1: lettura e scrittura di richieste di acquisto, fatture di acquisto, contratti, fornitori e programmi; lettura e creazione di clienti e ordini di vendita; lettura e invio di ticket legali; sola lettura di fatture e contratti di vendita, ordini di acquisto, ricevimenti e pagamenti. Un ordine di vendita creato tramite API arriva come bozza, con gli stessi controlli della schermata (come il limite di credito) e unaIdempotency-Keyobbligatoria. I passaggi fissi tra moduli si leggono come feed su/api/v1/handovers. La contabilità generale (registrazioni e bilancio di verifica) e l'audit trail per un SIEM si attivano separatamente per chiave; l'accesso alla contabilità generale lo concede solo un approvatore o un contabile. Una chiave da Connettore BI (Power BI / Excel) ha scopebi.reade funziona solo sul feed OData in sola lettura. - In Webhook aggiungi un endpoint, scegli gli eventi e invia un evento di test; le consegne non riuscite le vedi nel log delle consegne. Ruota segreto crea un nuovo signing secret; quello vecchio resta valido per altre 24 ore. Per ogni endpoint scegli il Formato dei messaggi: Fiatto (predefinito) o CloudEvents 1.0 (lo standard aperto; un passaggio arriva allora esattamente come nel feed). L'elenco degli eventi comprende anche i passaggi (
handover.*) e il ciclo di vita dei contratti, comecontract.created,contract.status_changed,contract.renewedecontract.expired.
Consigli
- Non usare mai le chiavi API in un browser o in un'app mobile. Il rinnovo non è possibile: crea una nuova chiave, inseriscila nella tua integrazione e revoca quella vecchia. Amministratori e autore ricevono un promemoria 14 e 3 giorni prima; una chiave non usata per 90 giorni viene revocata automaticamente dopo un avviso. Un elenco IP si può in seguito solo restringere (Restringi l’elenco IP). Per ogni chiave API, BI e dell'assistente vedi quando e da quale indirizzo è stata usata l'ultima volta; se non ha ancora un elenco IP, Limita a questo indirizzo la limita a quell'indirizzo con un clic.
- Ogni chiave ha per impostazione predefinita un limite di 120 richieste al minuto; leggi gli header
X-RateLimit-*per rallentare prima di un 429. La politica di versionamento è in/api/v1/openapi.jsone negli headerDeprecation/Sunset: una versione viene annunciata come dismessa con almeno 12 mesi di anticipo. - Un SIEM può abbonare un endpoint webhook all'evento degli eventi di sicurezza (accessi, verifica in due passaggi, modifiche di ruoli e criteri, pulsante di emergenza, accesso del supporto).
- Nella sandbox ogni endpoint webhook è un endpoint di test: ogni consegna porta l'intestazione
X-Fiatto-Environment: test(livenel tuo ambiente reale), e chiavi API e webhook di test restano quando svuoti la sandbox. Vedi esercitarsi nella sandbox. - Tutti i collegamenti con il loro stato, le app di terze parti e il portale sviluppatori li trovi in Impostazioni → Integrazioni e app (marketplace) (
/dashboard/settings/koppelingen). Collegare Claude o ChatGPT: assistenti IA esterni. Portare via i dati senza API: esportazione dei dati.