Il collegamento con Shopify tiene allineati il gestionale e un negozio online Shopify. Il gestionale pubblica sul negozio gli articoli, i prezzi, le immagini e le giacenze. Dal negozio arrivano gli ordini, che diventano ordini cliente, insieme ai clienti che li hanno fatti. Quando l’ordine viene evaso con un DDT o una fattura, la spedizione torna su Shopify con il corriere e il numero di tracking.

Da quando il collegamento è attivo, il gestionale è il master. Articoli, prezzi e giacenze si modificano nel gestionale; su Shopify si gestiscono solo la vetrina (collezioni, temi, canali di vendita) e le impostazioni del negozio.

Le funzioni si trovano in e-Commerce → Shopify:

Voce	A cosa serve
Anagrafica siti	la configurazione di ogni negozio: credenziali, listini, depositi, causali, transcodifiche
Test connessione	verifica le credenziali e i permessi e permette di scegliere la location delle giacenze
Gestione sito	si usa tutti i giorni: pubblicazione, giacenze, import degli ordini, evasioni, primo allineamento
Log sincronizzazioni	l’esito di ogni operazione e gli elementi rimasti in coda

Le voci compaiono solo se il modulo e-commerce Shopify è in licenza.

1. Come funziona il collegamento

Il gestionale dialoga direttamente con Shopify tramite le API ufficiali, con le credenziali di un’app creata sul negozio (sezione 2). Sul sito non si installa nulla.

Cosa viaggia e in quale verso:

Dato	Verso	Quando
Articoli, varianti, prezzi, immagini	gestionale → Shopify	a mano, da Gestione sito
Giacenze	gestionale → Shopify	in automatico dopo ogni import degli ordini, oppure a mano
Ordini e clienti	Shopify → gestionale	con la procedura schedulata, oppure a mano
Evasioni (spedito, corriere, tracking)	gestionale → Shopify	a mano, da Gestione sito
Rimborsi	Shopify → gestionale	segnalati durante l’import degli ordini
Prodotti già presenti su Shopify	Shopify → gestionale	una sola volta, con il primo allineamento

Tre regole spiegano quasi tutti i comportamenti:

L’abbinamento si fa per SKU. Per un articolo senza varianti lo SKU Shopify coincide con il codice articolo. Per un articolo con varianti lo SKU di ogni variante è il barcode di tipo CVAR della variante. I CVAR mancanti li genera il gestionale alla prima pubblicazione. Dopo il primo collegamento il gestionale riconosce i prodotti anche per identificativo interno: uno SKU cambiato su Shopify non rompe il collegamento, ma la pubblicazione successiva lo riscrive con quello del gestionale.
La disponibilità online è l’esistenza meno l’impegnato, sommata sui depositi del sito, meno la scorta di sicurezza. Un ordine Shopify importato diventa impegnato: la merce venduta online non torna disponibile.
Prima gli ordini, poi le giacenze. La procedura schedulata importa gli ordini e subito dopo invia le giacenze cambiate. Inviare le giacenze senza aver importato gli ordini renderebbe di nuovo disponibile la merce appena venduta.

2. Preparare Shopify: l’app e i permessi

Chi crea l’app

L’app si crea nell’organizzazione Shopify del negozio, dal Dev Dashboard di Shopify. Può crearla il titolare del negozio, oppure un account dello staff con il permesso Sviluppo app. I collaboratori esterni non hanno accesso al Dev Dashboard.

App e negozio devono appartenere alla stessa organizzazione. In caso contrario la richiesta del token viene rifiutata e il gestionale mostra:

“L’app non e’ installata sul negozio. Nel Dev Dashboard di Shopify: rilasciare una versione dell’app con gli scope necessari e installarla sul negozio. App e negozio devono appartenere alla stessa organizzazione: un negozio di sviluppo creato dal pannello di Shopify invece che dal Dev Dashboard non ne fa parte.”

I passi

Nel Dev Dashboard crea una nuova app, per esempio “Atlantis Evo”.
Nella configurazione della versione indica i permessi (scope) elencati sotto.
Rilascia la versione dell’app.
Installa l’app sul negozio.
Dalle impostazioni dell’app copia Client ID e Client secret. Vanno nella scheda Connessione dell’anagrafica siti (sezione 3).

I permessi da concedere

Concedi all’app tutti questi scope:

read_customers,write_customers,read_files,write_files,write_inventory,read_inventory,write_locations,read_locations,read_orders,write_orders,read_products,write_products,read_merchant_managed_fulfillment_orders,write_merchant_managed_fulfillment_orders,read_publications,write_publications

Scope	A cosa serve
`read_products`, `write_products`	pubblicare articoli, varianti e prezzi; leggere il catalogo per il primo allineamento; collezioni IVA
`read_files`, `write_files`	caricare le immagini degli articoli
`read_inventory`, `write_inventory`	leggere e scrivere le giacenze
`read_locations`, `write_locations`	elencare le location del negozio per scegliere quella delle giacenze
`read_orders`, `write_orders`	leggere gli ordini e i rimborsi
`read_customers`, `write_customers`	leggere i clienti degli ordini
`read_merchant_managed_fulfillment_orders`, `write_merchant_managed_fulfillment_orders`	segnare gli ordini come spediti, con corriere e tracking
`read_publications`, `write_publications`	rendere disponibili i prodotti nuovi nei canali di vendita (Online Store…)

Se il negozio è in più lingue, o ha una lingua principale diversa dall’italiano (sezione 8), servono anche:

read_locales,read_translations,write_translations

Scope	A cosa serve
`read_locales`	leggere le lingue attivate sul negozio e quella principale
`read_translations`, `write_translations`	leggere e scrivere le traduzioni dei prodotti

Test connessione elenca gli scope concessi e segnala quelli che mancano (“Scope mancanti per le fasi successive: …”).

⚠️ Dopo aver aggiunto uno scope bisogna rilasciare una nuova versione dell’app e, se Shopify lo chiede, riapprovarla sul negozio. Senza gli scope delle evasioni, Invia evasioni viene rifiutato da Shopify.

Accesso ai dati protetti dei clienti

Nome, indirizzo, email e telefono dei clienti sono dati protetti per Shopify. Senza l’autorizzazione a leggerli, Shopify non restituisce gli ordini: Importa ordini si ferma con un errore simile a

“This app is not approved to access the Order object … [ACCESS_DENIED]”

