Vai al contenuto

API e webhook

Aggiornato:

Chiavi API con durata ed elenco IP, webhook e il feed BI in Impostazioni → Integrazioni e API.

Apri Impostazioni in Fiatto
In 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

  1. Apri Impostazioni (menu dell'account) → scheda Integrazioni e API.
  2. 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.
  3. 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 una Idempotency-Key obbligatoria. 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 scope bi.read e funziona solo sul feed OData in sola lettura.
  4. 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, come contract.created, contract.status_changed, contract.renewed e contract.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.json e negli header Deprecation/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 (live nel 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.
Questo articolo ti è stato utile?
Vedi tutti gli articoli di questo argomento

Trova un’altra risposta

Basta un’attività, una funzione o una breve domanda.