PS PrestaShop Intermedio

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

Installare il modulo, collegare Square, Zettle o SumUp, associare i prodotti e sincronizzare stock e vendite tra la cassa e PrestaShop.

Aggiornato Versione del modulo 2.0.0

Come funziona

Il modulo collega PrestaShop alla tua cassa Square, Zettle by PayPal o SumUp. Importa in un registro ogni vendita, reso e rimborso della cassa, aggiorna lo stock nella direzione che scegli e può trasformare ogni vendita in un ordine PrestaShop. Può anche inviare il tuo catalogo PrestaShop alla cassa.

Lo stock si sincronizza in una delle tre direzioni seguenti, impostata per ogni cassa:

  • Dal negozio alla cassa: PrestaShop è il riferimento. Le vendite in cassa vengono scalate in PrestaShop, poi il nuovo livello torna alla cassa.
  • Dalla cassa al negozio: la cassa è il riferimento. PrestaShop riprende le quantità della cassa a ogni esecuzione del cron e a ogni webhook di stock.
  • Bidirezionale: le variazioni fatte su ciascun lato dall’ultima sincronizzazione vengono sommate. Una vendita online e una vendita in negozio contano ciascuna una sola volta.
Pannello del connettore cassa: vendite importate, stock sincronizzato, errori, coda e ultima sincronizzazione
Pannello del connettore cassa

Cosa fa ogni cassa

  • Square: vendite, resi e rimborsi, stock nelle tre direzioni, più punti vendita, invio del catalogo con l’immagine principale, webhook firmati.
  • Zettle by PayPal: vendite e rimborsi, stock nelle tre direzioni, invio del catalogo, webhook firmato creato dal modulo.
  • SumUp: vendite e rimborsi, scalati dallo stock PrestaShop. L’API pubblica di SumUp non espone né stock, né catalogo, né webhook per le vendite in cassa: l’importazione avviene tramite il cron, e lo stock mostrato in SumUp non viene aggiornato.

Il modulo non sostituisce la tua cassa e non la rende una cassa certificata. Scontrini, chiusura e obblighi fiscali restano gestiti da Square, Zettle o SumUp.

Requisiti

  • PrestaShop da 1.7.8 a 9.x. Il modulo è stato testato su PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) e 9.1.5 (PHP 8.5).
  • Un cron sul tuo hosting.
  • Un negozio in HTTPS per i webhook e per la connessione OAuth.
  • Un account Square, Zettle o SumUp, e l’accesso alla sua area sviluppatori se ti colleghi con un token o una chiave API.

Installazione e aggiornamento

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

Per passare da una versione 1.x alla 2.0.0, invia il nuovo ZIP nello stesso modo. L’aggiornamento conserva le associazioni, il registro delle vendite, le connessioni, i cursori di importazione (nessuna vendita viene reimportata) e le impostazioni. Gli URL dei webhook esistenti restano validi. L’aggiornamento aggiunge le nuove tabelle, cifra di nuovo i vecchi segreti e toglie dallo stato «Vendita in cassa» l’indicatore di spedizione che causava un secondo pagamento. Gli ordini già creati non vengono modificati.

Collegare le casse

La scheda Connessioni mostra lo stato di ogni cassa e le funzioni disponibili. Ogni cassa ha la propria procedura guidata. I segreti vengono memorizzati cifrati e non vengono mai mostrati di nuovo né scritti nel registro. Un campo lasciato vuoto mantiene il valore salvato.

Connessioni Square, Zettle e SumUp con le funzioni disponibili
Connessioni Square, Zettle e SumUp con le funzioni disponibili

Square

  1. Scegli la modalità di connessione. OAuth è consigliato: autorizzi il modulo dal tuo account Square, e il token viene rinnovato automaticamente. Per un solo negozio puoi anche incollare un token di accesso personale.
  2. In OAuth, inserisci l’ID e il segreto della tua applicazione Square, e dichiara in quell’applicazione l’URL di reindirizzamento mostrato. Il modulo chiede solo i permessi necessari: punti vendita, ordini, pagamenti, catalogo, stock e clienti in lettura, catalogo e stock in scrittura.
  3. Clicca su Connetti con Square, accetta i permessi, poi su Verifica la connessione.
  4. Scegli il punto vendita che tiene lo stock, e spunta quelli di cui importare le vendite (massimo 10).
  5. Per l’importazione immediata, aggiungi in Webhooks > Subscriptions l’URL di notifica mostrato con gli eventi order.updated, refund.created, inventory.count.updated e oauth.authorization.revoked, poi incolla la chiave di firma nel modulo. L’URL deve essere identico, carattere per carattere, da entrambe le parti.
