Collegare la Cassa a PrestaShop (Square, Zettle, SumUp): documentazione

Come funziona

PrestaShop è il riferimento dello stock. Ogni variazione di stock di un prodotto associato viene inviata alla cassa come quantità assoluta. Ogni vendita in cassa viene importata, scalata dallo stock PrestaShop con il motivo di movimento «Vendita in cassa», poi il nuovo livello torna alle altre casse. I resi rimettono gli articoli in stock con il motivo «Reso in cassa».

• Square: stock in entrambe le direzioni, vendite, resi, invio del catalogo.
• Zettle by PayPal: stock in entrambe le direzioni, vendite, rimborsi, invio del catalogo.
• SumUp: solo importazione delle vendite. L’API pubblica di SumUp non espone né stock né catalogo.

Requisiti

• PrestaShop da 8.0 a 9.x.
• Un cron sul tuo hosting.
• HTTPS sul negozio per il webhook Zettle.
• Un account Square, Zettle o SumUp con accesso sviluppatore.

Installazione

1. In Moduli > Gestione moduli, clicca su Carica un modulo e invia lo ZIP.
2. Il modulo aggiunge il menu Catalogo > Connettore cassa.
3. La dashboard mostra un elenco «Primi passi» che si spunta man mano che configuri il modulo.

Collegare le casse

Apri la scheda Connessioni. Ogni cassa ha il proprio riquadro con la casella Attivato. Le credenziali sono cifrate nel database: un campo lasciato vuoto mantiene il valore salvato.

Square

1. Crea un’applicazione nel Square Developer Dashboard e copia il suo token di accesso di produzione.
2. Incollalo in Token di accesso, scegli l’ambiente, salva e clicca su Prova la connessione.
3. Scegli il punto vendita che riceve lo stock. Se ne hai più di uno, seleziona quelli le cui vendite vanno importate (massimo 10).
4. Per l’importazione immediata, crea una sottoscrizione webhook sull’evento order.updated con l’URL di notifica mostrato, poi incolla la chiave di firma nel modulo. L’URL deve essere identico da entrambe le parti.

Zettle by PayPal

1. Nel Zettle Developer Portal, crea una chiave API self-hosted con gli scope READ:PURCHASE, READ:PRODUCT, READ:USERINFO e WRITE:PRODUCT.
2. Inserisci Client ID e chiave API, salva e prova la connessione.
3. Clicca su Attiva il webhook per ricevere le vendite in pochi secondi.
4. Il monitoraggio dello stock deve essere attivo sui prodotti in Zettle. I prodotti inviati dal modulo lo hanno automaticamente.

SumUp

1. Inserisci la chiave API segreta (sup_sk_...), salva e prova la connessione. Il codice esercente viene rilevato automaticamente.
2. Le vendite SumUp vengono associate per nome dell’articolo: riferimento esatto o nome esatto di un prodotto senza combinazioni.

Regole di sincronizzazione

In alto nella scheda Connessioni:

• Invia i livelli di stock PrestaShop alla cassa e, facoltativamente, subito dopo ogni variazione.
• Importa le vendite in cassa e scalale dallo stock PrestaShop.
• Rimetti in stock gli articoli resi (Square e Zettle).
• Associazione automatica per riferimento, per EAN-13 / UPC e per nome per SumUp.
• Importa le vendite in cassa a partire dal: le vendite precedenti vengono ignorate. Una vendita già importata non viene mai duplicata.

Attività pianificata e webhook

La dashboard mostra due URL. Pianifica il primo ogni 5 minuti e il secondo (con full=1) una volta a notte:

*/5 * * * * curl -s "https://tuo-negozio.it/module/dfposconnector/cron?token=TUO_TOKEN" >/dev/null
0 3 * * * curl -s "https://tuo-negozio.it/module/dfposconnector/cron?token=TUO_TOKEN&full=1" >/dev/null

Il cron importa le nuove vendite, invia lo stock in attesa e rileva le differenze create fuori da PrestaShop (import SQL, ERP). La sincronizzazione notturna rinvia tutti i livelli associati. Cron e webhook funzionano anche in modalità manutenzione.

Associare i prodotti

Scheda Associazione prodotti:

