Quante ore alla settimana passa qualcuno del tuo team a copiare dati da un gestionale a un altro? Se la risposta è "più di zero", hai già un problema di integrazione — e probabilmente lo stai risolvendo nel modo sbagliato. Lo sviluppo di API custom per connettere software aziendali è una delle richieste più frequenti che riceviamo da PMI che hanno accumulato nel tempo tre, quattro, cinque strumenti diversi che non si parlano. In questa guida vediamo come funziona il processo, quando ha senso costruire un'integrazione custom rispetto a usare connettori preconfezionati, e quali errori architetturali è meglio evitare fin dall'inizio.
Zapier, Make, e i connettori nativi dei SaaS risolvono il 70% dei problemi di integrazione standard. Se devi spostare un lead da un form a un CRM, usali senza pensarci due volte.
Il problema emerge quando entri nel restante 30%: logiche di business proprietarie, gestionali legacy senza API native, flussi multi-step con condizioni complesse, volumi di dati che i piani standard non reggono, o requisiti di sicurezza che impediscono di mandare dati sensibili a servizi terzi.
In questi casi, un'API custom non è un lusso — è l'unica soluzione che non si rompe al primo aggiornamento del fornitore o al primo picco di traffico.
Gestionale legacy senza API. Molti ERP installati in aziende italiane hanno 10-15 anni. Non hanno endpoint REST. Hanno al massimo un database SQL accessibile in rete locale e qualche export CSV. Un wrapper API scritto ad hoc può esporre quei dati in modo strutturato senza toccare il sistema esistente.
Logiche di trasformazione dati complesse. Quando il dato che esce da sistema A non corrisponde al formato atteso da sistema B — codici prodotto diversi, valute, unità di misura, strutture gerarchiche — nessun connettore preconfezionato gestisce quella trasformazione senza configurazioni fragili. Un middleware custom la codifica una volta sola, in modo testabile.
Requisiti di sicurezza e residenza dati. Alcune aziende non possono mandare dati di fatturazione o dati personali a server di terze parti. Un'API self-hosted risolve il problema alla radice.
Prima di scrivere una riga di codice, le decisioni architetturali determinano se l'integrazione reggerà nel tempo o diventerà debito tecnico.
Per la quasi totalità delle integrazioni B2B tra software aziendali, REST è la scelta giusta. È comprensibile, documentabile, e qualunque sviluppatore che subentra in futuro sa come lavorarci.
GraphQL conviene quando hai client multipli con esigenze di dato eterogenee — ad esempio un'app mobile che legge solo un sottoinsieme dei campi che legge il dashboard web. Per un'integrazione gestionale-e-commerce, aggiunge complessità senza benefici concreti.
gRPC è rilevante in contesti di microservizi ad alto throughput. Per connettere un ERP a un WMS, è overkill.
Una chiamata API sincrona risponde subito: il sistema A chiede, il sistema B risponde, si va avanti. Funziona bene per operazioni veloci — verificare disponibilità a magazzino, leggere l'anagrafica di un cliente.
Diventa un problema quando il sistema B è lento, non disponibile, o quando l'operazione richiede elaborazione pesante. In questi casi, un pattern asincrono con coda messaggi (RabbitMQ, Redis, o anche una semplice tabella di job) è più robusto: il sistema A deposita la richiesta, il sistema B la processa quando può, il risultato viene notificato.
La scelta sbagliata qui genera timeout a cascata e dati inconsistenti in produzione.
L'errore più comune nelle integrazioni custom è accoppiare direttamente i sistemi. Il codice chiama l'API del gestionale, trasforma i dati, li manda all'e-commerce. Funziona — finché il gestionale non aggiorna la propria API.
L'adapter pattern risolve questo: scrivi un'interfaccia interna stabile e un adapter specifico per ogni sistema esterno. Quando il fornitore cambia qualcosa, aggiorni solo l'adapter, senza toccare la logica di business. Su integrazioni che vivono 3-5 anni, questa scelta si ripaga ampiamente.
Il processo ha fasi abbastanza prevedibili, indipendentemente dalla complessità.
Prima di tutto: quali dati devono muoversi, in quale direzione, con quale frequenza, e con quali trasformazioni. Questo lavoro si fa con chi conosce i processi aziendali, non solo con i tecnici. Un foglio di mappatura con sorgente, destinazione, frequenza e regole di trasformazione vale più di ore di analisi del codice.
Quali API espone già il gestionale? Sono documentate? C'è autenticazione OAuth2 o API key? Ci sono rate limit? Il database è accessibile direttamente? Queste risposte determinano l'approccio tecnico e, in misura significativa, i tempi.
Se stai costruendo un middleware, definisci i contratti API prima di scrivere codice. OpenAPI (Swagger) è lo standard: permette di generare documentazione, mock server per i test, e validazione automatica dei payload. Un contratto scritto prima evita ambiguità costose a metà sviluppo.
Lo sviluppo in sé è la parte più breve quando la fase 1-3 è fatta bene. I test di integrazione — che simulano i sistemi reali con dati realistici — sono la parte che non va mai tagliata per rispettare le scadenze. I bug di integrazione che emergono in produzione costano ordini di grandezza di più di quelli trovati in test.
Un'API in produzione ha bisogno di logging strutturato, alerting su errori e latenza anomala, e una strategia di versioning. Senza questi elementi, il primo problema in produzione diventa un'emergenza invece di un ticket ordinario.
| Tipo di integrazione | Complessità tipica | Tempo indicativo | Tecnologie comuni |
|---|---|---|---|
| Integrazione punto-a-punto (2 sistemi) | Bassa-media | 2-6 settimane | Laravel, REST, cron job |
| Middleware multi-sistema (3+ sistemi) | Media-alta | 2-4 mesi | Laravel, queue, Redis, OpenAPI |
| Wrapper API su gestionale legacy | Media (dipende dal legacy) | 3-8 settimane | Laravel, accesso DB diretto, SFTP |
| Integrazione B2B con partner esterno | Media-alta | 4-10 settimane | REST, OAuth2, webhook, OpenAPI |
I tempi nella tabella assumono che la fase di analisi sia completata prima dell'avvio dello sviluppo e che i sistemi sorgente/destinazione abbiano documentazione accessibile. Ogni incognita sul legacy allunga i tempi.
Nessun versioning degli endpoint. Se esponi /api/ordini e poi devi cambiare la struttura della risposta, tutti i client che la consumano si rompono. /api/v1/ordini e /api/v2/ordini ti danno il tempo di migrare senza interruzioni.
Autenticazione trattata come optional. Un'API interna "tanto non è pubblica" che gira su rete aziendale senza autenticazione è un rischio concreto. API key con scadenza, OAuth2, o almeno mutual TLS — scegli in base alla sensibilità dei dati.
Nessuna gestione degli errori idempotente. Se una chiamata fallisce a metà — il dato è stato scritto su sistema A ma non su sistema B — cosa succede al retry? Un'integrazione robusta gestisce questi casi esplicitamente, con ID di transazione e controlli di duplicazione.
Logging insufficiente. "L'integrazione non funziona" è un'informazione inutile senza log strutturati che dicono quale payload è stato ricevuto, quale trasformazione è stata applicata, e quale risposta ha restituito il sistema downstream.
Se stai valutando un'integrazione tra sistemi e non sai da dove partire con l'analisi, in Press Start affrontiamo spesso questa fase come primo passo autonomo — prima di qualsiasi sviluppo. Può aiutarti a capire la complessità reale e scegliere l'approccio giusto.
Le piattaforme iPaaS (Integration Platform as a Service) come MuleSoft, Boomi, o Workato offrono connettori prebuilt e interfacce low-code. Per integrazioni standard tra sistemi noti, riducono i tempi di sviluppo in modo significativo.
Il middleware custom conviene quando:
L'iPaaS conviene quando:
Non è una scelta ideologica — è una valutazione di costi, rischi e requisiti specifici.
Senza entrare in un trattato sulla sicurezza, questi sono i punti che ogni API custom aziendale deve coprire prima di andare in produzione:
Autenticazione. OAuth2 con client credentials per comunicazioni machine-to-machine. API key con rotazione programmata come alternativa più semplice per integrazioni interne.
Autorizzazione granulare. Il sistema A deve poter leggere gli ordini ma non modificare l'anagrafica clienti. I permessi si definiscono per scope, non per sistema.
Rate limiting. Protegge da picchi accidentali e da abusi. Anche su API interne — un bug in un cron job può generare migliaia di chiamate al minuto.
HTTPS ovunque. Anche su reti private. Il certificato TLS non è un optional.
Input validation. Ogni payload ricevuto va validato prima di essere processato. SQL injection e injection di vario tipo passano spesso da endpoint API non validati.
Q: Quanto tempo richiede sviluppare un'API custom per un gestionale?
A: Dipende dalla complessità. Un'integrazione punto-a-punto tra due sistemi richiede in genere 2-6 settimane. Un middleware che coordina più sistemi può richiedere 2-4 mesi, inclusi test e collaudo in produzione. La variabile più grande è la qualità della documentazione dei sistemi da integrare.
Q: REST API o GraphQL: quale scegliere per integrare software aziendali?
A: REST è la scelta più solida nella maggior parte dei casi aziendali: documentazione abbondante, tooling maturo, facile da mantenere nel tempo. GraphQL conviene quando hai molti client con esigenze di dato diverse — ad esempio un'app mobile e un dashboard web che interrogano gli stessi endpoint con payload differenti.
Q: È possibile integrare un gestionale legacy che non ha API native?
A: Sì, ma richiede uno strato intermedio. Le tecniche più comuni sono: accesso diretto al database (se disponibile e documentato), file exchange strutturato via CSV o XML su SFTP, o un wrapper API scritto ad hoc che legge dai report del gestionale. Ognuna ha trade-off diversi su affidabilità e manutenzione futura.
Q: Cosa succede se il fornitore del gestionale aggiorna la propria API?
A: Dipende da come hai costruito il layer di integrazione. Con un adapter pattern aggiorni solo l'adapter senza toccare la logica di business. Se hai accoppiato direttamente i sistemi, ogni aggiornamento del fornitore può rompere l'integrazione. È uno dei motivi per cui l'architettura conta più del codice in sé.
Q: Un middleware custom ha senso per una PMI con budget limitato?
A: Ha senso quando il costo del lavoro manuale di sincronizzazione dati supera il costo di sviluppo nel giro di 12-18 mesi. Se stai copiando dati tra sistemi ogni giorno, o se un errore di sincronizzazione ti costa ordini persi, il calcolo spesso torna a favore dello sviluppo custom.
Q: Come si gestisce il versioning di un'API custom nel tempo?
A: La convenzione più diffusa è il versioning nell'URL (/api/v1/, /api/v2/). Quando introduci breaking changes, rilasci una nuova versione mantenendo la precedente attiva per un periodo di transizione. I client hanno il tempo di migrare senza interruzioni di servizio.
Se stai valutando come connettere i tuoi sistemi aziendali e non hai ancora chiaro quale approccio sia più adatto alla tua situazione, in Press Start possiamo aiutarti a fare un'analisi tecnica del contesto prima di qualsiasi decisione — scrivici