Assistente di connessione Square: OAuth, permessi minimi, punti vendita
Assistente di connessione Square

Il pulsante di connessione OAuth ti porta alla pagina di autorizzazione della cassa, sul suo sito, poi ti riporta nel modulo. La schermata qui sotto è stata acquisita in modalità dimostrazione, con una pagina di autorizzazione simulata.

Schermata di autorizzazione OAuth simulata (modalità demo)
Schermata di autorizzazione OAuth simulata (modalità demo)
Punti vendita Square: punto vendita di stock e importazione vendite
Punti vendita Square

Zettle by PayPal

  1. Per un solo negozio è consigliata la chiave API self-hosted: creala nello Zettle Developer Portal e incollala con il suo Client ID. È disponibile anche una connessione OAuth per un’applicazione partner, con rinnovo automatico dei token.
  2. Salva, poi verifica la connessione.
  3. Clicca su Attiva il webhook: il modulo crea da solo la sottoscrizione (PurchaseCreated, InventoryBalanceChanged) e conserva cifrata la sua chiave di firma. Zettle richiede un negozio in HTTPS.
  4. Il monitoraggio dello stock deve essere attivo sui prodotti in Zettle. I prodotti inviati dal modulo lo hanno automaticamente.
Assistente di connessione Zettle: chiave API o OAuth e webhook firmato
Assistente di connessione Zettle

SumUp

  1. Incolla la tua chiave API segreta (dashboard SumUp, Developers > API keys) con il tuo codice esercente, oppure collegati in OAuth.
  2. Verifica la connessione. Il codice esercente viene letto automaticamente se manca.
  3. SumUp non invia webhook per le vendite in cassa: vengono importate dal cron ogni 5 minuti. Vengono associate per riferimento o per nome dell’articolo.
Assistente di connessione SumUp: chiave API o OAuth, importazione tramite cron
Assistente di connessione SumUp

Scollegare una cassa

Il pulsante Disconnetti revoca i token quando la cassa lo consente (Square, Zettle) e li elimina da PrestaShop. Le associazioni e il registro delle vendite vengono conservati.

Direzione dello stock

In Impostazioni > Magazzino, scegli la direzione dello stock per Square e per Zettle: dal negozio alla cassa, dalla cassa al negozio, bidirezionale o nessuna sincronizzazione dello stock. Per SumUp, le vendite vengono scalate dallo stock PrestaShop, ma la sua cassa non riceve lo stock.

  • Solo una cassa può essere il riferimento dello stock. Se ne scegli una seconda, il modulo la imposta su Bidirezionale.
  • In bidirezionale, la fonte di riferimento decide il primo allineamento e i conflitti.
  • Un livello scritto dal modulo non viene mai rinviato, per evitare effetti eco. Quando la cassa conta già le proprie vendite, l’importazione non le scala una seconda volta.
  • L’opzione Invia subito dopo ogni modifica del magazzino PrestaShop invia il livello immediatamente. Altrimenti parte alla successiva esecuzione del cron.
Direzione di sincronizzazione dello stock per cassa e fonte di riferimento
Direzione di sincronizzazione dello stock per cassa e fonte di riferimento

Associare i prodotti

La scheda Associazioni collega ogni articolo della cassa a un prodotto o a una combinazione PrestaShop.

  • Leggi il catalogo di Square o Zettle: gli articoli vengono associati automaticamente tramite SKU (riferimento del prodotto o della combinazione) e tramite codice a barre EAN-13 / UPC.
  • Suggerimenti per nome: per ogni articolo rimanente, il modulo propone il prodotto più vicino con un punteggio. I suggerimenti dal 90 % in su si possono accettare in blocco, gli altri uno per uno. Nessun suggerimento viene salvato senza la tua conferma.
  • Associazione manuale: cerca un prodotto per nome, riferimento o EAN.
  • Un articolo venduto in cassa ma assente dal catalogo letto compare anche nella coda. Puoi nasconderlo se non è venduto online.
Associazioni tra articoli di cassa e prodotti PrestaShop con suggerimenti
Associazioni tra articoli di cassa e prodotti PrestaShop con suggerimenti

Associare un articolo recupera lo stock delle vendite già importate, una sola volta. Le righe di vendita passate vengono collegate alla nuova regola.

Inviare il catalogo alla cassa

