Come progettare l’integrazione WooCommerce–ERP con fonti di verità, code ed errori
26 Agosto 2026 · Siti web
Il risultato da ottenere
Il risultato atteso è un flusso in cui WooCommerce ed ERP scambiano ogni oggetto nella direzione prevista, senza duplicazioni silenziose e con modalità di recupero definite. Per ciascun dato occorre sapere quale sistema può modificarlo, quanto ritardo è accettabile e che cosa deve accadere quando la consegna non riesce.
Definire oggetti e ownership dei dati
Prodotti, varianti, categorie, prezzi, stock, clienti, indirizzi, ordini, pagamenti e resi possono avere master differenti. Scrivere da entrambi i sistemi senza regole genera conflitti.
Scegliere pattern sincroni e asincroni
API in tempo reale, webhooks, code e batch rispondono a esigenze diverse. Operazioni critiche per il checkout possono richiedere risposta immediata; cataloghi e report possono tollerare ritardo.
Progettare identificativi e idempotenza
SKU, ID ERP, ID WooCommerce e chiavi esterne devono essere stabili. Ogni messaggio o ordine deve poter essere ripetuto senza creare duplicati.
Gestire errori, retry e dead letter
Timeout, dati invalidi, indisponibilità e conflitti richiedono retry controllati, coda di eccezione, alert e strumenti per correggere. Un webhook fallito non deve sparire.
Proteggere sicurezza e prestazioni
Credenziali, permessi, rate limit, logging e dati personali vanno governati. WooCommerce espone REST API e supporta webhooks; l'implementazione deve testare volumi e limiti reali.
Riconciliare e osservare il sistema
Conteggi, totali, stock, ordini e stati devono essere confrontati periodicamente. Il monitoraggio deve mostrare lag, errori, duplicati e record non sincronizzati.
Matrice operativa
| Dimensione | Dato o oggetto | Decisione | Cautela |
|---|---|---|---|
| Prodotti | ERP/PIM → Woo | Batch/API | Versione |
| Stock | ERP/WMS → Woo | Near real-time | Overselling |
| Prezzi | ERP → Woo | Regole/account | Validità |
| Clienti | CRM/ERP ↔ Woo | Conflitti | Privacy |
| Ordini | Woo → ERP | Coda/idempotenza | Duplica |
| Stati | ERP → Woo | Evento | Riconciliazione |
Sequenza di implementazione
1. Inventariare oggetti, campi e owner.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
2. Definire master e direzione per ogni dato.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
3. Stabilire identificativi e mapping.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
4. Scegliere API, webhook, coda o batch.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
5. Progettare idempotenza, retry ed eccezioni.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
6. Testare volumi, errori e sicurezza.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
7. Creare dashboard e riconciliazione.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
8. Versionare integrazione e cambi.. La fase va chiusa con un'evidenza accessibile, un owner e un criterio di accettazione; eccezioni e dipendenze devono essere registrate.
Come misurare il lavoro
- Lag di sincronizzazione
- Messaggi falliti e ritentati
- Ordini duplicati o mancanti
- Disallineamenti di stock e prezzo
- Record in coda di eccezione
- Tempo di riconciliazione
Lag, retry ed elementi in eccezione acquistano significato quando vengono confrontati con ordini mancanti, duplicati e disallineamenti effettivi. Il report deve separare i problemi transitori già recuperati da quelli che richiedono intervento e mostrare se la riconciliazione riporta i sistemi allo stato atteso.
Scenario applicativo
Stock e prezzi vengono aggiornati con un cron, mentre gli ordini sono inviati direttamente all'ERP. Un timeout porta il plugin a reinviare l'ordine e crea un duplicato.
Il nuovo disegno usa chiavi idempotenti, una coda e conferme di elaborazione. Le eccezioni sono visibili e la riconciliazione confronta ordini e totali.
Criteri di completamento
| Livello | Condizione | Evidenza |
|---|---|---|
| Fondamenta | Perimetro, definizioni e owner approvati | Brief, RACI e fonti |
| Implementazione | Configurazioni, processi o contenuti testati | QA, log o versione |
| Adozione | Le persone previste usano il processo | Dati e osservazione |
| Risultato | Gli indicatori cambiano senza effetti indesiderati | Dashboard e verifica |
| Manutenzione | Esistono trigger e data di revisione | Calendario e backlog |
Errori da evitare
- Permettere scrittura bidirezionale senza regole.
- Usare SKU non univoci.
- Trattare webhooks come consegna garantita.
- Eseguire retry infiniti.
- Registrare dati sensibili nei log.
- Non progettare la riconciliazione.
Progettare il contratto di sincronizzazione
Prima di implementare un connettore conviene descrivere un contratto per ciascun oggetto scambiato. Il contratto specifica campi obbligatori e facoltativi, trattamento dei valori nulli, unità di misura, precisione dei prezzi, fuso orario, valori ammessi per gli stati e identificativi da conservare. Deve inoltre indicare quali metadati accompagnano il messaggio, per esempio chiave esterna, versione del tracciato e istante dell’evento.
- Stabilire se un prodotto incompleto viene rifiutato, pubblicato come bozza o accodato per una correzione.
- Definire come distinguere un prezzo assente da un prezzo pari a zero.
- Chiarire se lo stock rappresenta disponibilità fisica, vendibile o già ridotta dalle riserve.
- Prevedere la traduzione degli stati quando i due sistemi usano tassonomie differenti.
- Gestire i campi aggiunti o rimossi senza interrompere i messaggi ancora conformi alla versione precedente.
Il contratto deve considerare anche la sequenza degli eventi. Un aggiornamento più vecchio non dovrebbe sovrascriverne uno recente solo perché è arrivato dopo; allo stesso modo, la creazione di una variante non può essere elaborata correttamente se il prodotto padre non è disponibile. Timestamp, numeri di versione o controlli sullo stato corrente permettono di riconoscere questi casi e indirizzarli alla gestione prevista.
Provare i guasti prima del rilascio
Il collaudo non dovrebbe limitarsi al percorso senza errori. È utile simulare un timeout dopo la registrazione dell’ordine nell’ERP ma prima della conferma, la consegna ripetuta dello stesso evento, un aggiornamento di stock fuori sequenza, un payload non valido e l’indisponibilità temporanea di uno dei sistemi. Per ogni prova vanno verificati lo stato finale nei due ambienti, i log disponibili e il modo in cui un operatore può riprendere l’elaborazione senza generare nuovi record.
In un caso ipotetico, WooCommerce invia un ordine con una chiave esterna stabile. L’ERP lo salva, ma la risposta si perde. Il tentativo successivo usa la stessa chiave e recupera l’ordine già creato; se il contenuto ricevuto è diverso, il messaggio viene isolato invece di produrre un secondo documento. La riconciliazione confronta poi identificativi, totali e stato, rendendo verificabile l’esito del recupero.
Domande frequenti
REST API o webhook?
Le API leggono o scrivono su richiesta; i webhooks notificano eventi. Spesso vengono combinati con code e riconciliazione.
Serve un middleware?
Quando trasformazioni, volumi, sistemi e gestione errori superano ciò che un plugin può governare in modo trasparente.
Come evitare overselling?
Con fonte stock, frequenza, riserve e gestione degli errori coerenti con il rischio commerciale.
Fonti e riferimenti
- WooCommerce Developer Docs — REST API — https://developer.woocommerce.com/docs/apis/rest-api/
- WooCommerce Developer Docs — Webhooks — https://developer.woocommerce.com/docs/apis/rest-api/v2/webhooks
- WooCommerce Action Scheduler — Processing at scale — https://github.com/woocommerce/action-scheduler/blob/trunk/docs/perf.md
Approfondisci il servizio: E-commerce WooCommerce.