• Leggi il catalogo di Square o Zettle: associa automaticamente tramite SKU e codice a barre.
• Suggerisci prodotti per nome: propone un prodotto per ogni articolo rimanente, con un punteggio. I suggerimenti dal 90 % in su si accettano in blocco, gli altri uno per uno.
• Associazione manuale: cerca un prodotto per nome, riferimento o EAN.
• Invia tutto lo stock alla cassa, oppure importa lo stock dalla cassa in PrestaShop (da usare una sola volta, alla configurazione, se lo stock della cassa è quello affidabile).

Inviare il catalogo alla cassa

Scheda Invio catalogo: scegli la cassa, una categoria (sottocategorie incluse), il prezzo inviato (IVA inclusa o esclusa, senza sconti) e se considerare solo i prodotti attivi.

1. Verifica cosa verrà inviato legge prima il catalogo della cassa e associa ciò che esiste già, poi mostra il numero di prodotti e varianti da creare.
2. Creali nella cassa invia i prodotti a lotti con una barra di avanzamento. Le combinazioni diventano varianti. Ogni articolo creato viene associato e riceve il suo stock.

Non vengono inviati: i prodotti già associati in quella cassa, i prodotti virtuali, i pacchetti, le immagini e le categorie. Zettle accetta al massimo 99 varianti per prodotto.

Controllo stock

La scheda Controllo stock legge le quantità reali da Square o Zettle ed elenca le differenze con PrestaShop, dalla più grande. Per ogni riga:

• Invia lo stock PrestaShop: la cassa riceve il valore PrestaShop.
• Usa lo stock cassa: PrestaShop riceve il valore della cassa, con un movimento di magazzino.

Ordini PrestaShop per le vendite in negozio

Riquadro Ordini PrestaShop, disattivato per impostazione predefinita. Una volta attivato, ogni vendita con tutti gli articoli associati crea un ordine:

• cliente da banco dedicato all’indirizzo del negozio;
• vettore gratuito «Vendita in cassa», mai proposto al checkout;
• prezzi dello scontrino, con uno sconto globale ripartito sulle righe;
• ordine datato all’ora della vendita, con il riferimento della cassa nella nota interna;
• stato «Vendita in cassa» (pagato, consegnato, senza fattura né email), modificabile nelle impostazioni.

In questo caso è l’ordine a scalare lo stock. Durante la creazione non viene inviata alcuna email. Una vendita con articoli non associati non riceve un ordine: i suoi articoli associati vengono scalati direttamente.

Registro delle vendite

La scheda Vendite in cassa elenca ogni vendita con le sue righe, cassa, punto vendita, pagamento e, se presente, il link all’ordine. Filtri: cassa, stato (da associare, associate, resi, con ordine), ricerca per scontrino, articolo o punto vendita, intervallo di date. Il pulsante Esporta CSV esporta la selezione, una riga per articolo.

Avvisi email

Riquadro Avvisi email: viene inviata un’email quando la sincronizzazione pianificata fallisce 3 volte di seguito (al massimo una ogni 6 ore), poi un’altra quando torna a funzionare. Lascia vuoto l’indirizzo per usare quello del negozio. Il pulsante Invia un avviso di prova verifica l’invio.

Risoluzione dei problemi

«Inventario non inizializzato» su Zettle

Attiva il monitoraggio dello stock su almeno un prodotto in Zettle, oppure invia un prodotto dalla scheda Invio catalogo.

Webhook Square rifiutato (firma non valida)

L’URL di notifica dichiarato in Square deve coincidere carattere per carattere con quello del modulo, e la chiave di firma deve appartenere a quella sottoscrizione.

Lo stock non parte dopo una modifica in back office

PrestaShop non esegue gli hook di un modulo per un dipendente senza il permesso «Visualizza» su quel modulo. Il controllo delle differenze del cron recupera queste modifiche all’esecuzione successiva. Puoi anche concedere il permesso in Parametri avanzati > Team > Permessi.

Una vendita non ha creato un ordine

Il registro tecnico indica il motivo: articoli non associati, valuta della vendita assente in PrestaShop, restrizione del vettore su un prodotto o quantità inferiore a un’unità. In questo caso lo stock è stato scalato direttamente.

Disinstallazione

La disinstallazione elimina le tabelle del modulo (associazioni, registro delle vendite, coda, registro tecnico) e le sue impostazioni, e disattiva il vettore «Vendita in cassa». Gli ordini creati, lo stato dell’ordine, il cliente da banco e i motivi di movimento di magazzino vengono conservati, perché lo storico vi fa riferimento.