Procedura di messa in produzione

Documento generico. Si applica a qualsiasi installazione in cui Shopify venga popolato dalla migrazione di un negozio esistente (PrestaShop, WooCommerce, Magento…) mentre Dolibarr contiene già lo storico commerciale corrispondente.

1. Il rischio che questa procedura elimina

Quando i vostri ordini storici vengono trasferiti in Shopify, ricevono identificativi Shopify nuovi, e le loro date di creazione e di modifica sono quelle del giorno della migrazione: Shopify consente di retrodatare la data di elaborazione, mai queste due.

Doli2Shop riconosce un ordine già importato dal suo identificativo Shopify. Un ordine presente in Dolibarr con un'altra origine non porta alcun identificativo Shopify: il modulo non può sapere che si tratta della stessa vendita. Senza precauzioni, viene importato una seconda volta, con la data di oggi, nella vostra contabilità.

Tre percorsi possono importare un ordine, e sono indipendenti fra loro:

2. Prima della migrazione — le impostazioni

• Verso della sincronizzazione delle giacenze. DOLI2SHOP_SYNC_STOCKS_DIRECTION deve valere dolibarr_to_shopify se Dolibarr è il vostro riferimento per le giacenze. Il valore predefinito è both: in tal caso un webhook di inventario Shopify scrive movimenti di magazzino anche in Dolibarr.
• Ordini non pagati. Per impostazione predefinita vengono importati solo gli ordini con stato finanziario pagato. Se devono entrare anche gli ordini in attesa di pagamento (pagamento dilazionato B2B, bonifico), attivate DOLI2SHOP_SYNC_NON_PAID_ORDERS.
• Riferimenti prodotto. Gli SKU delle varianti Shopify devono coincidere esattamente con i riferimenti Dolibarr: è questa corrispondenza a evitare la creazione di prodotti e varianti duplicati.
• Indirizzi e-mail dei soggetti. Un cliente esistente viene abbinato tramite l'e-mail presente sulla scheda dell'azienda, non sui suoi contatti, e all'interno della stessa entità. Un'e-mail che risieda solo su un contatto, o che differisca da quella di Shopify, produrrà un'azienda duplicata. Allineatele prima del passaggio: è un lavoro sui dati, non di configurazione.

3. Durante la migrazione — ciò che deve restare spento

Finché la migrazione non è conclusa e verificata, i tre percorsi di importazione devono essere inattivi:

1. i webhook degli ordini — schermata Webhooks nella configurazione del modulo;
2. l'attività pianificata Doli2ShopOrdersCatchup;
3. l'attività pianificata Doli2ShopOrdersHistoricalImport.

Verifica con una sola query (sola lettura):

SELECT label, entity, status FROM llx_cronjob WHERE label LIKE 'Doli2Shop%';

Entrambe le attività devono mostrare status = 0. In un'installazione Multicompany, controllate inoltre che la colonna entity corrisponda all'entità in cui il modulo è configurato: un'attività creata nell'entità sbagliata gira a vuoto, senza segnalare alcun errore.

La sincronizzazione di prodotti e giacenze può invece proseguire in questa fase.

4. Il passaggio in produzione

1. Completate la migrazione e verificatela in Shopify.
2. Annotate l'istante esatto in cui la migrazione si è conclusa: chiamiamolo T0.
3. Riducete DOLI2SHOP_CATCHUP_LOOKBACK_HOURS a un valore che non risalga oltre T0: 1 o 2 ore. Il valore predefinito è 168 (7 giorni) e farebbe entrare immediatamente i vostri ordini migrati.
4. Attivate prima i webhook degli ordini, poi l'attività di recupero.

5. Dopo il passaggio — le verifiche

• Aprite la schermata degli eventi webhook: elenca ciò che arriva, con il relativo stato.
• Controllate che nessun ordine anteriore a T0 sia stato creato in Dolibarr.
• Riportate DOLI2SHOP_CATCHUP_LOOKBACK_HOURS al valore abituale (168) solo quando T0 risale a più di sette giorni. Prima di allora, la finestra raggiungerebbe i vostri ordini migrati.

6. Ciò che questa procedura non copre

La finestra di recupero limita l'attività pianificata, non i webhook.

Dopo il passaggio, qualsiasi modifica apportata in Shopify a un ordine migrato — una modifica, un rimborso, una correzione di indirizzo, l'aggiunta di un tag — genera un webhook orders/updated. Il modulo non conosce quell'ordine: lo crea. Ottenete così un ordine storico reimportato con la data di oggi.

Questa falla non si chiude con la procedura. La chiuderebbe un'impostazione di «data di messa in produzione»: ogni ordine Shopify creato prima della data scelta verrebbe escluso dall'importazione, qualunque sia il percorso — webhook di creazione, webhook di modifica, attività di recupero — mentre l'importazione storica deliberata conserva i propri limiti.

⚠️ Questa impostazione non esiste ancora nel modulo. È uno sviluppo, disponibile su preventivo. In sua assenza, l'unica difesa è la vigilanza sugli ordini migrati: non modificarli in Shopify dopo il passaggio e verificare regolarmente che nessun ordine anteriore a T0 sia comparso in Dolibarr.

7. Se un duplicato viene comunque creato

1. Individuatelo dalla schermata degli eventi webhook: l'evento riporta l'identificativo dell'ordine Shopify interessato.
2. Finché l'ordine creato in Dolibarr non è né validato né fatturato, eliminarlo non ha conseguenze contabili.
3. Se è già fatturato, la correzione segue la vostra prassi abituale in Dolibarr (nota di credito o annullamento, secondo la vostra politica contabile): il modulo non richiede nulla di particolare.
4. Rimuovete la causa prima di fare pulizia, altrimenti il webhook successivo ricreerà lo stesso ordine.