Questa maschera contiene tutta la configurazione del collegamento tra Atlantis e un sito WooCommerce: come raggiungerlo, in che verso far viaggiare i prodotti, come tradurre IVA, pagamenti e stati degli ordini, come creare i clienti che arrivano dal sito.
Qui non si sincronizza nulla: si configura soltanto. Le sincronizzazioni vere (scaricamento prodotti, caricamento prodotti e immagini, sincronizzazione quantità e prezzi, scaricamento ordini) si lanciano dalla maschera Gestione sito, che usa quanto impostato qui.
Si possono configurare più siti: ogni sito è un record con un proprio codice numerico.
1. Come funziona il collegamento
Vale la pena capirlo prima di compilare i campi, perché spiega l’ordine delle operazioni e la maggior parte degli errori.
Atlantis non dialoga direttamente con WooCommerce. Il collegamento avviene in due tempi:
- Atlantis carica sul sito, via FTP o SFTP, un piccolo client (un insieme di file PHP) nella cartella indicata. Durante il caricamento il client viene personalizzato con il token e con alcuni parametri (memoria, tempo massimo, nomi degli attributi taglia e colore);
- da quel momento Atlantis parla con il client via HTTP, autenticandosi con lo stesso token.
2. Testata
| Campo | A cosa serve |
|---|---|
| Codice | identificativo numerico del sito |
| Descrizione | nome con cui riconoscerlo negli elenchi |
| Url | indirizzo del sito, usato per tutte le chiamate al client |
| Attivo | disattivando il sito lo si esclude dalle elaborazioni |
| Tipo | WooCommerce |
Il pulsante Apri sito apre l’URL nel browser.
3. Scheda “Principale”
| Campo | A cosa serve |
|---|---|
| Token | la chiave condivisa tra Atlantis e il client sul sito. Genera ne crea una nuova di 64 caratteri |
| Modalità prodotti | il verso in cui viaggiano i prodotti (vedi sotto) |
| Attiva chiamate asincrone | da attivare se le chiamate al server vengono interrotte per timeout: il sito prepara i dati e Atlantis li recupera controllando ogni 10 secondi |
| Esecuzione sincronizzazione bloccata / in corso | semaforo automatico |
I tre pulsanti
- Test FTP sito – esegue la diagnostica passo passo della connessione (vedi § 9);
- Carica server – installa o aggiorna il client sul sito. Richiede che il record sia già salvato: se ci sono modifiche in sospeso compare “E’ necessario eseguire prima il salvataggio dei dati”;
- Apri sito – apre il sito nel browser.
Modalità prodotti
È la scelta che determina tutto il resto della configurazione dei prodotti:
| Modalità | Significato |
|---|---|
| Anagrafica articoli su sito | i prodotti nascono sul sito e Atlantis li scarica, creando automaticamente gli articoli in anagrafica |
| Gestione manuale | i prodotti si creano a mano da entrambe le parti; Atlantis si limita ad allineare quantità e prezzi |
| Anagrafica articoli su gestionale | i prodotti nascono in Atlantis e vengono pubblicati sul sito |
Scegliendo Anagrafica articoli su sito diventano obbligatori i campi che servono a creare gli articoli: N. giorni, unità di misura, gruppo merceologico e contropartita nella scheda Prodotti da sito.
Il flag di blocco sincronizzazione
Viene acceso automaticamente all’avvio di una sincronizzazione e spento alla fine: serve a impedire che due elaborazioni sullo stesso sito partano insieme.
⚠️ Se una sincronizzazione si interrompe in modo anomalo (blocco del programma, caduta della rete) il flag può restare acceso e le sincronizzazioni successive non partono. In quel caso va tolto a mano da qui, dopo essersi assicurati che non ci sia davvero un’elaborazione in corso.
4. Scheda “Prodotti”
Generale
| Campo | A cosa serve |
|---|---|
| Listino | con prodotti da sito, il listino in cui vengono scritti i prezzi letti dal sito; con prodotti da gestionale, il listino da cui vengono letti |
| Listino personalizz. | usato con prodotti da gestionale per determinare il prezzo da pubblicare |
| Listino personal. offerte | il prezzo in offerta: sul sito compare il prezzo scontato e il prezzo pieno barrato |
| Deposito movim./giac. | deposito usato per giacenze e per la creazione dei prodotti |
| N. dec. prezzi / N. dec. qta | decimali usati nello scambio dati |
| Qta da sincronizzare | Non sincronizzare, Esistenza, Disponibilità, Esistenza disponibile (al netto dell’impegnato da cliente) |
| Costo | il costo di riferimento da inviare |
| Stato nuovi prodotti | i prodotti creati sul sito nascono Pubblicati o in Bozza |
| Gestione descrizione | la descrizione va nella descrizione principale o nella descrizione breve del prodotto |
| Meta key barcode | nome del campo meta di WooCommerce che contiene il codice a barre |
| Ordini arretrati | se il sito accetta ordini a fronte di giacenza esaurita: non permettere, permetti, permetti e avvisa il cliente |
| Modalità aggiornamento prezzi | predefinita (segue la modalità prodotti) oppure aggiorna sempre i listini del sito con quelli del gestionale |
Sono inoltre presenti le opzioni di gestione varianti tramite codice variante (con modalità, separatore e generazione automatica del codice): usano il codice variante definito nella sezione Codici a barre dell’articolo per riconoscere le varianti.
⚠️ La gestione varianti generiche e la gestione varianti con codice variante sono incompatibili tra loro: attivandole entrambe, al salvataggio compare una segnalazione esplicita. Entrambe, inoltre, vanno attivate solo su configurazioni nuove: su un sito già avviato cambiano il modo in cui i prodotti vengono riconosciuti.
Prodotti da sito
I valori usati per creare gli articoli a partire dai prodotti del sito: unità di misura, gruppo merceologico, codice monofase, contropartita, numero di reparto, controlli su fuori giacenza e fuori disponibilità (non gestito / avvisa / blocca), struttura varianti per gli articoli taglia-colore.
Qui si imposta anche il comportamento dello scaricamento: N. gg (scarica i prodotti modificati negli ultimi n giorni), modo scarico varianti (tutte o solo quelle disponibili), scarica codice variante, usa varianti generiche, scarica prodotti non pubblicati.
Liste articoli
L’elenco delle liste articoli che determinano quali prodotti pubblicare sul sito, nella modalità “articoli da gestionale”. Con il flag Escludi una lista viene usata al contrario, per togliere articoli dalla pubblicazione.
Nei prodotti a varianti vengono comunque esportate tutte le varianti.
Immagini
| Campo | A cosa serve |
|---|---|
| Categoria Immagine principale | la categoria documenti da cui prendere l’immagine principale dell’articolo |
| Categoria altre Immagini | la categoria da cui prendere le immagini aggiuntive |
| Immagine watermark e Applica watermark | filigrana (formato PNG) da sovrapporre alle immagini pubblicate |
| Percorso immagini su sito | cartella di destinazione sul sito |
| Disattiva collegamento immagini | da attivare se le immagini si gestiscono direttamente dal sito |
Altri depositi
L’elenco dei depositi aggiuntivi che concorrono, sommandosi, all’esistenza o disponibilità inviata al sito. Serve a chi pubblica la giacenza complessiva di più magazzini.
Articoli / depositi
Un deposito specifico per singolo articolo, quando quell’articolo va sincronizzato guardando un magazzino diverso da quello generale. Se si compila una delle due colonne bisogna compilarle entrambe: la riga non viene salvata se manca l’articolo o il deposito.
Varie
Tre tabelle di dettaglio: Articoli / categorie (id categoria web per articolo), Articoli / Tag (id tag web per articolo) e Articoli correlati (prodotti da proporre insieme).
5. Scheda “Clienti”
Regola come vengono creati e riconosciuti i clienti che arrivano dal sito.
| Campo | A cosa serve |
|---|---|
| Prefisso num. clienti | prefisso per numerare a parte i clienti provenienti dal sito |
| Sottoconto, Categoria, Cod. contropartite, Categ. Provv. | valori attribuiti ai clienti creati |
| Cod. SDI default | codice destinatario impostato sui nuovi clienti |
| Meta key codice fiscale / partita IVA / cod. SDI / email PEC | i nomi dei campi meta di WooCommerce da cui leggere quei dati (es. billing_codice_fiscale) |
Il riconoscimento per e-mail
Due coppie di opzioni, una per i clienti registrati sul sito e una per gli acquisti Guest:
- Tenta di determinare clienti in archivio tramite email – invece di creare un nuovo cliente, Atlantis cerca in anagrafica un soggetto con la stessa e-mail e usa quello;
- Se trova cliente in archivio aggiorna l’anagrafica nel gestionale con dati sito – a riconoscimento avvenuto, sovrascrive i dati anagrafici con quelli del sito.
⚠️ La seconda opzione è segnalata come ATTENZIONE già nella maschera, ed è il caso di prenderla sul serio: attivandola, l’anagrafica curata nel gestionale viene sostituita da quella che il cliente ha digitato sul sito, indirizzo di fatturazione compreso. Attivala solo se il sito è la fonte autorevole dei dati cliente.
6. Scheda “Ordini”
Principale
| Campo | A cosa serve |
|---|---|
| N. gg | scarica gli ordini modificati negli ultimi n giorni |
| Stato ordini da importare | quali stati WooCommerce vanno importati (selezione multipla con Ctrl + clic) |
| Stato ordini da cancellare | gli stati che provocano la cancellazione dell’impegno già importato (es. ordine annullato o rimborsato) |
| Scarica ordini dal | data sotto la quale non scaricare nulla: utile alla prima attivazione per non importare lo storico |
| Causale doc. | la causale con cui viene creato l’impegno cliente. L’elenco è filtrato sui documenti di tipo impegno |
| Cod. spesa spediz. | la spesa con cui viene addebitato il costo di spedizione |
| Cod. articolo default | articolo da usare per le righe non riconosciute |
| Codice pagamento predefinito | usato quando sull’ordine non è indicata alcuna modalità di pagamento |
| Salva note su | note interne dell’impegno oppure note stampate |
| Ricalcola prezzi con condizioni commerciali cliente | ignora i prezzi del sito e riapplica listini e sconti del cliente |
| Applica condizione di pagamento del cliente | usa il pagamento dell’anagrafica invece di quello dell’ordine |
| Accoda codice variante WooCommerce a descrizione articolo | riporta il codice della variante nella descrizione di riga |
| Scarica ordini con valori IVA inclusa | l’ordine viene creato a valori lordi |
| Determina aliquota iva in base configurazione WooCommerce | usa le aliquote configurate su WooCommerce invece della tabella IVA (§ 7) |
| Escludi articoli in ordine da lista | una lista articoli le cui righe non vengono importate |
Pagamenti
La tabella di corrispondenza tra la descrizione del pagamento sul sito e il codice pagamento di Atlantis. Si compilano i due campi e si preme Aggiungi; la riga compare nell’elenco sottostante, con un collegamento Canc. per rimuoverla.
La corrispondenza viene cercata in due passaggi:
- corrispondenza esatta del testo (senza distinzione tra maiuscole e minuscole);
- espressione regolare, per le voci scritte con il prefisso
regex:– per esempioregex:^Paga in 3 rate\bintercetta tutte le varianti di quel testo.
⚠️ Se un ordine arriva con un pagamento che non trova corrispondenza, l’importazione di quell’ordine fallisce con “Corrispondenza codice pagamento non trovata per pagamento ‘…'”. Ogni volta che sul sito si attiva un nuovo metodo di pagamento, va aggiunta qui la riga corrispondente.
Stati ordine
La corrispondenza tra lo stato dell’ordine su WooCommerce e lo stato del documento in Atlantis: si indicano codice stato del sito e stato gestionale, poi Aggiungi.
Il pulsante con la i mostra l’elenco degli stati standard di WooCommerce:
| Codice | Significato |
|---|---|
pending |
pagamento in sospeso |
processing |
in elaborazione |
on-hold |
in attesa di pagamento (es. bonifico) |
completed |
completato |
cancelled |
cancellato |
refunded |
rimborsato |
failed |
pagamento fallito |
Escludi articoli in scaricamento ordini
Un elenco di testi: se la descrizione dell’articolo in una riga d’ordine contiene uno di questi testi, la riga non viene importata. Serve per le righe tecniche che WooCommerce aggiunge agli ordini e che non hanno senso nel gestionale.
7. Scheda “IVA”
La tabella di corrispondenza tra l’aliquota IVA del sito (il valore numerico, es. 22) e il codice IVA di Atlantis. Si compilano i due campi e si preme Aggiungi.
⚠️ Come per i pagamenti, un’aliquota non mappata fa fallire l’importazione dell’ordine con “Corrispondenza codici IVA non trovata per iva …”. Mappa tutte le aliquote che il sito può produrre, comprese quelle a 0 per le esenzioni.
Se si attiva l’opzione Determina aliquota iva in base configurazione WooCommerce (scheda Ordini), le aliquote vengono lette dalla configurazione del sito.
8. Scheda “FTP / SFTP”
Le credenziali con cui Atlantis installa il client e carica le immagini.
| Campo | Note |
|---|---|
| Tipo connessione | FTP, SFTP o FTPS |
| Host, Utente, Password, Porta | tipicamente 21 per FTP, 22 per SFTP |
| Cartella | la cartella radice del sito, es. /htdocs |
| Modalità passiva | solo per connessioni FTP |
9. Test FTP sito
La diagnostica passo passo del collegamento: ogni riga si spunta se il passaggio riesce, e ci si ferma al primo che fallisce mostrando l’errore. I controlli, nell’ordine, sono:
- connessione FTP, autenticazione utente, posizionamento sulla cartella;
- creazione di una cartella e caricamento di un file HTML;
- lettura via HTTP di quel file – è il passaggio che verifica che la cartella FTP corrisponda davvero all’URL del sito, l’errore di configurazione più frequente;
- cancellazione del file e della cartella;
- caricamento di uno script PHP, sua esecuzione via HTTP e cancellazione.
Conviene farlo passare tutto prima di premere Carica server.
10. Specifiche CMS → WooCommerce
I nomi degli attributi di WooCommerce che rappresentano taglia e colore (proposti taglia e colore). Vanno scritti esattamente come sono definiti sul sito.
Modificandoli è necessario ricaricare il client: questi due valori vengono scritti dentro la configurazione del client durante il caricamento.
11. Scheda “Avanzate”
| Campo | A cosa serve |
|---|---|
| Memoria massima | limite di memoria PHP del client, in MB. Richiede il ricaricamento del client |
| Tempo massimo | tempo massimo di esecuzione, in secondi. Richiede il ricaricamento del client |
| Nr. record per chiamata | quanti record per ogni chiamata nelle sincronizzazioni di articoli, quantità e prezzi (0 = 1000) |
| Intervallo fra chiamate server | pausa in secondi tra una chiamata e l’altra |
| Attiva log sincronizzazioni sul server | scrive un log lato sito, utile in diagnosi |
| Lingua default | proposta it |
| Script caricamento prodotti | script eseguito per ogni prodotto in fase di pubblicazione |
| Script ins.to / agg.to clienti | script eseguito all’inserimento o aggiornamento di un cliente |
Se il sito va in timeout o in errore di memoria durante le sincronizzazioni, i tre parametri da rivedere sono memoria, tempo massimo e numero di record per chiamata (abbassandolo), oltre alle chiamate asincrone nella scheda Principale.
Gli script
Accanto a ciascuno dei due campi, il pulsante con l’icona apre il template con le variabili disponibili.
Per lo script di caricamento prodotti:
| Variabile | Contenuto |
|---|---|
_ditta |
azienda corrente |
_xmlProd |
l’oggetto XML del prodotto già compilato, che sta per essere inviato |
_enArticolo |
l’articolo di Atlantis |
_enSito |
il sito corrente |
_listaDepositi |
i depositi considerati |
_tipoUpload |
A articoli, Q quantità, P prezzi e quantità |
Per lo script di inserimento/aggiornamento clienti: _ditta e _enSogg (il soggetto).
Servono per le personalizzazioni: modificare al volo un dato prima dell’invio, valorizzare campi non previsti, applicare regole specifiche del cliente.
12. Scheda “Note”
Riporta le indicazioni operative e i limiti dichiarati della procedura:
- sono gestiti i prezzi per variante: il prezzo particolare di una taglia o di un colore viene trasmesso al sito;
- nella struttura varianti la variante colore deve chiamarsi COLORE e quella taglia TAGLIA;
- nei dati scambiati,
NetPrice1eGrossPrice1sono sempre i prezzi di vendita netto e lordo IVA;NetPrice2eGrossPrice2, se presenti, sono i prezzi non in promozione.
13. Sequenza di attivazione di un nuovo sito
- crea il sito: codice, descrizione, URL, flag Attivo;
- compila la scheda FTP / SFTP e fai passare tutti i controlli di Test FTP sito;
- premi Genera per il token e salva il record;
- premi Carica server per installare il client sul sito;
- scegli la modalità prodotti e compila le schede Prodotti e Clienti di conseguenza;
- compila le tabelle di corrispondenza: IVA, pagamenti, stati ordine;
- imposta Scarica ordini dal per non importare tutto lo storico;
- salva, e prova le sincronizzazioni una alla volta da Gestione sito.
14. Promemoria
- Dopo aver rigenerato il token, cambiato gli attributi taglia/colore o i limiti di memoria e tempo, ricarica il client: finché non lo fai, sul sito resta la configurazione precedente.
- Carica server funziona solo con i dati salvati.
- Le tabelle di corrispondenza (IVA, pagamenti, stati, articoli esclusi) vengono memorizzate insieme al record: dopo aver premuto Aggiungi bisogna comunque salvare l’anagrafica, altrimenti le righe si perdono.
- Una corrispondenza mancante su IVA o pagamento fa fallire l’importazione del singolo ordine: sono le prime due cose da controllare quando “un ordine non è entrato”.
- Se le sincronizzazioni non partono più, controlla il flag “Esecuzione sincronizzazione bloccata / in corso” nella scheda Principale.
- Le opzioni marcate “attivare solo su nuove configurazioni” (varianti generiche, varianti con codice variante) non vanno attivate su un sito già in produzione.
- L’aggiornamento automatico dell’anagrafica cliente con i dati del sito sovrascrive quanto c’è nel gestionale: valutalo prima di attivarlo.