Integrazioni B2B in Magento 2: Profiles, Mappings e controllo della sincronizzazione in B2B Suite

Integrare Magento 2 con ERP, PIM, WMS o CRM significa più che inviare dati a un’API. Occorre identificare l’azienda, collegare gli identificativi, verificare l’esito e gestire messaggi rifiutati. Nel B2B questo determina se l’ordine arriva alla gestione operativa, il cliente viene riconosciuto e il listino concordato raggiunge il canale corretto.

Integrations in Kowal B2B Suite organizza il lavoro in cinque aree: Profiles, Mappings, Sync Jobs, Dead Letter Queue e Sync Errors. Ne spieghiamo funzionamento e utilizzo quotidiano.

La descrizione segue l’implementazione verificata a novembre 2026. Gli esempi sono illustrativi e presuppongono un adattatore installato per sistema e operazione indicati.

Cosa offre Integrations e cosa fa l’adattatore?

Integrations fornisce infrastruttura comune: profili, associazioni di ID, registro delle attività, controllo tentativi, risultati e storico errori. Un adattatore realizza la connessione specifica a ERP, PIM, WMS o CRM e ne conosce API e regole di scambio.

L’adattatore definisce autenticazione, formati, trasformazione dei campi ed esecuzione. Selezionare “ERP” descrive lo scopo del profilo; non installa una connessione pronta con qualsiasi ERP.

Salvare un’attività registra solo lavoro da svolgere. Il modulo di inserimento non avvia un processo periodico in background. Elaborazione e selezione delle attività vanno collegate durante l’implementazione, ad esempio tramite worker, pianificazione o middleware che usi logica e API disponibili.

Cinque schermate, cinque domande precise

Questi elementi descrivono lo stesso processo da prospettive diverse. Il profilo definisce il contesto, le associazioni collegano record, il job rappresenta l’operazione e le ultime viste aiutano a gestire gli errori.

Profiles: configurare l’integrazione per il website corretto

In B2B > Integrations > Profiles crei e modifichi profili. Ciascuno appartiene a un website Magento con B2B attivo. Puoi così separare canali nazionali ed export se utilizzano website distinti.

Website indica qui l’unità organizzativa del canale Magento. Più viste linguistiche nello stesso website non equivalgono a integrazioni indipendenti.

Config JSON non ha campi universali per tutte le integrazioni. L’adattatore interpreta le chiavi. Il modulo convalida JSON, ma non sostituisce una prova di connessione. Per le credenziali è opportuno usare riferimenti a configurazioni sicure secondo i requisiti dell’adattatore.

L’integratore usa un profilo nominato invece di ripetere parametri ERP in script separati. L’operatore vede sistema e direzione dello scambio.

Mappings: collegare identificativi Magento ed esterni

Un’azienda può avere ID 42 in B2B Suite e codice ERP-C-0084 nell’ERP. Una persona riconosce un solo cliente; l’integrazione richiede un legame esplicito per leggere o aggiornare la scheda giusta.

Mappings salva website, tipo di sistema, entità, ID locale, ID esterno e metadati JSON facoltativi. L’interfaccia prevede aziende, clienti, prodotti, categorie, listini, ordini, RFQ e documenti.

I valori sono esempi. L’adattatore stabilisce la rappresentazione dell’ID locale per ogni entità. Le associazioni sono ricercabili tramite ID locale o esterno.

Mappings collega identità di record; non è un editor visuale per trasformare campi. Una regola come “il nome cliente ERP va nel campo company di Magento” appartiene all’adattatore. Salvare un’associazione non recupera né sincronizza dati.

Il contesto comprende website, tipo di sistema ed entità, non un solo profilo. Con più connessioni dello stesso tipo in un website, l’integratore deve pianificare un’identificazione coerente. Nel contesto, il database impone unicità sia dell’ID locale sia di quello esterno.

Sync Jobs: registrare il lavoro e seguire la sincronizzazione

Un Sync Job rappresenta un’operazione, come inviare un ordine all’ERP. In Schedule Sync Job scegli profilo attivo, entità e operazione. Puoi specificare direzione, input JSON, chiave di idempotenza, limite tentativi e data pianificata. Senza modifica vale la direzione del profilo.

