Integrazione API è completata quando evento attraversa sistemi senza duplicare operazioni, perdere dati o lasciare errori invisibili.
«Collegare CRM e gestionale» non è uno scope. Servono evento, fonte autorevole, identificatore, direzione, latenza e comportamento in caso di conflitto.
Parti dall’evento e dal contratto dati
Scrivi eventi osservabili: cliente creato, ordine confermato, pagamento fallito, documento aggiornato. Per ogni evento indica chi possiede verità e come destinatario conferma stato.
Contratto descrive campi obbligatori, formati, enum, timezone, valuta, unità, null e trasformazioni. Esempio reale anonimizzato vale più di una tabella generica. OpenAPI 3.1 rende endpoint, schemi, parametri e risposte revisionabili.
REST, webhook, polling o batch
| Meccanismo | Uso | Rischio |
|---|---|---|
| REST sincrono | Risposta immediata | Timeout e dipendenza runtime |
| Webhook | Notifica evento | Firma, duplicati, ordine |
| Polling | Nessun webhook | Rate limit e cursore |
| Batch | Volumi o riconciliazione | File parziali e ripartenza |
Spesso webhook serve velocità e processo periodico trova eventi persi. RFC 9110 definisce semantica HTTP: non usare GET per modificare stato e non assumere che ogni retry sia sicuro.
Autenticazione non significa autorizzazione
Chiave API, OAuth 2.0, certificato client e token firmato risolvono problemi diversi. Definisci creazione, rotazione, revoca, permessi minimi, separazione ambienti, scadenza e risposta a compromissione. Segreti restano fuori repository.
OWASP API Security Top 10 include autorizzazione a livello di oggetto e funzione, consumo incontrollato di risorse, inventario incompleto e uso insicuro di API terze. Token valido non autorizza automaticamente ogni record.
Idempotenza, retry e ordine
- Assegna identificatore evento stabile.
- Registra ricezione e risultato.
- Usa idempotency key dove operazione può ripetersi.
- Applica timeout espliciti.
- Limita retry con backoff e jitter.
- Invia errori permanenti a revisione.
- Consenti replay autorizzato e tracciato.
Due webhook possono arrivare invertiti. Se ordine conta, specifica chi lo garantisce e come vengono respinti o ricostruiti stati vecchi.
Versionamento e test del contratto
Versionare non significa soltanto aggiungere `/v2`. Rimuovere campo, cambiarne significato o restringere enum può rompere consumer con URL invariata. Definisci cambi compatibili, periodo di deprecazione e comunicazione.
Contract test e sample payload catturano rotture prima della produzione. Test di accettazione include happy path, credenziale scaduta, timeout, rate limit, payload invalido, duplicato, evento fuori ordine, provider indisponibile e replay.
Osservabilità e riconciliazione
- Correlation ID da sorgente a destinazione.
- Contatori di successi, retry, scarti e latenza.
- Log strutturati con dati minimizzati.
- Alert con soglia e proprietario.
- Coda degli eventi non riconciliati.
- Runbook per replay, revoca e degrado.
SLO deve descrivere risultato di business. Uptime endpoint non dice quanti ordini sono incoerenti.
Privacy e minimizzazione
Mappa finalità, categorie di dati, destinatari, trasferimenti e conservazione. GDPR richiede minimizzazione e protezione adeguata al rischio. Non inviare intero profilo se bastano ID e stato.
Decidi ruoli privacy e come rettifica o cancellazione si propaga. Pseudonimizzazione riduce esposizione, ma non elimina automaticamente obblighi.
Cosa determina il preventivo
Non esiste prezzo per «una API». Variabili: documentazione, eventi, endpoint, autenticazione, sandbox, trasformazioni, bidirezionalità, retry, riconciliazione, privacy, test, rollout e supporto.
Separa discovery, implementazione, collaudo con provider, rilascio e monitoraggio. Usa preventivo sviluppo software per clausole. Se integrazione nasce da processo manuale, mappalo con digitalizzazione processi aziendali.
L’automazione AI è intento diverso: può consumare API ma aggiunge qualità modello e controllo umano.
Domande frequenti
Cos’è un’integrazione API?
È un collegamento governato tra software che scambia dati o comandi tramite un contratto. Comprende autenticazione, trasformazione, errori, osservabilità, sicurezza e responsabilità operative.
Quanto costa integrare due software tramite API?
Dipende da eventi, endpoint, documentazione, autorizzazione, trasformazioni, retry, test e supporto. Un prezzo medio senza questi dati non è confrontabile.
Meglio webhook o polling?
Webhook riduce latenza quando il provider lo supporta in modo affidabile. Polling serve quando webhook manca o per riconciliare eventi persi. La scelta dipende da limiti e criticità.
Come si testa un’integrazione API?
Con contract test, casi di errore, duplicati, timeout, rate limit, credenziali scadute, replay e verifica dello stato finale nei sistemi collegati.
Fonti verificate
Porta un evento e due sistemi
Invia documentazione, evento, fonte autorevole e conseguenza di un errore. Li trasformo in perimetro, rischi e test di accettazione.
Contenuto tecnico pubblicato e verificato il 30/08/2026. Specifiche, provider e requisiti possono cambiare: verifica documentazione applicabile.