Integrare Adobe Commerce: API, GraphQL e cosa ho imparato quest’anno

Nel corso di quest’anno ho passato più tempo a discutere di integrazioni che di temi, di catalogo o di checkout messi insieme. È il segno di dove sta davvero la difficoltà di un progetto Adobe Commerce oggi: non nella piattaforma in sé, ma in tutto quello che le gira attorno. ERP, PIM, CRM, tool di marketing, corrieri e magazzino. Un negozio isolato non esiste più, e la qualità di un progetto la misuro sempre più spesso da come parla con il resto dell’azienda.

Voglio mettere in fila cosa ho imparato nel 2021, senza girarci intorno: le integrazioni che contano, quando usare REST e quando GraphQL, perché le code sono la cosa che sottovaluto di meno, e gli errori che ho visto ripetersi da un progetto all’altro.

Le integrazioni che contano davvero

Quando qualcuno mi chiede “quante integrazioni servono”, la mia risposta è che ne contano poche, ma pesano tutte. Le cinque che vedo tornare in quasi ogni progetto mid-market sono:

• ERP: è il cuore. Anagrafica prodotti, prezzi, giacenze, ordini che tornano indietro come documenti fiscali. Se sbagli questa, sbagli tutto il resto.
• PIM: quando il catalogo supera qualche migliaio di SKU con attributi ricchi, il PIM diventa la fonte di verità del prodotto e Adobe Commerce ne diventa un consumatore.
• CRM: clienti, segmenti, storico. Serve soprattutto in B2B, dove il cliente non è un’email ma un’azienda con listini e condizioni sue.
• Marketing: email automation, loyalty, feed pubblicitari. Qui il flusso è quasi sempre in uscita da Adobe Commerce.
• Logistica: WMS e corrieri. Spedizioni, tracking, resi. È il pezzo che il cliente finale vede, e quindi quello che perdona meno.

La domanda giusta non è “come le collego”, ma “chi è il master di ogni dato”. Secondo me è la decisione architetturale più importante di tutto il progetto, e va presa prima di scrivere una riga di codice. Chi possiede il prezzo? Chi possiede lo stock? Chi possiede l’anagrafica cliente? Finché queste risposte restano ambigue, ogni integrazione diventa un campo di battaglia.

REST o GraphQL: non è una gara

Su questo ho cambiato idea rispetto a qualche anno fa. Oggi la vedo così: sono strumenti per lavori diversi, non due versioni della stessa cosa dove una è “più moderna”.

Uso REST (e le API async e bulk introdotte da Adobe Commerce) per le integrazioni server-to-server con i sistemi gestionali. Quando devo importare cinquantamila prodotti dall’ERP o riversare migliaia di ordini, la Bulk API con RabbitMQ dietro è la strada giusta: accodi, rispondi subito, processi in background. REST resta anche il posto dove vivono le operazioni di scrittura pesanti e la logica di catalogo.

Uso GraphQL per il front-end, in particolare negli scenari headless e PWA. Il valore vero, per me, è chiedere esattamente i campi che servono in una sola chiamata, senza l’over-fetching che con REST ti costringe a orchestrare tre o quattro endpoint per popolare una pagina prodotto. In un progetto headless di quest’anno abbiamo ridotto in modo netto il numero di round-trip verso il server proprio spostando la lettura del catalogo su GraphQL.

Detto questo, GraphQL non è gratis. La copertura delle funzionalità non è totale come su REST, il caching HTTP tradizionale non si applica allo stesso modo e una query mal scritta può diventare pesante senza che te ne accorga. La mia regola pratica: GraphQL per leggere lato storefront, REST e API async per scrivere e per integrare i sistemi. Chi prova a fare tutto con uno solo dei due, prima o poi si pente.

Le code: la parte che salva i progetti

Se dovessi indicare una sola cosa che separa un’integrazione solida da una fragile, direi la gestione asincrona. Adobe Commerce ha un message queue framework che può girare su RabbitMQ o sul database, e nei progetti seri RabbitMQ non è un’opzione, è la base.

Il principio è semplice: le integrazioni non devono essere sincrone. Quando l’ERP invia un aggiornamento prezzi, non deve aspettare che Adobe Commerce finisca di elaborarlo. Mette il messaggio in coda e va avanti. Il consumer processa con i suoi tempi, e se qualcosa va storto il messaggio non si perde: si ritenta, oppure finisce in una dead letter queue dove qualcuno lo guarda. Questo disaccoppiamento è ciò che permette a un picco di traffico o a un import massiccio di non trascinarsi dietro tutto il resto.

