Ritiro in negozio (Store Pickup) — Guida completa

Presentazione

Il modulo Ritiro in negozio (datafireflystorepickup) consente ai tuoi clienti di ritirare il proprio ordine in uno dei tuoi punti vendita anziché farselo consegnare. Durante l’installazione viene creato automaticamente un corriere «Ritiro in negozio». Al checkout, quando il cliente sceglie questo corriere, compaiono un elenco di negozi e una mappa interattiva: seleziona il proprio punto di ritiro e tale scelta viene salvata con l’ordine.

La mappa si basa su Leaflet e OpenStreetMap, senza alcuna chiave API. Il modulo è compatibile con PrestaShop 8.x e 9.x e si appoggia esclusivamente agli hook nativi, senza override del core.

Installazione

1. Comprimi in ZIP la cartella datafireflystorepickup (l’archivio deve contenere la cartella stessa, non solo il suo contenuto).
2. Dal back office, apri Moduli > Gestore dei moduli, fai clic su Carica un modulo e rilascia l’archivio ZIP.
3. Al termine dell’installazione, fai clic su Configura.

All’installazione, il modulo esegue automaticamente le seguenti operazioni: crea il corriere «Ritiro in negozio» (con le sue fasce di prezzo e peso, tutte le zone e tutti i gruppi clienti), crea le tabelle dati, registra gli hook e inizializza le spese di ritiro a 0.

Configurazione

Vai su Moduli > Ritiro in negozio > Configura. La pagina riunisce le impostazioni generali e la gestione dei negozi.

Spese di ritiro

Il campo Spese di ritiro (IVA esclusa) definisce il costo applicato al corriere di ritiro. Lascia 0 per un ritiro gratuito oppure inserisci un importo al netto delle imposte. Questa tariffa si applica indipendentemente dal negozio scelto.

Gestione dei negozi

L’elenco dei negozi mostra tutti i tuoi punti di ritiro con nome, indirizzo, CAP, città, telefono e stato. Da questo elenco puoi aggiungere, modificare, attivare/disattivare o eliminare un negozio.

Ogni negozio dispone dei seguenti campi:

• Nome (obbligatorio) — etichetta mostrata al cliente.
• Indirizzo (obbligatorio) e CAP.
• Città (obbligatorio).
• Telefono.
• Orari — campo di testo libero, es. «Lun-Sab 9-19».
• Latitudine e Longitudine (obbligatori) — la posizione del negozio sulla mappa.
• Attivo — solo i negozi attivi vengono proposti al checkout.

Lato cliente (checkout)

Nella fase di consegna, quando il cliente seleziona il corriere «Ritiro in negozio», il modulo mostra sotto il corriere l’elenco dei negozi attivi insieme a una mappa interattiva in cui ogni negozio è rappresentato da un marcatore. Il cliente sceglie il proprio punto di ritiro dall’elenco o direttamente sulla mappa.

La selezione è obbligatoria: finché non viene scelto un negozio, la fase di consegna non può essere convalidata e un messaggio invita il cliente a selezionare il proprio negozio. La scelta viene salvata in tempo reale (tramite una richiesta AJAX) e collegata al carrello.

Monitoraggio dell’ordine

Una volta confermato l’ordine, il negozio scelto viene salvato come istantanea collegata all’ordine (nome, indirizzo, CAP, città, telefono e orari al momento dell’acquisto). Rimane quindi consultabile anche se il negozio viene modificato o eliminato in seguito. Il punto di ritiro viene visualizzato automaticamente:

• nella pagina di conferma dell’ordine;
• nel dettaglio dell’ordine dell’area cliente;
• nella scheda ordine del back office, nella colonna laterale.

Struttura tecnica

Questa sezione è rivolta a integratori e sviluppatori che desiderano comprendere il funzionamento interno del modulo.

Tipo di modulo

La classe principale DataFireflyStorePickup estende CarrierModule. La tariffa del corriere è restituita da getOrderShippingCost() e getOrderShippingCostExternal(), entrambe basate sulla configurazione DATAFIREFLY_PICKUP_FEE.

Hook utilizzati

• actionFrontControllerSetMedia — carica Leaflet (CSS/JS remoti) e gli asset front del modulo nella pagina dell’ordine.
• displayCarrierExtraContent — inietta l’elenco e la mappa sotto il corriere di ritiro.
• actionCarrierUpdate — aggiorna l’identificatore del corriere quando viene modificato nel back office.
• actionValidateStepComplete — rende obbligatoria la selezione del negozio nella fase di consegna.
• actionValidateOrder — congela il negozio scelto nell’ordine.
• displayOrderConfirmation e displayOrderDetail — mostrano il punto di ritiro lato cliente.
• displayAdminOrderSide — mostra il punto di ritiro nella scheda ordine del back office.

Riconoscimento del corriere

Il metodo isPickupCarrier() identifica il corriere di ritiro tramite il suo riferimento (id_reference) oltre che tramite il suo identificatore corrente, poiché l’ID di un corriere PrestaShop cambia a ogni modifica nel back office. A tal fine vengono memorizzate due chiavi di configurazione: DATAFIREFLY_PICKUP_CARRIER_ID e DATAFIREFLY_PICKUP_CARRIER_REF.

Tabelle dati

• datafirefly_pickup_store — i negozi (nome, indirizzo, coordinate, orari, stato). Gestita dall’ObjectModel DataFireflyPickupStore.
• datafirefly_pickup_selection — il negozio scelto per carrello (chiave id_cart), prima della convalida dell’ordine.
• datafirefly_pickup_order — l’istantanea del negozio per ordine (chiave id_order), conservata dopo l’acquisto.

Selezione AJAX

Il controller front ajax (azione selectStore) salva il negozio selezionato in datafirefly_pickup_selection per il carrello corrente. Alla convalida dell’ordine, questa selezione viene copiata in datafirefly_pickup_order e poi la riga del carrello viene eliminata.

Disinstallazione

La disinstallazione del modulo contrassegna il corriere come eliminato e disattivato, rimuove le chiavi di configurazione (DATAFIREFLY_PICKUP_CARRIER_ID, DATAFIREFLY_PICKUP_CARRIER_REF, DATAFIREFLY_PICKUP_FEE) ed elimina le tre tabelle del modulo. I negozi salvati vengono quindi cancellati.

Limitazioni note

• Il punto di ritiro non viene iniettato nelle email di conferma: rimane visibile nel back office e nell’area cliente.
• La geocodifica si basa su Nominatim (OpenStreetMap) — si consiglia un uso moderato per rispettare le condizioni d’uso del servizio.

FAQ

È necessaria una chiave API per la mappa?

No. La mappa utilizza Leaflet e le tile di OpenStreetMap, senza chiave API né configurazione esterna.

Il cliente può convalidare il proprio ordine senza scegliere un negozio?

No. Quando è selezionato il corriere di ritiro, la scelta di un negozio è obbligatoria per superare la fase di consegna.

Cosa succede al punto di ritiro se elimino un negozio dopo un ordine?

L’ordine conserva un’istantanea del negozio (nome, indirizzo, orari…) salvata al momento dell’acquisto. Rimane consultabile anche dopo l’eliminazione del negozio.

Il modulo è compatibile con PrestaShop 9?

Sì, il modulo è compatibile con PrestaShop 8.x e 9.x.