e non viene importato nulla. L’accesso si concede nel portale Partners di Shopify (partners.shopify.com):

entra nel portale Partners con l’account che ha creato l’app;
apri App e seleziona l’app;
vai in API access requests (richieste di accesso alle API) → Protected customer data access;
nella prima parte indica il motivo d’uso dei dati: gestione ed evasione degli ordini, fatturazione;
nella seconda parte seleziona i campi Nome, Email, Telefono e Indirizzo, ciascuno con il suo motivo;
salva. Per un’app ad uso del solo negozio non serve la revisione di Shopify.

Su alcuni negozi l’accesso è concesso in automatico alle app create dal titolare. Se Importa ordini funziona già, non serve fare nulla. Se compare ACCESS_DENIED, questo è il passo mancante.

Impostazioni del negozio da controllare

Valuta del negozio uguale a quella del listino del sito (di norma EUR). Se sono diverse, la pubblicazione si ferma con “La valuta del negozio (…) e’ diversa da quella del listino (…): impostare la valuta del negozio su Shopify o cambiare listino”.
Prezzi IVA inclusa o esclusa (Impostazioni → Imposte e dazi). Il gestionale legge questa impostazione e converte i prezzi del listino: non va dichiarata da nessuna parte.
Aliquota del paese: Shopify applica l’aliquota ordinaria dell’Italia a tutti i prodotti. Le aliquote ridotte richiedono un’eccezione IVA per ogni aliquota (sezione 8).
Location: quella scelta per le giacenze deve essere attiva e evadere gli ordini online. Una location che non evade gli ordini online fa risultare i prodotti esauriti nel negozio anche con la quantità caricata.
Dati fiscali nel checkout: codice fiscale, partita IVA e PEC arrivano dai campi fiscali italiani del checkout Shopify, se il negozio li raccoglie. Il codice SDI non ha un campo nativo: serve un attributo del checkout, aggiunto con un’app o una personalizzazione del checkout, e il suo nome va indicato nell’anagrafica del sito.

3. Anagrafica siti

Ogni negozio è un record con un codice numerico. Se ne possono configurare più di uno.

Testata

Campo	A cosa serve
Codice	identificativo numerico del sito
Descrizione	nome del negozio negli elenchi (obbligatoria, fino a 50 caratteri)
Attivo	solo i siti attivi compaiono in Gestione sito, ricevono le giacenze in coda e vengono elaborati dallo scheduler

Scheda “Connessione”

Campo	A cosa serve
Dominio negozio	`xxx.myshopify.com`. Si può incollare anche l’indirizzo del pannello (`admin.shopify.com/store/xxx`) o il solo nome: il gestionale lo converte e lo salva nella forma giusta
Versione API	versione delle API Shopify usata dal gestionale, proposta `2026-07`. Non va cambiata, salvo indicazione dell’assistenza
Client ID	dalle impostazioni dell’app
Client secret	dalle impostazioni dell’app. A video compaiono asterischi e nel database viene salvato cifrato
Location giacenze, Id location	la location Shopify su cui si scrivono le giacenze. Non si digitano: si scelgono dal test di connessione
Test connessione e scelta location…	apre il test di connessione (sezione 4) sul sito. Funziona solo sul sito già salvato: altrimenti “Salvare il sito prima di eseguire il test di connessione”

La cifratura del Client secret nasconde il dato a chi legge il database. Non è una protezione forte: la chiave è nel programma.

Scheda “Prodotti e giacenze”

Campo	A cosa serve
Listino	listino dei prezzi pubblicati. Obbligatorio per pubblicare
Listino offerte	facoltativo. Se per l’articolo esiste un prezzo in offerta, su Shopify il prezzo del listino normale diventa il prezzo di confronto (barrato) e quello in offerta il prezzo di vendita
Scorta di sicurezza	quantità tolta dalla disponibilità di ogni variante prima dell’invio, per non vendere online l’ultimo pezzo

Il listino può essere IVA inclusa o esclusa: il gestionale converte il prezzo con l’aliquota dell’articolo secondo l’impostazione del negozio.

Scheda “Liste articoli”

Gli articoli da pubblicare si scelgono con le liste articoli, anche dinamiche. Si pubblicano gli articoli delle liste indicate, tolti quelli delle liste con Escludi gli articoli di questa lista. Ogni riga si conferma con Conferma riga.

Con nessuna lista la pubblicazione si ferma: “Nessun articolo nelle liste del sito: impostare le liste articoli prima di pubblicare”.
Un articolo che esce dalle liste viene messo in bozza su Shopify, mai cancellato. Se rientra nelle liste torna attivo.

Scheda “Depositi”

I depositi che formano la disponibilità online: si somma l’esistenza meno l’impegnato di ciascun deposito. Senza depositi l’invio delle giacenze si ferma: “Nessun deposito indicato nel sito Shopify: impostare i depositi che formano la disponibilita’ online”.

Solo i movimenti dei depositi indicati qui mettono in coda le giacenze da inviare.

Scheda “Ordini e clienti”

Campo	A cosa serve
Causale ordini	causale degli ordini cliente creati dagli ordini Shopify. Da questa dipendono causale di magazzino, deposito e scarico
Serie documento	serie degli ordini cliente. Se è vuota si usa la serie della causale. Deve essere riservata agli ordini Shopify (vedi sotto)
Spesa di spedizione	codice spesa su cui si riporta la spedizione pagata dal cliente
Pagamento predefinito	pagamento dell’ordine quando il metodo Shopify non ha transcodifica. Se manca anche questo, si usa il pagamento del cliente
Sottoconto clienti nuovi	sottoconto contabile dei clienti creati dall’import. Obbligatorio: senza, l’import si ferma con “Sottoconto dei clienti nuovi non impostato nel sito Shopify”
Categoria clienti nuovi	categoria assegnata ai clienti creati
Prefisso codice clienti	1 carattere (predefinito `S`). Il codice dei clienti nuovi è il prefisso seguito da 6 caratteri, un progressivo del sito in base 36, per esempio `S00001A`
Attributo checkout SDI	nome dell’attributo del checkout che contiene il codice SDI (fino a 50 caratteri)
Escludi gli ordini di prova	di norma attivo: gli ordini fatti con il gateway di prova di Shopify non si importano
Ordini dal	data di partenza del collegamento. Obbligatoria: gli ordini creati prima non si importano mai, neanche se modificati dopo, e non ricevono le evasioni