Gli errori che vedo qui sono quasi sempre gli stessi: consumer lasciati con la configurazione di default che non reggono il volume reale, nessun monitoraggio sulla lunghezza delle code (te ne accorgi quando sono già esplose), e nessuna strategia per i messaggi che falliscono. Una coda senza monitoraggio è una bomba a orologeria, e l’ho visto succedere abbastanza da non fidarmi mai delle impostazioni iniziali.

Non trasformare il core in un mostro

Arrivo al punto che mi sta più a cuore. Il modo più veloce per rovinare un progetto Adobe Commerce è mettere la logica di integrazione dentro il core, magari con qualche plugin che intercetta il salvataggio di un ordine e chiama in diretta l’ERP. Funziona in demo. Poi il gestionale ha tre secondi di latenza, e il tuo checkout eredita quei tre secondi. Oppure l’ERP è in manutenzione, e i clienti non riescono più a comprare.

I pattern che difendo su ogni progetto sono pochi e chiari:

• Anti-corruption layer: un modulo di integrazione separato che traduce i modelli esterni nei modelli di Adobe Commerce. Il core non deve sapere com’è fatto il tracciato dell’ERP.
• Middleware quando ha senso: in scenari con molti sistemi, un livello di integrazione dedicato (un iPaaS o un servizio custom) evita di trasformare Adobe Commerce nell’hub che parla con tutti. La piattaforma di commerce deve fare commerce, non fare da centralino.
• Asincrono per default: code in mezzo, mai chiamate sincrone nel flusso d’acquisto.
• Idempotenza: ogni messaggio deve poter essere processato due volte senza danni, perché prima o poi verrà processato due volte.

La mia convinzione, dopo anni su Magento e Adobe Commerce, è che un core pulito valga più di qualsiasi integrazione elegante. Il codice di integrazione va isolato, versionato e testato a parte, così un aggiornamento di piattaforma non ti costringe a rimettere mano a tutto.

Gli errori d’integrazione più frequenti del 2021

Per chiudere, la lista che avrei voluto avere all’inizio dell’anno:

• Nessun master dato definito. Due sistemi che si contendono il prezzo o lo stock producono conflitti infiniti.
• Integrazioni sincrone nel checkout. La disponibilità del tuo negozio finisce ostaggio di quella dei gestionali.
• Logica dentro il core. Ogni upgrade diventa un incubo e ogni bug è difficile da isolare.
• Code senza monitoraggio né retry. I messaggi si perdono in silenzio e te ne accorgi dai clienti.
• Tutto su un solo protocollo. GraphQL usato per import massivi, o REST usato per popolare ogni pagina lato client: entrambi si pagano in performance.

Se dovessi riassumere l’anno in una frase: le integrazioni non si progettano pensando al giorno del go-live, ma al giorno in cui uno dei sistemi collegati si comporterà male. Perché quel giorno arriva sempre, e un’architettura fatta bene è quella che quel giorno lo assorbe senza fermare le vendite.

Mini-FAQ

Meglio REST o GraphQL per integrare Adobe Commerce?
Dipende dal lavoro. GraphQL è ideale per la lettura lato storefront, specie in headless, perché chiedi solo i campi che servono. REST e le API async/bulk sono la scelta per scrivere e per integrare i sistemi gestionali con volumi elevati.

Serve davvero RabbitMQ?
Per progetti mid-market con integrazioni reali, sì. Il message queue framework di Adobe Commerce su RabbitMQ permette di rendere asincrone le integrazioni, gestire retry e picchi senza rallentare il front-end.

Come evito che le integrazioni appesantiscano la piattaforma?
Isolando la logica in un modulo di integrazione separato (anti-corruption layer), usando code al posto delle chiamate sincrone e, quando i sistemi sono molti, delegando l’orchestrazione a un middleware dedicato invece di caricarla sul core.

Qual è l’errore di integrazione più comune?
Non aver definito chi è il master di ogni dato (prezzo, stock, anagrafica). Senza questa decisione presa a monte, ogni integrazione genera conflitti.

Fabio Canovi si occupa di e-commerce enterprise da oltre dieci anni, con un focus su Magento e Adobe Commerce. È tra i primi professionisti in Italia ad aver ottenuto la certificazione Adobe Commerce. Su questo blog racconta, senza filtri commerciali, cosa succede davvero dietro i progetti e cosa significa per chi vende online.