Installazione passo passo
- Carica il modulo
Nel back office vai su Moduli > Gestione moduli > Carica un modulo e seleziona il pacchetto `zefirox.zip`, poi apri Configura. Per ricevere il pacchetto crea il tuo account.
- Genera la chiave API
Nella dashboard Zefirox apri Impostazioni > Altri CMS e premi Genera chiave API. Copiala subito: non verrà mostrata di nuovo.
- Compila la configurazione
Inserisci Zefirox API URL (l'URL API indicato nella dashboard), Widget script URL (`<URL dashboard>/dms-widget.js`) e API key. Se la chiave è già salvata puoi lasciare il campo vuoto.
- Collega prodotti e combinazioni alle campagne
Nel campo Product → campaign mapping scrivi una riga per prodotto: `id_prodotto=UUID_campagna`, oppure `id_prodotto:id_combinazione=UUID_campagna` per una combinazione (le righe per combinazione hanno la precedenza).
- Pianifica il cron dei ritentativi
La pagina di configurazione mostra un URL `/module/zefirox/cron?token=…`: richiamalo circa ogni 10 minuti con un cron del server o con il modulo Cron tasks manager.
Cosa ottieni su PrestaShop
- Widget nella scheda prodotto (hook `displayProductAdditionalInfo`) che si aggiorna al cambio di combinazione.
- Campagne per prodotto o per singola combinazione.
- Invio degli ordini quando lo stato è segnato come pagato (ad esempio "Pagamento accettato").
- Una richiesta firmata (HMAC SHA-256 con timestamp) per ogni campagna nell'ordine, con chiave di idempotenza.
- Importi nella valuta dell'ordine, tasse incluse, in unità minori.
- Ritentativi automatici (fino a 6) tramite URL cron protetto da token.
Come vengono sincronizzati gli ordini
Quando un ordine passa a uno stato contrassegnato come pagato, il modulo raggruppa le righe per campagna e invia una richiesta firmata per ciascuna. L'esito di ogni invio viene salvato nel database del negozio.
Se la rete o l'API non rispondono, l'invio resta in attesa e viene ritentato dall'URL cron, fino a 6 tentativi. Gli ordini già registrati non vengono duplicati grazie alla chiave di idempotenza.
Sicurezza
La chiave API resta nel back office e serve a firmare ogni richiesta con un timestamp: Zefirox scarta le richieste più vecchie di 5 minuti o con firma non valida.
Domande frequenti
Il modulo è su PrestaShop Addons?
Non ancora: si installa caricando lo zip da Moduli > Gestione moduli > Carica un modulo.
Posso fare una campagna solo su una taglia?
Sì, con una riga `id_prodotto:id_combinazione=UUID_campagna` nel campo di mappatura. Le righe per combinazione prevalgono su quelle per prodotto.
Serve davvero il cron?
Serve per ritentare gli invii falliti, ad esempio per un problema di rete. Senza cron gli ordini inviati correttamente al primo tentativo vengono comunque registrati.