L’adattatore deve comprendere entità e nome operazione. export_order può appartenere alla soluzione concordata, ma inserirlo non implementa un’esportazione.

View mostra riepilogo, input, risultato dell’adattatore, log ed errori. Puoi controllare website, profilo, direzione, entità, operazione, tentativi, chiave e tempi di pianificazione, avvio e fine.

Interpreta success secondo il contratto dell’adattatore. Se l’API esterna accetta solo il messaggio per elaborarlo dopo, va stabilito se il risultato conferma ricezione o completamento dell’operazione aziendale.

La data pianificata informa il processo esecutore. Impostarla non sostituisce l’esecuzione né le regole per selezionare attività pronte.

Idempotenza: limitare le attività duplicate

Dopo una disconnessione il middleware può reinviare la stessa operazione. Una chiave di idempotenza riconosce il job esistente. La stessa chiave nello stesso website restituisce quel record invece di crearne un altro.

La chiave deve identificare un’operazione precisa, come esportare una versione dell’ordine. È condivisa nel website: includi contesto riconoscibile di sistema e operazione. Riutilizzare una chiave vecchia non aggiorna l’input del job esistente.

Questo evita registrazioni duplicate. Prevenire effetti doppi nell’ERP, come un secondo documento dopo una risposta incerta, richiede anche gestione nell’adattatore e supporto dell’API esterna.

Dead Letter Queue: attività che richiedono una decisione

Dead Letter Queue mostra job dead. È una vista degli stessi record, non una seconda copia dei messaggi. Isola operazioni non completate entro il limite di tentativi.

Con tre tentativi consentiti, il terzo fallimento dell’adattatore imposta dead. Non significa che il modulo avvii automaticamente tre tentativi consecutivi. Esecuzioni successive e intervalli dipendono dal processo esecutore e dalla gestione dei tentativi implementati.

L’operatore apre il job, analizza e corregge la causa, ad esempio un’associazione cliente mancante o la connessione. Può poi usare Retry Job.

Il tentativo è disponibile per failed e dead. Non crea un nuovo job e non azzera lo storico dei tentativi. Imposta retry, pianifica il momento attuale e cancella precedenti orari di avvio e fine. Se il limite è esaurito, lo aumenta per consentire un altro tentativo. Solo l’elaborazione successiva esegue l’adattatore.

Sync Errors: storico degli errori con contesto

Sync Errors mostra errori dell’adattatore: codice, messaggio, ora e possibilità di riprovare. Li collega al contesto attuale di job, profilo e website, distinguendo un problema del cliente da un guasto generale.

I dettagli del job includono errori e log tecnici, ad esempio avvio, conclusione e pianificazione dei tentativi. I dati d’errore conservano anche una traccia tecnica utile all’integratore.

Un job può avere più errori da tentativi successivi. Il numero di errori non corrisponde alle operazioni ancora aperte. Un job poi riuscito può mantenere gli errori precedenti.

Retryable dipende dai tentativi rimasti al momento dell’errore. Non riconosce automaticamente cause temporanee. Un ID errato non si corregge riprovando, anche se restano tentativi.

La distinzione principale: Sync Errors serve all’analisi delle cause; Dead Letter Queue elenca job con tentativi esauriti.

Scenario 1: collegare l’azienda B2B al cliente ERP

Alfa ha un account Magento e una scheda ERP esistente. Il team vuole evitare di duplicare il cliente.

1. L’integratore prepara adattatore ERP e profilo del website corretto.
2. Mappings collega l’azienda 42 a ERP-C-0084.
3. Il job dell’adattatore usa l’associazione per il record esistente.
4. L’operatore controlla risultato e identificativi restituiti in Sync Jobs.

L’identità del cliente resta coerente. Campi aggiornati e sistema che ne è fonte appartengono all’ambito concordato.

Scenario 2: inviare l’ordine B2B dopo un’interruzione

Il cliente ordina e il meccanismo crea un job di esportazione. L’ERP è temporaneamente irraggiungibile. L’adattatore fallisce, viene registrato l’errore e il job diventa failed o, esauriti i tentativi, dead.

Dopo il ripristino l’operatore verifica l’esito precedente nell’ERP e pianifica Retry dello stesso job. L’adattatore deve riconoscere documenti esistenti per evitare duplicati se la richiesta era stata accettata nonostante la risposta persa.