La scheda Catalogo crea i tuoi prodotti PrestaShop in Square o Zettle: combinazioni come varianti, prezzi, SKU, codice a barre, immagine principale facoltativa, poi lo stock. 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, associa tramite SKU o codice a barre ciò che esiste già, poi mostra il numero di prodotti e di varianti da creare.
  2. Spunta la conferma, poi clicca su Creali nella cassa: i prodotti partono a lotti, con una barra di avanzamento, e ogni articolo creato viene associato subito.
Invio del catalogo PrestaShop alla cassa con anteprima prima della creazione
Invio del catalogo PrestaShop alla cassa con anteprima prima della creazione

Gli articoli esistenti della cassa non vengono mai modificati. Su Square, ogni articolo viene collegato a un’imposta Square esistente con la stessa aliquota: non viene creata nessuna imposta. I prodotti virtuali e i pacchetti sono esclusi, e le categorie non vengono inviate. Zettle accetta al massimo 99 varianti per prodotto. SumUp non può ricevere prodotti tramite la sua API.

Controllo dello stock e riconciliazione

La scheda Magazzino confronta lo stock PrestaShop e lo stock della cassa per ogni articolo associato, ed elenca le differenze. Per ogni differenza, o per una selezione:

  • Mantieni PrestaShop: la cassa riceve la quantità PrestaShop.
  • Mantieni la cassa: PrestaShop riceve la quantità della cassa, con un movimento di magazzino.

La sincronizzazione completa notturna esegue una riconciliazione e ne conserva il rapporto. I rapporti precedenti restano consultabili. Importa tutte le giacenze della cassa sovrascrive lo stock PrestaShop di ogni prodotto associato: da usare una sola volta, alla configurazione, se lo stock della cassa è il più affidabile.

Riconciliazione dello stock tra PrestaShop e la cassa con report delle differenze
Riconciliazione dello stock tra PrestaShop e la cassa con report delle differenze

Vendite in cassa

La scheda Vendite in cassa elenca ogni scontrino con le sue righe, la cassa, il punto vendita, il pagamento, l’IVA per riga, la mancia e, se presente, l’ordine PrestaShop. Filtri: cassa, tipo (vendite, resi e rimborsi, ordini PrestaShop), differenze di importo, ricerca per scontrino, articolo, punto vendita o numero d’ordine, e intervallo di date. Esporta CSV esporta la selezione.

Registro delle vendite in cassa con ordine PrestaShop, IVA e mancia
Registro delle vendite in cassa con ordine PrestaShop, IVA e mancia

L’importazione è idempotente: una vendita già importata non viene mai duplicata, anche se arriva da più webhook e dal cron nello stesso momento. Vengono importati anche gli scontrini registrati offline in cassa e trasmessi più tardi. Le vendite precedenti alla data impostata in Importa le vendite in cassa dal vengono ignorate.

Ordini PrestaShop per le vendite in negozio

In Impostazioni > Ordini e rimborsi, l’opzione Crea un ordine PrestaShop per ogni vendita in cassa i cui articoli sono tutti associati è disattivata per impostazione predefinita. Una volta attivata:

  • un cliente da banco per negozio, all’indirizzo del negozio;
  • un vettore gratuito «Vendita in cassa», mai proposto al checkout;
  • il metodo di pagamento «Cassa – Square / Zettle / SumUp», un solo pagamento, e un ordine datato all’ora della vendita;
  • i prezzi e gli sconti dello scontrino, ripartiti sulle righe;
  • la mancia fuori dal totale dell’ordine, riportata nella sua nota;
  • nessuna email, né al cliente né a te.

Lo stato predefinito è «Vendita in cassa» (pagato, consegnato, senza email né fattura). Se PrestaShop ricalcola un totale diverso dallo scontrino (regole fiscali, arrotondamenti), la differenza viene mostrata sulla vendita e annotata nel registro.

Impostazioni di ordini, fatture, rimborsi e clienti identificati
Impostazioni di ordini, fatture, rimborsi e clienti identificati
  • Consenti le fatture per gli ordini di cassa: disattivato per impostazione predefinita, perché la cassa rilascia già lo scontrino. Senza questa opzione, uno stato che genera una fattura viene rifiutato. Con questa opzione, la fattura viene creata sul pagamento esistente e segnalata nel registro.
  • Clienti identificati (Square): l’ordine può essere collegato al cliente PrestaShop esistente che ha lo stesso indirizzo email del cliente Square. Viene usato solo un cliente esistente con un indirizzo: non viene creato nessun cliente né alcun indirizzo.
Ordine PrestaShop creato per una vendita in cassa, con il riepilogo dello scontrino
Ordine PrestaShop creato per una vendita in cassa, con il riepilogo dello scontrino