Il numero dell’ordine cliente è il numero dell’ordine Shopify (l’ordine #1001 diventa il documento 1001 della serie del sito). Se nella serie esiste già un ordine con quel numero non collegato a Shopify, l’import si ferma con “il numero … e’ gia’ usato da un altro ordine: la serie deve essere riservata agli ordini Shopify”.

Scheda “Transcodifiche e opzioni”

Il riquadro Opzioni:

Opzione	Effetto
Prodotti nuovi pubblicati come	Attivi (visibili nel negozio) oppure Bozza (da pubblicare su Shopify). Vale solo per i prodotti creati; negli aggiornamenti lo stato scelto su Shopify non si tocca
Codici CVAR mancanti composti con	codici oppure sigle dei valori delle varianti, per i CVAR generati alla pubblicazione
Separatore	carattere fra le parti del CVAR generato; vuoto = trattino
Aliquota IVA ordinaria del negozio %	vuoto = 22. Gli articoli con un’aliquota diversa (e maggiore di zero) ricevono la collezione IVA della sezione 8
Canali di vendita dei prodotti nuovi	canali in cui rendere disponibili i prodotti creati dal gestionale, con i nomi che mostra Shopify separati da virgola (per esempio Online Store, Point of Sale). Vuoto = Online Store; `-` = nessun canale. Il pulsante Scegli… legge i canali dal negozio (il sito deve essere salvato) e li fa scegliere da un elenco, anche più di uno con Ctrl+clic
Alla spedizione Shopify avvisa il cliente via email (invio evasioni)	se attiva, all’invio dell’evasione Shopify manda al cliente l’email di spedizione

Le quattro tabelle di transcodifica (Aggiungi / Elimina righe):

Tabella	Chiave	Valore
Pagamenti	nome del metodo di pagamento come lo riporta Shopify. Si legge nelle note interne dell’ordine importato, riga Pagamento Shopify	pagamento del gestionale
Aliquote IVA	aliquota in percentuale: 22, 10, 4, 5,5, 0	codice IVA
Stati ordine	stato del pagamento su Shopify: In attesa di pagamento, Autorizzato, Pagato in parte, Pagato, Rimborsato in parte, Rimborsato, Annullato, Scaduto. L’ultima riga vale per gli ordini il cui totale non coincide con Shopify	stato dell’ordine cliente
Lingue	lingua del negozio Shopify, con il codice di Shopify: `en`, `it`, `de`, `pt-BR`… Compresa la lingua principale del negozio, se è diversa dall’italiano	lingua del gestionale da cui prendere i testi (sezione 8)

⚠️ Le transcodifiche si salvano con il record. Dopo aver aggiunto le righe bisogna salvare l’anagrafica.

Senza transcodifica dell’aliquota, l’ordine usa il codice IVA dell’articolo, se ha la stessa aliquota. Altrimenti l’ordine non viene importato e resta in coda. Le righe e le spedizioni su cui Shopify non applica imposte richiedono la riga con aliquota 0, con un codice esente o non imponibile. Senza quella riga compare “riga senza IVA su Shopify: indicare nelle transcodifiche del sito (scheda Aliquote IVA) il codice IVA per l’aliquota 0 (esente o non imponibile)”.

Scheda “Primo allineamento”

Valori usati per gli articoli creati dal primo allineamento, cioè per i prodotti già presenti su Shopify e assenti nel gestionale (sezione 6).

Campo	A cosa serve
Unità di misura	UM degli articoli creati
Codice iva	codice IVA degli articoli creati: Shopify non conosce l’aliquota dei prodotti, quindi è lo stesso per tutti
Gruppo merceologico	gruppo degli articoli creati
Lista articoli creati	lista statica, da inserire anche nella scheda Liste articoli, a cui si aggiungono gli articoli creati. Senza, la pubblicazione successiva metterebbe in bozza i prodotti appena collegati
Causale carico iniziale	causale del documento di magazzino con le quantità presenti su Shopify
Deposito carico iniziale	deposito di quel documento
Primo allineamento eseguito	lo imposta la procedura. Finché non è attivo, pubblicazione e invio giacenze sono bloccati

4. Test connessione

Si apre dal menu o dal pulsante della scheda Connessione. Chiede il token a Shopify e legge i dati del negozio. Mostra:

nome del negozio, valuta, prezzi IVA inclusa o esclusa, piano;
scope concessi e “Scope mancanti per le fasi successive”; gli scope delle traduzioni si controllano solo se il sito ha la tabella Lingue;
le lingue del negozio, per esempio it (principale), en, de (non pubblicata);
limite di chiamata disponibile;
i canali di vendita del negozio, da copiare nell’opzione Canali di vendita dei prodotti nuovi;
l’elenco delle location attive, con l’indicazione (non evade ordini online) dove serve.

Seleziona la location e premi Usa la location selezionata per le giacenze: viene salvata nel sito. Se la location salvata non è più attiva sul negozio, il test avvisa: “La location impostata sul sito non e’ fra quelle attive del negozio: sceglierne una.”

Errori tipici del token:

Messaggio	Causa
“…L’app non e’ installata sul negozio…”	app non rilasciata, non installata, o in un’altra organizzazione (sezione 2)
“Client ID o Client secret non corretti: ricopiarli dalle impostazioni dell’app nel Dev Dashboard.”	credenziali sbagliate

5. Avviare il collegamento: i casi possibili

La preparazione di Shopify (sezione 2) e la compilazione dell’anagrafica (sezione 3) sono uguali in tutti i casi. Cambia l’ordine delle operazioni, a seconda di dove si trovano già i dati.

5.1 Il gestionale è già in uso e si apre un negozio Shopify nuovo

È il caso più semplice: gli articoli ci sono già, il negozio è vuoto.

Prepara gli articoli. Crea una o più liste articoli con quello che vuoi vendere online e controlla per quegli articoli:
- titolo e descrizione web nella lingua di default (altrimenti si usano descrizione e descrizione aggiuntiva);
- marca, gruppo merceologico, tag;
- prezzo nel listino del sito;
- immagini nell’archivio documenti, nelle categorie immagine principale e altre immagini dei dati fissi;
- per gli articoli con varianti, al massimo 3 dimensioni (Shopify non ne gestisce di più).
Prepara Shopify (sezione 2): app, scope, valuta, prezzi IVA inclusa, location.
Crea il sito nell’anagrafica e salvalo. Poi Test connessione e scelta della location.
Compila Liste articoli, Depositi, Ordini e clienti e Transcodifiche e opzioni. Come Ordini dal metti il giorno di apertura del negozio.
Primo allineamento da Gestione sito, scheda Utilità. Sul negozio vuoto non trova prodotti. L’anteprima lo conferma e l’esecuzione segna il sito come allineato.
Pubblica tutti (scheda Articoli). Se vuoi controllare i prodotti prima di mostrarli, imposta prima l’opzione Prodotti nuovi pubblicati come: Bozza.
Per ogni aliquota ridotta imposta l’eccezione IVA sulla collezione IVA n% creata dalla pubblicazione (sezione 8).
Invia tutte le giacenze (scheda Giacenze): il negozio è ancora fermo, quindi non ci sono ordini da perdere.
Fai un ordine di prova e importalo con Importa ordini. Controlla cliente, righe, IVA, spedizione e totale. Poi evadilo con un DDT e prova Invia evasioni.
Configura la procedura schedulata (sezione 13) e apri il negozio.

5.2 Il negozio Shopify è già in uso e il gestionale è vuoto

Il catalogo è su Shopify. Il primo allineamento crea gli articoli nel gestionale partendo dai prodotti del negozio.

Prepara Shopify (sezione 2). Controlla che ogni variante abbia uno SKU e che gli SKU siano univoci. Gli SKU dei prodotti senza varianti possono avere al massimo 20 caratteri, quelli delle varianti 50.
Nel gestionale prepara:
- le tabelle di base (unità di misura, codici IVA, un gruppo merceologico, il listino e l’eventuale listino offerte);
- una lista articoli statica per gli articoli creati;
- una causale di magazzino per il carico iniziale e il deposito.
Crea il sito e compila tutte le schede, compresa Primo allineamento. Metti la lista degli articoli creati anche nella scheda Liste articoli.
Primo allineamento (sezione 6). Leggi con attenzione l’anteprima: conflitti, prodotti senza SKU, configurazione mancante. Correggi su Shopify i conflitti che ti interessano e ripeti l’analisi finché il risultato è quello atteso. Poi conferma.
Controlla gli articoli creati prima di pubblicare. In particolare:
- il codice IVA: è quello della scheda Primo allineamento per tutti. Correggi gli articoli ad aliquota ridotta;
- le descrizioni e i prezzi nel listino;
- il documento di carico iniziale, che porta in giacenza le quantità presenti su Shopify.
Pubblica tutti. Da questo momento il gestionale è master: titolo, descrizione, prezzi e varianti di Shopify vengono riscritti con quelli del gestionale. Le immagini del negozio sono già state scaricate nell’archivio documenti e vengono riusate, non ricaricate.
Eccezioni IVA sulle collezioni IVA n% (sezione 8).
Come Ordini dal metti il giorno da cui il gestionale riceve gli ordini. Gli ordini precedenti restano solo su Shopify e i clienti vengono creati man mano che arrivano ordini nuovi.
Scegli un momento di negozio fermo, oppure lancia Importa ordini subito prima, e fai Invia tutte le giacenze.
Configura la procedura schedulata.

5.3 Il negozio Shopify è già in uso e anche il gestionale è già avviato

Gli articoli esistono da entrambe le parti. Il primo allineamento li collega e crea nel gestionale solo quelli che mancano.

Allinea gli SKU prima di iniziare. Il collegamento è automatico solo se:
- lo SKU di un prodotto Shopify senza varianti è uguale al codice articolo;
- lo SKU di ogni variante è uguale al barcode CVAR della variante corrispondente nel gestionale.
Maiuscole e minuscole non contano. Dove non coincidono, correggi lo SKU su Shopify, oppure aggiungi il CVAR giusto alla variante nel gestionale.
Controlla che la struttura varianti del gestionale corrisponda alle opzioni Shopify: tutte le varianti di un prodotto devono portare allo stesso articolo.
Crea il sito e compila le schede. Le liste articoli devono contenere gli articoli già in vendita online: gli articoli collegati che non sono nelle liste vengono aggiunti alla Lista articoli creati, se è impostata.
Primo allineamento, con l’anteprima. Oltre ai conflitti, guarda le differenze di giacenza sui prodotti collegati: dopo l’allineamento vince la giacenza del gestionale, e per i prodotti collegati non si genera nessun carico. Se il gestionale non ha giacenze affidabili, fai prima un inventario.
Correggi i conflitti e ripeti l’analisi quante volte serve: l’allineamento ripetuto non crea doppioni.
Conferma. Poi controlla gli articoli creati (codice IVA, prezzi) come nel caso 5.2.
Pubblica tutti: i prodotti collegati vengono riscritti con i dati del gestionale. Se un articolo non ha immagini nel gestionale, quelle di Shopify restano. Se ha la descrizione vuota, quella di Shopify non viene toccata.
Eccezioni IVA, poi Invia tutte le giacenze a negozio fermo, poi la procedura schedulata.
Come Ordini dal metti il giorno da cui gli ordini arrivano dal collegamento: quelli precedenti, inseriti a mano, non vengono importati di nuovo.

⚠️ Non pubblicare e non inviare giacenze prima del primo allineamento. Il gestionale lo impedisce (“Primo allineamento non eseguito: eseguirlo prima di pubblicare, per non creare doppioni dei prodotti gia’ presenti sul negozio”). Non attivare a mano il flag Primo allineamento eseguito su un negozio che ha già dei prodotti.

6. Il primo allineamento

Si lancia da Gestione sito, scheda Utilità, Primo allineamento…. Serve una sola volta per negozio, ma si può ripetere senza creare doppioni.

Anteprima

La procedura legge tutto il catalogo Shopify e non scrive nulla. Nel riquadro Avanzamento elenca:

i prodotti collegati ad articoli esistenti;
i prodotti da creare nel gestionale;
i prodotti con varianti senza SKU;
i conflitti, con il motivo;
gli articoli delle liste del sito che su Shopify non ci sono (li creerà la pubblicazione);
le giacenze diverse fra gestionale e Shopify sui prodotti collegati;
la configurazione mancante.

Un prodotto va in conflitto, e resta escluso, se:

lo SKU è ripetuto nel negozio;
solo alcune varianti trovano un articolo, oppure varianti diverse portano ad articoli diversi;
l’articolo è già abbinato a un altro prodotto;
il prodotto ha più di 3 opzioni;
lo SKU supera i 50 caratteri (20 per un prodotto senza varianti);
lo SKU di un prodotto senza varianti è il codice di un articolo con varianti.

Le gift card non vengono mai importate.

Se manca la configurazione per creare gli articoli, la procedura lo dice e non chiede conferma: “Per creare gli articoli completare prima nell’anagrafica del sito: …”.

Conferma

La domanda riepiloga quanti prodotti si collegano e quanti articoli si creano. La casella Crea anche i N prodotti con varianti senza SKU va spuntata solo se sei sicuro che quei prodotti non esistono già nel gestionale: senza SKU non si possono riconoscere, e il rischio è un doppione. Per queste varianti il CVAR viene generato e lo SKU viene scritto su Shopify alla prima pubblicazione.

Cosa crea

Per ogni prodotto da creare:

l’articolo:
- codice = SKU in maiuscolo per i prodotti senza varianti;
- per i prodotti con varianti, l’handle Shopify in maiuscolo se entra in 20 caratteri, altrimenti SH più un progressivo;
UM, codice IVA e gruppo dalla scheda Primo allineamento; la marca se ne esiste una con la stessa descrizione del fornitore (vendor) Shopify (le marche non si creano);
una struttura varianti propria, con le sole combinazioni presenti su Shopify, e un CVAR per variante uguale allo SKU;
il barcode Shopify come barcode web;
i prezzi nel listino del sito. Se su Shopify c’è un prezzo di confronto, questo va nel listino normale e il prezzo di vendita nel listino offerte;
il peso, il titolo, la descrizione e i tag nella lingua di default;
la riga nella lista articoli creati;
le immagini, scaricate nell’archivio documenti: la prima come immagine principale, le altre (fino a 10) nella categoria delle altre immagini; l’immagine di una variante viene collegata anche alla variante.

Le immagini si scaricano anche per gli articoli collegati che nel gestionale non ne hanno.

Infine viene creato un solo documento di carico con le quantità disponibili su Shopify, una riga per ogni variante con giacenza. Se il documento non si riesce a salvare, gli articoli restano creati: l’esito lo segnala e il log elenca le quantità da caricare a mano.

A fine procedura il sito è segnato come allineato, anche se ci sono conflitti: i prodotti in conflitto restano esclusi finché non li correggi e ripeti l’allineamento.

7. Gestione sito

In alto si sceglie il Sito (solo i siti attivi). Apri apre l’anagrafica del sito, Log… la consultazione del log. Il riquadro Avanzamento mostra cosa sta facendo l’operazione in corso e il risultato.

Scheda “Ordini”

Pulsante	Cosa fa
Importa ordini	importa gli ordini nuovi o modificati e ritenta quelli in coda. Poi invia le giacenze in coda
Reimporta ordine…	chiede il numero (1001 o #1001) e reimporta quell’ordine anche se non è cambiato. Serve per recuperare un ordine cancellato per errore nel gestionale
Ordini in coda: N	ordini non importati per un errore. Un clic apre il log sulle code, con il motivo
Invia evasioni	invia a Shopify le spedizioni dei DDT e delle fatture, con data da Ordini dal
Invia evasione ordine…	come sopra, per un solo ordine e senza limite di data

Scheda “Giacenze”

Pulsante	Cosa fa
Invia giacenze in coda	invia solo le varianti cambiate dai movimenti di magazzino. Mostra quante sono in attesa
Invia tutte le giacenze	invia le giacenze di tutti gli articoli pubblicati. Operazione di servizio: chiede conferma e va usata a negozio fermo o subito dopo Importa ordini
Invia giacenze singolo articolo	invia le giacenze dell’articolo indicato

Scheda “Articoli”

Pulsante	Cosa fa
Pubblica singolo l’articolo	pubblica l’articolo indicato, anche se non è cambiato
Pubblica modificati	pubblica gli articoli delle liste nuovi o cambiati dall’ultima pubblicazione (dati, prezzo, varianti, immagini, aliquota)
Pubblica tutti	ripubblica tutti gli articoli delle liste. Chiede conferma: con molti articoli richiede tempo, ma le immagini già caricate non si reinviano

Scheda “Utilità”

Primo allineamento… (sezione 6), la riga Semaforo e il pulsante Sblocca (sezione 14).

Se un’operazione è già in corso nella maschera compare “Operazione in corso: attendere la fine”.

8. Pubblicazione dei prodotti

La pubblicazione è solo manuale: salvare un articolo non lo invia al negozio. Dopo aver cambiato prezzi, descrizioni o immagini usa Pubblica modificati.

Cosa si invia per ogni articolo:

Su Shopify	Dal gestionale
Titolo	descrizione web della lingua di default, altrimenti descrizione dell’articolo
Descrizione	descrizione estesa (HTML) della lingua di default, altrimenti descrizione aggiuntiva
Titolo e descrizione per i motori di ricerca	titolo web e meta description della lingua di default
Fornitore	marca
Tipo prodotto	gruppo merceologico
Tag	tag dell’articolo e della descrizione web, più il tag IVA (sotto)
Opzioni e varianti	una opzione per dimensione della struttura varianti, al massimo 3
SKU	codice articolo, oppure CVAR della variante
Prezzo e prezzo di confronto	dai listini del sito
Barcode, peso	barcode web, peso lordo
Immagini	archivio documenti: immagine principale, altre immagini, immagine di ogni variante

Regole:

un prodotto nuovo nasce attivo o in bozza secondo l’opzione del sito; negli aggiornamenti lo stato impostato su Shopify non cambia;
un prodotto viene reso disponibile nei canali di vendita dell’opzione del sito una sola volta: alla creazione, oppure al primo invio dopo l’aggiornamento del programma per i prodotti già pubblicati. Poi i canali si gestiscono su Shopify e il gestionale non li tocca più. Senza canale un prodotto attivo non compare da nessuna parte;
se i canali non si possono leggere (manca lo scope write_publications) il prodotto si pubblica lo stesso, ma resta da reinviare: Pubblica modificati lo riprova al giro successivo;
un articolo obsoleto, eliminato o uscito dalle liste va in bozza. Nessun prodotto viene mai cancellato;
un articolo senza immagini nel gestionale non tocca quelle presenti su Shopify;
se un prodotto collegato è stato cancellato su Shopify, viene ricreato;
prima di creare un prodotto si cerca su Shopify una variante con lo stesso SKU, per non creare doppioni;
le collezioni del negozio non si toccano, salvo le collezioni IVA.

Aliquote IVA ridotte

Shopify non conosce l’aliquota dei singoli articoli: applica a tutti l’aliquota ordinaria dell’Italia, a meno che il prodotto stia in una collezione con eccezione IVA. Il gestionale fa la sua parte in automatico:

agli articoli con aliquota diversa dall’ordinaria del sito (e maggiore di zero) aggiunge il tag IVA 10%, IVA 4%, IVA 5.5%…;
crea la collezione manuale IVA 10% (e così via), una per aliquota;
ci inserisce i prodotti con quell’aliquota e li toglie quando l’aliquota cambia.

Gli articoli esenti vengono pubblicati come non soggetti a imposte.

Una volta per ogni aliquota bisogna impostare l’eccezione su Shopify, perché non esiste un modo di farlo dal gestionale:

pubblica almeno un articolo con quell’aliquota e controlla che la collezione IVA n% esista e contenga il prodotto;
su Shopify: Impostazioni → Imposte e dazi → Italia → Eccezioni sui prodotti → aggiungi un’eccezione per la collezione IVA n% con l’aliquota giusta;
fai un ordine di prova: su Shopify deve comparire l’IVA ridotta, e l’ordine cliente deve entrare con il codice IVA corrispondente.

⚠️ Le eccezioni IVA valgono solo sulle collezioni manuali. Non trasformare le collezioni IVA n% in collezioni automatiche. Se ne esiste una automatica con quel nome, la pubblicazione segnala l’errore: va eliminata su Shopify e l’articolo ripubblicato.

Senza eccezione, Shopify scorpora il 22% anche da un articolo al 10%, e l’ordine entra al 22%.

Lingue e traduzioni

Se il sito ha la tabella Lingue (scheda Transcodifiche e opzioni), a ogni pubblicazione il gestionale legge le lingue del negozio e usa la tabella in due modi:

lingua principale del negozio (su Shopify Settings → Languages, quella marcata Default): se è nella tabella, i testi principali del prodotto si prendono dalla lingua del gestionale abbinata. Se non è nella tabella, i testi principali restano quelli della lingua di default del gestionale;
tutte le altre righe diventano traduzioni, compresa la lingua di default del gestionale quando il negozio ha un’altra lingua principale.

Esempio: il negozio ha l’inglese come lingua principale e l’italiano e il tedesco come traduzioni. La tabella Lingue è:

Lingua Shopify	Lingua
`en`	`ENG`
`it`	`ITA`
`de`	`DEU`

Il prodotto si pubblica con i testi inglesi dell’articolo, e l’italiano e il tedesco arrivano come traduzioni. Se il negozio avesse l’italiano come lingua principale, basterebbe la riga en → ENG.

I testi usati:

Su Shopify	Dal gestionale, nella lingua abbinata
Titolo	descrizione web
Descrizione	descrizione estesa (HTML)
Tipo prodotto	descrizione in lingua del gruppo merceologico
Titolo e descrizione per i motori di ricerca	titolo web e meta description
Tag (solo testi principali)	tag web, insieme ai tag dell’articolo

Quando un testo manca:

Caso	Cosa si usa
testi principali, lingua abbinata senza testo	i dati dell’articolo: descrizione, descrizione aggiuntiva, gruppo merceologico. L’articolo si pubblica comunque, con l’avviso “testi nella lingua … (lingua principale del negozio) mancanti: usati quelli dell’articolo per …”
traduzione nella lingua di default del gestionale	la descrizione web in quella lingua, altrimenti i dati dell’articolo, che sono già in quella lingua
traduzione in un’altra lingua	solo la descrizione web in quella lingua. Senza testo il campo non si traduce, e il cliente vede il testo principale

Regole:

le traduzioni fatte su Shopify restano: quelle a mano e quelle della traduzione automatica (Translate & Adapt) non vengono toccate, finché il gestionale non ha un testo proprio per quel campo. Quando ce l’ha, vince il gestionale, come per il resto del prodotto;
un testo svuotato nel gestionale toglie da Shopify solo la traduzione inviata dal gestionale, e solo se nessuno l’ha cambiata su Shopify nel frattempo;
si inviano solo i campi cambiati, e le traduzioni entrano nel confronto di Pubblica modificati: cambiare un testo tradotto fa ripubblicare l’articolo;
opzioni e valori delle varianti (taglia, colore…) restano in una sola lingua, quella delle descrizioni dei valori nel gestionale. Per un negozio tutto in inglese vanno scritte in inglese;
un campo si può tradurre solo se ha un testo principale. Per esempio, una meta description presente solo nella traduzione non si invia, e il log lo segnala come avviso;
i tag non si traducono: Shopify non lo prevede.

All’inizio di ogni pubblicazione il riquadro Avanzamento dice quale lingua usa, per esempio “Lingua principale del negozio: en, testi dalla lingua ENG del gestionale” e “Traduzioni in: de da DEU, it da ITA”. Casi particolari:

Situazione	Cosa succede
lingua principale del negozio non in tabella	testi principali dalla lingua di default del gestionale, con un avviso
lingua della tabella non attivata sul negozio	traduzioni non inviate, con l’avviso “Lingua ‘…’ non attivata sul negozio (Impostazioni, Lingue): traduzioni non inviate. Dopo averla attivata usare ‘Pubblica tutti'”
lingua attivata ma non pubblicata	traduzioni inviate; i clienti le vedono quando la lingua viene pubblicata
lingue del negozio non leggibili (mancano gli scope)	si pubblica come senza tabella: testi principali dalla lingua di default, nessuna traduzione; gli articoli restano da reinviare al giro successivo

Una riga nuova nella tabella Lingue fa risultare modificati tutti gli articoli, e Pubblica modificati li reinvia. Se invece la riga c’era già e la lingua è stata attivata su Shopify solo dopo, lancia Pubblica tutti: per il gestionale gli articoli non sono cambiati.

⚠️ Se cambi la lingua principale del negozio su Shopify, lancia Pubblica tutti. Finché non lo fai, i prodotti già pubblicati hanno i testi principali nella lingua precedente.

Nel primo allineamento, se la lingua principale del negozio è nella tabella, titolo, descrizione e tag dei prodotti Shopify vanno nella descrizione web di quella lingua. La descrizione dell’articolo si prende comunque dal titolo di Shopify. Le traduzioni presenti su Shopify non si importano.

9. Giacenze

La quantità inviata per ogni variante è la somma, sui depositi del sito, di esistenza meno impegnato clienti, meno la scorta di sicurezza, arrotondata all’intero e mai negativa. Il riservato non si sottrae.

Si inviano solo le varianti già pubblicate, e solo quelle che su Shopify hanno una quantità diversa.
Gli articoli senza gestione giacenza non si inviano.
Se nel frattempo è arrivato un ordine e Shopify ha cambiato la quantità, il gestionale rilegge e riprova.

In automatico. Ogni documento che muove il magazzino su un deposito del sito mette in coda le varianti pubblicate che cambiano: salvataggio o cancellazione da maschera, POS, Web API, trasferimenti, rettifiche d’inventario. La coda si svuota con la procedura schedulata, subito dopo l’import degli ordini, oppure con Invia giacenze in coda.

Non passano dalla coda:

l’azzeramento dei saldi;
la modifica manuale dei saldi;
la ricostruzione dei movimenti;
il cambio codice e la cancellazione degli articoli;
le conversioni dati.

Dopo una di queste operazioni usa Invia tutte le giacenze, a negozio fermo.

10. Import degli ordini e dei clienti

Ogni ordine Shopify diventa un ordine cliente con:

Nel gestionale	Da Shopify
Numero, serie, esercizio	numero dell’ordine, serie del sito, anno della data dell’ordine
Riferimento cliente	nome dell’ordine (`#1001`)
Cliente	vedi sotto
Righe	articolo e variante dallo SKU; quantità attuali; prezzi e sconti
Spese	spedizione sulla spesa del sito, al netto degli sconti di spedizione
Destinazione	indirizzo di spedizione, se diverso da quello di fatturazione; viene aggiunto anche fra le destinazioni del cliente
Pagamento	transcodifica, poi pagamento predefinito, poi pagamento del cliente
Stato	transcodifica dello stato del pagamento
Confermato	sì, se l’ordine è pagato
Note interne	numero Shopify, metodo di pagamento (Pagamento Shopify: …), nota e attributi del checkout, riepilogo degli sconti con i codici usati

Sconti.

Uno sconto sull’intero ordine va in testata: in percentuale se su Shopify è uno solo in percentuale, altrimenti a valore.
Uno sconto di riga in percentuale va nello sconto della riga; quello a valore, o più sconti sulla stessa riga, vanno nel prezzo netto.
Lo sconto previsto dal codice di pagamento non si applica agli ordini Shopify.

Controllo del totale. Se il totale del gestionale differisce da quello di Shopify di più di un centesimo, l’ordine entra comunque. La differenza viene scritta nelle note interne e l’ordine prende lo stato dell’ultima riga della transcodifica stati (da verificare).

Clienti. Il cliente si cerca, nell’ordine, per collegamento, per codice d’import, per email. Se non esiste viene creato con:

codice = prefisso + progressivo;
persona fisica, se mancano ragione sociale e partita IVA;
codice fiscale o partita IVA dai campi fiscali del checkout (11 cifre = partita IVA);
PEC dal campo fiscale del checkout;
SDI dall’attributo indicato nel sito; 0000000 per i clienti italiani nuovi senza SDI;
sottoconto, categoria e pagamento dal sito.

Di un cliente esistente si completano solo i campi vuoti: i dati già presenti, in particolare quelli fiscali, non vengono sovrascritti.

Ordini che non entrano. Un ordine con un errore non viene importato e resta in coda. Viene ritentato a ogni giro, per al massimo 20 volte. I casi tipici:

una riga senza SKU, o con uno SKU che non corrisponde a nessun articolo (tipicamente un prodotto creato su Shopify e non nel gestionale): crea o correggi l’articolo, oppure correggi lo SKU su Shopify;
un’aliquota senza transcodifica;
il numero già usato nella serie.

Il motivo si legge nel log, scheda Code.

Ordini modificati su Shopify. Un ordine non ancora evaso né fatturato viene sostituito con la versione aggiornata. Un ordine già evaso o fatturato non si modifica più: la differenza resta segnalata nel log.

Ordini annullati su Shopify. Se l’ordine cliente non è evaso né fatturato viene cancellato. Altrimenti resta e l’annullamento è segnalato nel log.

11. Evasioni e tracking

Quando evadi un ordine Shopify con un DDT o una fattura, anche in più volte e per righe parziali, Invia evasioni segna come spedite su Shopify le righe corrispondenti. Una fattura fatta direttamente dall’ordine evade tutto il residuo.

Si considerano i documenti con data da Ordini dal. Invia evasione ordine… lavora su un solo ordine, senza limite di data.
Le righe aggiunte nel gestionale, che su Shopify non esistono, vengono ignorate. Le quantità sono arrotondate all’intero.
Le spedizioni già fatte a mano su Shopify non vengono raddoppiate.
Un documento già inviato non si reinvia. Se nel frattempo è cambiato il tracking, viene aggiornato su Shopify.

Corriere e tracking.

Numero di tracking: campo N. Tracking nella scheda dei vettori del documento. Vale il primo vettore del documento che ha un numero.
Nome corriere e URL di tracciamento: nell’anagrafica Vettori, scheda Tracciamento (Archivi → Tabelle → Trasporto → Vettori).
- Il nome va scritto come lo riconosce Shopify (BRT, GLS, Poste Italiane, SDA, DHL Express, UPS…); se è vuoto si usa il nome del vettore.
- L’URL è l’indirizzo della pagina di tracciamento con {tracking} al posto del numero, per esempio https://www.corriere.it/tracking?numero={tracking}. Se è vuoto e il corriere è noto a Shopify, il link lo genera Shopify.

Un documento senza tracking si può inviare subito con il solo corriere. Il numero, aggiunto dopo, parte con il successivo Invia evasioni.

L’email di spedizione al cliente parte se è attiva l’opzione Alla spedizione Shopify avvisa il cliente via email.

12. Rimborsi

Un rimborso fatto su Shopify:

su un ordine non ancora evaso né fatturato: l’ordine viene reimportato con le quantità correnti e lo stato della transcodifica (Rimborsato, Rimborsato in parte);
su un ordine già evaso o fatturato: l’ordine non si tocca. Il gestionale:
- scrive un avviso nel log e nel riquadro di avanzamento, per esempio “Ordine #1002 gia’ evaso o fatturato: rimborsato su Shopify il 26/09/2026 per 25,50 EUR: valutare nota di credito o reso nel gestionale”, con il dettaglio delle righe rimborsate (e se la merce è stata rimessa a magazzino su Shopify) e la nota del rimborso;
- aggiunge una riga alle note interne dell’ordine cliente;
- conta il rimborso nell’esito (rimborsi da gestire).

Ogni rimborso si segnala una sola volta. Nessun documento viene creato in automatico: la nota di credito o il reso si fanno a mano.

13. La procedura schedulata

In automatico gira una sola procedura, Import ordini Shopify e invio giacenze, che importa gli ordini e poi invia le giacenze in coda. Si configura in Utilità → Amministrazione → Schedulatore con:

classe it.dao.atlantis.shopify.schedule.ShSchOrdini;
parametro: il codice del sito;
un intervallo breve, per esempio ogni 5 o 10 minuti;
le notifiche (popup o email) per ricevere l’esito quando ci sono ordini importati, errori, ordini da verificare o rimborsi.

⚠️ Lo scheduler gira dentro il programma dell’utente schedulatore. Se su quella postazione Atlantis è chiuso, gli ordini non si importano e le giacenze non si inviano.

Non esiste una procedura schedulata delle sole giacenze, per scelta: inviarle senza aver importato prima gli ordini rimetterebbe in vendita la merce appena venduta. La pubblicazione dei prodotti e l’invio delle evasioni restano manuali.

14. Il semaforo

Due sincronizzazioni contemporanee dello stesso sito, per esempio dallo scheduler e da un’altra postazione, potrebbero importare due volte un ordine o inviare giacenze sbagliate. Per questo ogni operazione di Gestione sito e dello scheduler prende un semaforo del sito. La pubblicazione dei prodotti non lo prende.

Se il semaforo è già preso compare “E’ in corso un’altra sincronizzazione del sito (scheduler o altra postazione): riprovare fra poco”.
La riga Semaforo della scheda Utilità mostra se è libero, oppure chi lo tiene, da quando e quando si libera.
Il semaforo si libera da solo dopo 30 minuti. Le operazioni lunghe lo rinnovano mentre lavorano.
Sblocca lo toglie a mano, dopo una conferma. Serve quando una postazione è stata chiusa durante un invio. Usalo solo se sei certo che nessuna sincronizzazione sia davvero in corso. Lo sblocco resta nel log.

15. Log sincronizzazioni

Si apre dal menu, dal pulsante Log… di Gestione sito o con un clic sulle righe delle code. Il pulsante di aggiornamento nella barra rilegge log e code con i filtri impostati.

Scheda “Log”

Filtri Dal (proposto: una settimana fa), Al, Flusso, Esito, Testo.
- Flussi: CONNESSIONE, PRODOTTI, GIACENZE, ORDINI, EVASIONI, ALLINEAMENTO.
- Esiti: OK, AVVISO, ERRORE.
- Il testo si cerca nel messaggio, nel riferimento e nell’identificativo Shopify.
L’elenco mostra le righe più recenti per prime, al massimo 5000.
Selezionando una riga, sotto compare il dettaglio completo. Per un ordine importato il dettaglio riporta, riga per riga, articolo, importo, aliquota e IVA di Shopify e codice IVA scelto: è il primo posto dove guardare quando l’IVA di un ordine non torna.
Elimina piu’ vecchi di… cancella le righe del sito anteriori alla data indicata (proposta: tre mesi fa), dopo aver mostrato quante sono.

Scheda “Code”

Gli ordini non importati e le giacenze non inviate, con il motivo dell’ultimo errore.

La colonna Esaurito indica gli elementi che hanno raggiunto il numero massimo di tentativi (10 per le giacenze, 20 per gli ordini) e che non si ritentano più da soli.
Ritenta azzera i tentativi. Togli dalla coda elimina l’elemento. Funzionano anche su più righe selezionate.

Un ordine tolto dalla coda non viene più importato: si recupera con Reimporta ordine da Gestione sito.

16. Promemoria

Gli scope dell’app vanno concessi tutti, e dopo ogni aggiunta bisogna rilasciare una nuova versione. Se gli ordini non si importano con ACCESS_DENIED, manca l’accesso ai dati protetti dei clienti nel portale Partners.
Mai pubblicare o inviare giacenze prima del primo allineamento su un negozio che ha già dei prodotti, e mai spuntare a mano Primo allineamento eseguito in quel caso.
Dopo il primo allineamento vince il gestionale: controlla codice IVA, prezzi e giacenze degli articoli prima di Pubblica tutti.
La serie degli ordini Shopify è riservata: non inserirci ordini a mano.
Ogni aliquota ridotta vuole la sua eccezione IVA su Shopify, sulla collezione manuale IVA n%. Senza, l’ordine entra al 22%.
Invia tutte le giacenze solo a negozio fermo o subito dopo Importa ordini. Nell’uso normale bastano lo scheduler e la coda.
Negozio con lingua principale diversa dall’italiano (per esempio tutto in inglese): metti anche la lingua principale nella tabella Lingue, altrimenti i testi principali restano in italiano. Taglie e colori vanno scritti nella lingua del negozio.
Dopo aver attivato una lingua o cambiato la lingua principale sul negozio lancia Pubblica tutti.
Un prodotto attivo senza canale di vendita non si vede: controlla l’opzione Canali di vendita dei prodotti nuovi e lo scope write_publications.
Salvare un articolo non lo pubblica: dopo modifiche a prezzi, descrizioni o immagini lancia Pubblica modificati.
Un ordine evaso o fatturato non viene più aggiornato: modifiche, annullamenti e rimborsi successivi compaiono nel log e vanno gestiti a mano.
Lo scheduler gira solo mentre Atlantis è aperto sulla postazione dell’utente schedulatore.
Quando un ordine “non è entrato”, guarda la scheda Code del log: nove volte su dieci è uno SKU senza articolo o un’aliquota senza transcodifica.

Manuale Atlantis Evo

Shopify