Il risultato riuscito può contenere l’ID del documento ERP e l’adattatore può salvare un’associazione. Contenuto e momento dipendono dall’implementazione.

Scenario 3: aggiornare il listino del canale B2B corretto

L’ERP è fonte delle condizioni commerciali. Il canale all’ingrosso ha un profilo di importazione e un’associazione dal listino 7 a ERP-PRICELIST-DEALERS.

L’adattatore legge l’ERP, verifica SKU, valuta e scaglioni e salva secondo Pricing. Sync Job segue l’operazione; il risultato può riepilogare le voci elaborate. In caso di problemi sono disponibili contesto e messaggio.

Integrations gestisce il flusso; Pricing sceglie il prezzo. Vedi listini B2B e Price List in Magento 2. Convalida, scritture parziali e aggiornamenti dell’indice devono essere definiti nell’adattatore.

Scenario 4: un errore ricorrente richiede dati corretti

Il sistema di magazzino rifiuta un’operazione perché non riconosce il prodotto. Riprovare non cambia nulla. Il job esaurisce i tentativi e appare in Dead Letter Queue.

L’operatore apre View Job, legge il messaggio e verifica gli ID. Se manca un collegamento corregge Mappings. Risolta la causa, seleziona Retry Job e controlla l’esito successivo.

Questo spiega la necessità di associazioni e storico errori. La coda consente di riprendere l’operazione; la diagnosi indica cosa correggere prima del nuovo tentativo.

Implementare Integrations passo dopo passo

1. Scegli il primo processo. Parti dall’esportazione ordini anziché collegare subito tutte le aree.
2. Stabilisci le fonti. Decidi chi gestisce cliente, listino o stato e come risolvere i conflitti.
3. Prepara adattatore ed esecutore. Definisci operazioni, formati, autenticazione, esecuzione e tentativi.
4. Configura Profiles e Mappings. Verifica website, direzione e ID con casi reali.
5. Prova successi ed errori. Includi API indisponibile, dati errati, richieste ripetute e tentativi esauriti.
6. Verifica il risultato aziendale. Conferma il record corretto a destinazione oltre allo stato.
7. Assegna le responsabilità. Stabilisci chi monitora Sync Errors e Dead Letter Queue e corregge dati o connessioni.

Valuti così operazioni corrette e tempi di risoluzione, non solo l’esistenza di una connessione API.

Domande frequenti su Integrations in B2B Suite

Un profilo ERP offre una connessione pronta a qualsiasi ERP?

No. Conserva contesto e configurazione. Un adattatore per API e processi concordati realizza la comunicazione.

Mappings trasforma i campi di importazione?

Collega identificativi locali ed esterni. Trasformazione dei campi e formattazione competono all’adattatore.

Retry invia subito i dati?

No. Riprogramma il job esistente. Invio o recupero avvengono alla successiva esecuzione del processo collegato.

Qual è la differenza tra Dead Letter Queue e Sync Errors?

La prima mostra job dead, il secondo errori con contesto. Errori di operazioni poi riuscite possono rimanere nello storico.

Il modulo riprova automaticamente ogni pochi minuti?

Salva tempi, stati e contatori e offre il tentativo successivo. Calendario, intervalli e selezione automatica vanno configurati nella soluzione esecutiva.

Si può gestire l’integrazione via API?

L’API B2B Suite gestisce profili e associazioni, pubblicazione, elaborazione e tentativi dei job, più lettura di job, log ed errori. Richiede permessi di integrazione e contesto website dove previsto.

Integrazione B2B sotto il controllo del team

Profiles organizza configurazione, Mappings identità, Sync Jobs avanzamento e Dead Letter Queue e Sync Errors fallimenti. Insieme formano una base estendibile per integrare Magento 2 tramite adattatori aziendali.

Scopri Kowal B2B Suite per Magento 2 Open Source oppure descrivici il processo da collegare a ERP, PIM, WMS o CRM. Bastano sistema, direzione e un’operazione oggi manuale.

Leggi anche: ridurre la gestione manuale delle vendite B2B e il costo della gestione manuale degli ordini B2B.