Una vendita che contiene articoli non associati non riceve un ordine: i suoi articoli associati vengono scalati direttamente dallo stock.

Resi e rimborsi

I resi Square, i rimborsi Zettle e i rimborsi SumUp vengono importati, compresi quelli parziali. Gli articoli resi tornano in stock una sola volta, tramite la riga di reso. Un rimborso senza articoli resi non modifica lo stock. Sull’ordine originale, scegli:

  • Solo una nota nell’ordine (predefinito);
  • Nota di credito per gli articoli resi o l’importo rimborsato;
  • Nota di credito, e stato «Rimborsato» una volta che l’ordine è stato rimborsato interamente.
Reso parziale in cassa rimesso a stock con nota di credito
Reso parziale in cassa rimesso a stock con nota di credito

Attività pianificate e webhook

Impostazioni > Attività pianificate mostra l’URL del cron. Richiamalo ogni 5 minuti, e lo stesso URL 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 elabora la coda dei webhook, importa le nuove vendite, rinnova i token e invia i livelli di stock in attesa. Due esecuzioni non si sovrappongono mai. L’esecuzione notturna rinvia tutti i livelli associati e genera il rapporto di riconciliazione.

Ogni webhook viene controllato prima di essere accettato:

  • la chiave URL propria dei webhook, distinta dal token del cron;
  • la firma della cassa;
  • una dimensione massima di 256 KB;
  • un’età massima di 96 ore;
  • un identificativo di evento mai visto prima.

Il modulo risponde subito, poi elabora l’evento. Una notifica non firmata, con firma errata o ripetuta viene rifiutata e annotata nel registro.

Registro tecnico

La scheda Registro elenca errori, avvisi e informazioni, filtrabili per cassa, livello, problema, testo e data. Ogni errore noto indica la causa e la soluzione, con un link alla schermata interessata. Token, chiavi e firme vengono mascherati prima di essere scritti. Le voci vengono conservate per 30 giorni per impostazione predefinita (modificabile), e gli ultimi eventi webhook ricevuti vengono elencati.

Registro tecnico filtrabile con causa e soluzione di ogni errore
Registro tecnico filtrabile con causa e soluzione di ogni errore

Avvisi

La scheda Avvisi raccoglie i problemi in corso con la causa, la soluzione e un pulsante Risolvi ora. Un avviso si chiude da solo quando il problema scompare.

  • sincronizzazione fallita per 3 esecuzioni di seguito, poi un messaggio quando torna a funzionare;
  • token rifiutato o impossibile da rinnovare, permesso mancante, firme dei webhook rifiutate;
  • aggiornamenti dello stock scartati, cron che non viene più eseguito;
  • articoli venduti in cassa senza prodotto PrestaShop;
  • differenze trovate dalla riconciliazione notturna.
Centro avvisi con causa, soluzione ed email
Centro avvisi con causa, soluzione ed email

Gli avvisi possono anche essere inviati via email, al massimo uno ogni 6 ore per avviso. Lascia vuoto l’indirizzo per usare quello del negozio. Invia un avviso di prova verifica l’invio.

Email di avviso del connettore cassa con spiegazione e soluzione
Email di avviso del connettore cassa con spiegazione e soluzione

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 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 corrispondere a quella sottoscrizione.

Token rifiutato o permesso mancante

Apri Connessioni, ricollega la cassa con la sua procedura guidata e accetta tutti i permessi elencati.

Lo stock non parte dopo una modifica in back office

PrestaShop non esegue gli hook di un modulo per un dipendente che non ha il permesso «Visualizza» su quel modulo. Nella direzione dal negozio alla cassa, 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 ne indica il motivo: articoli non associati, valuta della vendita non attiva in PrestaShop, prodotto limitato a certi vettori o quantità inferiore a un’unità. In questo caso lo stock è stato gestito direttamente. Correggi la causa per le vendite successive. Il pulsante Crea l’ordine PrestaShop viene proposto solo per una vendita il cui stock non è ancora stato scalato, per non scalarlo mai due volte.

Il totale dell’ordine è diverso dallo scontrino

Verifica che la regola fiscale PrestaShop dei prodotti corrisponda all’aliquota IVA usata in cassa. La differenza viene mostrata sulla vendita.

Disinstallazione

La disinstallazione elimina le tabelle del modulo (associazioni, registro delle vendite, code, registro tecnico, riconciliazioni, avvisi) 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.

Questa pagina ti è stata utile?

Ancora bloccato? Contatta l'assistenza