Ogni SaaS PSA espone REST/JSON per API moderne, supporta SOAP/XML per legacy, webhook outbound per eventi real-time, LDAP/SAML/OAuth2 per SSO, SFTP per scambio file schedulato, SMTP/IMAP per email, FatturaPA/SdI per fatturazione elettronica, connettori specifici per AS/400 e Oracle dove serve. I pattern di sincronizzazione sono 3 (webhook near-real-time, polling periodico, batch notturno), scelti in base al caso d'uso. Resilience: retry esponenziale, circuit breaker, dead-letter queue, monitoring dedicato delle integrazioni.
01Filosofia: niente walled garden
Dopo quarant'anni di mestiere abbiamo visto passare l'EDI, CORBA, SOAP, REST, GraphQL, gRPC, ora gli MCP server per gli LLM. Un insegnamento costante: i sistemi che parlano solo con sé stessi muoiono prima. Per questo ogni SaaS che scriviamo nasce con l'integrazione come requisito, non come modulo opzionale.
Concretamente: il database non è mai il punto di integrazione (accoppiamento troppo stretto, rischio sicurezza, rottura a ogni upgrade schema). Il punto di integrazione è sempre un layer applicativo — API versionate, contratti chiari, autenticazione esplicita. Se un altro software vuole leggere o scrivere, passa di lì. Senza eccezioni, neanche per noi stessi.
Niente "connector marketplace" generici acquistati da terzi. Ogni integrazione è curata, testata sul dominio specifico, mantenuta nel tempo. Costa di più da dire, costa meno da gestire.
02Protocolli supportati out-of-the-box
La lista è lunga perché i sistemi che i nostri SaaS devono raggiungere sono eterogenei — dall'ERP acquistato tre anni fa al gestionale verticale scritto in RPG sull'AS/400 vent'anni fa.
- REST/JSON: standard de-facto per le API moderne. Autenticazione via Bearer token (JWT) o API key, versioning in URL, paginazione cursor-based, filtering/ordering coerente.
- SOAP/XML: dove serve. WSDL pubblicato, supporto a WS-Security se richiesto dal sistema controparte. Non è bello, ma per integrare mezza Italia legacy è necessario.
- GraphQL: opzionale, quando il consumatore ha bisogno di shape dei dati molto variabili (tipico di frontend esterni o BI).
- gRPC: per sistemi ad alta performance con throughput elevato — tipicamente integrazioni interne tra servizi PSA, o verso sistemi del cliente che lo richiedono esplicitamente.
- File-based: CSV, XML, JSON schedulati via SFTP/FTPS. Il 40% delle integrazioni reali in PMI italiane passa ancora di qui. Non lo neghiamo, lo gestiamo bene.
- Message queue: RabbitMQ o Kafka per integrazioni event-driven con volumi non banali.
03SSO e identity
Gli utenti del cliente non devono avere una password in più per ogni nostro SaaS. È una richiesta ricorrente, e la risolviamo sempre allo stesso modo: federazione sull'identity provider aziendale esistente.
- LDAP / Active Directory via LDAPS (TLS obbligatorio): il caso più frequente nelle PMI italiane. Gli utenti sono già su AD, non ha senso replicarli. Mapping gruppi AD → ruoli applicativi configurato caso per caso.
- SAML 2.0: per clienti con IdP enterprise (ADFS, Keycloak, Okta, Azure AD/Entra ID). Metadati XML scambiati una volta, assertion firmate, attributi mappati sul profilo utente.
- OAuth2 / OpenID Connect: per scenari moderni, flussi Authorization Code con PKCE per app web, Client Credentials per integrazioni server-to-server.
- Kerberos: quando il cliente lo richiede esplicitamente per single sign-on desktop integrato. Raro, ma lo facciamo.
Tutti i SaaS PSA hanno 2FA obbligatoria nativa quando l'SSO non copre questo requisito — allineamento normativo, non optional.
04Pattern di sincronizzazione
Ogni integrazione cade in uno di tre pattern. La scelta non è stilistica: dipende dal caso d'uso, dalla latenza accettabile, e soprattutto da cosa il sistema controparte è in grado di sostenere.
| Pattern | Latenza | Complessità | Affidabilità |
|---|---|---|---|
| Webhook outbound | Near-real-time (secondi) | Alta: serve endpoint HTTPS sul cliente, retry, idempotency | Eventuale (DLQ obbligatoria) |
| Polling periodico | Minuti (configurabile) | Media: lato consumer, stateful su cursor/timestamp | Alta: idempotente per design |
| Batch notturno | Ore (ciclo giornaliero) | Bassa: file SFTP, processo ETL, report | Molto alta: retry semplice, operabile |
La regola pratica: non usare webhook se puoi usare polling, non usare polling se puoi usare batch. La latenza è un requisito, non un valore. Un'anagrafica clienti che cambia due volte al mese non ha bisogno di webhook — serve un job notturno robusto.
05Integrazioni legacy
La voce più interessante, perché il mondo reale italiano è pieno di sistemi che il marketing preferisce non vedere ma che i bilanci confermano.
- AS/400 (IBM i): accesso in lettura via ODBC/JDBC ai file fisici e logici, oppure tramite stored procedure esposte come servizi. Per scrittura preferiamo programmi RPG/CL dedicati esposti come API — meno rischio di rompere la logica applicativa del gestionale.
- Oracle / SQL Server legacy: DBLink dove giustificato, più spesso view dedicate in sola lettura con utenti separati. Mai query ad-hoc sul database di produzione di un ERP.
- File CSV/XML schedulati: pattern dominante con gestionali che non hanno API. SFTP con chiavi, file con nomenclatura deterministica, archivio dei trasferiti, alert su assenza file.
- Mail-to-action: un indirizzo IMAP dedicato che ingerisce PEC o mail strutturate e genera eventi applicativi. Utile per SdI (ricezione fatture passive), per ticket generati da mail, per integrazione con sistemi che escono solo via email.
06Resilienza
Un'integrazione vive nel tempo, non viene installata e basta. Per questo ogni pipeline ha lo stesso kit di sopravvivenza.
- Retry esponenziale con jitter: default 5 tentativi, backoff 2s → 4s → 8s → 16s → 32s. Sui 5xx e timeout, mai sui 4xx (errore di business, non di rete).
- Circuit breaker: se il sistema controparte è giù, smettiamo di martellarlo dopo N fallimenti consecutivi. Riapertura graduale con half-open.
- Dead-letter queue: i messaggi che falliscono definitivamente non si perdono, finiscono in coda di rianalisi con payload originale, stack trace, contesto. Visibili in dashboard, riprocessabili manualmente.
- Idempotency key: ogni richiesta è idempotente per chiave — se il retry arriva dopo che l'operazione è già andata a buon fine, non raddoppia niente.
- Monitoring dedicato: Prometheus + Grafana con metriche per pipeline (throughput, error rate, latency p95/p99), alerting su Slack/email ai nostri reperibili prima che il cliente se ne accorga.
- Audit log: ogni evento di integrazione è tracciato, consultabile dal backend di governance del cliente con 2FA.
07Casi concreti
Per dare spessore ai pattern sopra, quattro integrazioni tipiche che abbiamo in esercizio.
ERP → SaaS, sync anagrafiche. Clienti, fornitori, articoli risiedono sull'ERP. Pattern: polling ogni 15 minuti sul delta (campo last_modified o equivalente), upsert lato SaaS con chiave naturale dell'ERP. Niente duplicazione di verità: se c'è conflitto, vince sempre l'ERP.
AD → autenticazione trasparente. Pattern: LDAPS con bind service account, ricerca utente, mapping gruppo AD → ruolo applicativo. L'utente digita email aziendale e password AD una volta, poi sessione gestita via cookie HTTPOnly / JWT refresh.
SdI → fatture passive. Ricezione fatture elettroniche XML firmate via canale SDI (diretto o via intermediario), validazione struttura, mappatura campi su modello interno, notifica al SaaS del cliente via webhook. FatturaPA gestita nativamente, no servizi terzi.
CRM → ticketing. Cliente apre ticket dal CRM (Salesforce o similare), webhook outbound verso il nostro SaaS di ticketing, lavorazione con stato sincronizzato indietro via API REST. Campi custom mappati in configurazione, non in codice.
08Cosa non facciamo
Onestà a inizio progetto risparmia mesi di rinegoziazione a metà.
- Non offriamo "connector marketplace" generici tipo Zapier/Make per i nostri SaaS. Sono utili per automazioni tra 500 servizi cloud americani, inutili per integrare un gestionale verticale italiano. Preferiamo integrazioni curate per dominio specifico.
- Non integriamo direttamente sul database di produzione di un sistema terzo senza una view dedicata o un'API esposta — rischio rottura a ogni patch del vendor, e responsabilità poco chiare in caso di problemi.
- Non promettiamo integrazione "bidirezionale magica" dove due sistemi scrivono lo stesso dato. Serve sempre stabilire chi è la source of truth, punto. Il resto è consistency eventuale.
- Non usiamo integration platform proprietarie (MuleSoft, Boomi) per progetti PMI — costano più del SaaS che devono integrare. Codice dedicato, testato, mantenuto da noi, costa meno in TCO triennale.