Connettore Axonaut PrestaShop — Documentazione
Installa e configura il connettore Axonaut per PrestaShop: chiave API, sincronizzazione clienti, fatture/preventivi, prodotti, cron e risoluzione dei problemi.
Il modulo Connettore Axonaut PrestaShop (dfaxonaut, di DataFirefly) sincronizza automaticamente clienti, ordini e prodotti tra PrestaShop e Axonaut, il software di gestione francese (CRM, fatturazione, preventivi, tesoreria). Questa guida copre installazione, configurazione, funzionamento delle sincronizzazioni e risoluzione dei problemi.
Requisiti
- PrestaShop 8.x o 9.x, PHP 7.4 fino a 8.3.
- Un account Axonaut attivo con accesso all’API v2.
- La tua chiave API Axonaut (userApiKey), disponibile in Axonaut in Impostazioni > Sviluppatori > Chiave API.
Installazione
- Nel back-office di PrestaShop, apri Moduli > Gestore moduli > Carica un modulo e trascina il file ZIP del modulo.
- Una volta installato, clicca su Configura.
- Sotto Parametri avanzati compare anche una nuova scheda Axonaut Connector: dà accesso alla dashboard e ai log.
Il modulo non installa alcuna dipendenza Composer al deploy: l’autoloader PSR-4 è integrato. Non serve nient’altro lato server.
Configurazione
Chiave API e test di connessione
Incolla la tua chiave API Axonaut nel campo Chiave API Axonaut e salva. Poi vai nella dashboard (Parametri avanzati > Axonaut Connector) e clicca su Testa connessione: il modulo interroga l’endpoint /me di Axonaut e mostra l’account associato se tutto è corretto.
Sincronizzazione dei clienti
Attiva Sincronizza clienti affinché ogni creazione di account, aggiornamento dell’account o modifica dell’indirizzo crei o aggiorni un’azienda Axonaut insieme al suo contatto. Il modulo rileva automaticamente i professionisti (ragione sociale o partita IVA intracomunitaria indicata) e i privati (B2C), e trasmette l’indirizzo, la partita IVA intracomunitaria e il numero azienda quando disponibili.
Sincronizzazione degli ordini
Attiva Sincronizza ordini, poi scegli:
- Modalità: creare una fattura o un preventivo Axonaut.
- Stati attivatori: l’ordine viene inviato la prima volta che raggiunge uno degli stati selezionati (ad esempio «Pagamento accettato»).
- Prezzi IVA inclusa: inviare i prezzi unitari IVA inclusa anziché IVA esclusa.
Ogni ordine inviato riporta le righe prodotto (riferimento, aliquota IVA, quantità) e aggiunge le spese di spedizione in una riga dedicata. Un ordine già inviato non viene mai duplicato.
Sincronizzazione dei prodotti (opzionale)
Attiva Sincronizza prodotti per rispecchiare il tuo catalogo (riferimento, nome, prezzo, IVA, descrizione breve) nei prodotti Axonaut. La sincronizzazione si attiva a ogni aggiornamento di una scheda prodotto.
Attività cron
Le sincronizzazioni vengono messe in coda ed elaborate in background. Un leggero tentativo inline viene eseguito al volo all’interno degli hook, ma per un funzionamento affidabile pianifica l’attività cron mostrata nella configurazione:
curl -s "https://il-tuo-negozio.tld/index.php?fc=module&module=dfaxonaut&controller=cron&token=IL_TUO_TOKEN"Frequenza consigliata: ogni 5-15 minuti. Il cron elabora la coda, ripulisce gli elementi completati (7 giorni) e i log vecchi (30 giorni). Il token può essere rigenerato dalla pagina di configurazione.
Se rigeneri il token, ricordati di aggiornare l’URL nel tuo pianificatore (cron del server, attività PrestaShop o servizio esterno).
Dashboard e log
La scheda Axonaut Connector mostra i contatori (in attesa / sincronizzati / falliti) e il log completo delle operazioni, filtrabile ed esportabile. Sono disponibili due azioni:
- Elabora la coda ora: forza l’elaborazione immediata degli elementi in attesa.
- Riprova i falliti: rimette in coda gli elementi falliti dopo 5 tentativi.
Come funzionano la coda e i retry
Ogni entità da sincronizzare (cliente, ordine, prodotto) viene messa in una coda. In caso di errore temporaneo (rete, quota API), il modulo riprova automaticamente fino a 5 volte, poi segna l’elemento come fallito. Gli errori vengono registrati con il loro messaggio, il che facilita la diagnosi. La modalità debug aggiunge ai log i payload e le risposte completi dell’API.
Risoluzione dei problemi
- «Chiave API vuota»: inserisci la chiave nella configurazione prima di testare la connessione.
- Errore HTTP 401/403: la chiave API non è valida o è stata revocata. Rigenerala in Axonaut.
- Ordini non inviati: verifica che lo stato raggiunto sia tra gli stati attivatori e che la sincronizzazione degli ordini sia attiva.
- Elementi falliti: apri il log per leggere il messaggio di errore, correggi la causa, poi clicca su Riprova i falliti.
- Nulla si sincronizza in background: verifica che l’attività cron sia pianificata e che il token dell’URL corrisponda a quello della configurazione.
Note tecniche
- API utilizzata: Axonaut REST API v2, autenticazione tramite l’header userApiKey.
- Endpoint: /me, /companies, /companies/{id}/employees, /employees/{id}, /products, /invoices, /quotations.
- Tabelle create: dfaxonaut_map (corrispondenze PrestaShop ↔ Axonaut), dfaxonaut_queue (coda), dfaxonaut_log (log).
- Compatibile con il multistore di PrestaShop.