Connettore Axonaut per WooCommerce — Documentazione
Installare, connettere e configurare il Connettore Axonaut per WooCommerce: fatture o preventivi, aziende e contatti, note di credito, importazione dello storico.
Il Connettore Axonaut per WooCommerce collega il tuo negozio WooCommerce all’ERP/CRM francese Axonaut. Invia automaticamente i tuoi ordini ad Axonaut come fatture o preventivi, crea le aziende e i contatti corrispondenti, genera note di credito sui rimborsi e ti permette di importare il tuo storico. Tutta l’elaborazione avviene in background tramite Action Scheduler, senza impatto sul checkout, ed è idempotente: un ordine non viene mai sincronizzato due volte.
Requisiti
- WordPress 6.0 o superiore
- WooCommerce 7.0 o superiore
- PHP 7.4 o superiore
- Un account Axonaut attivo e la sua chiave API
Il plugin non richiede alcuna dipendenza da Composer sul tuo server ed è compatibile con l’archiviazione ordini ad alte prestazioni (HPOS) e con l’archiviazione classica.
Installazione
- Nell’amministrazione di WordPress, vai su Plugin > Aggiungi nuovo > Carica plugin.
- Seleziona il file ZIP del plugin e fai clic su Installa ora.
- Attiva il plugin.
- Nell’amministrazione compare un nuovo menu WooCommerce > Axonaut.
Connessione ad Axonaut
Vai su WooCommerce > Axonaut, scheda Impostazioni.
Recuperare la chiave API
Nel tuo account Axonaut, apri la sezione Impostazioni e poi Sviluppatori. Copia la tua chiave API personale.
Inserire e testare la chiave
Incolla la chiave nel campo Chiave API Axonaut e fai clic su Testa connessione. Un messaggio verde conferma che la connessione è stabilita; un messaggio rosso indica una chiave non valida o un problema di rete.
La chiave è memorizzata in modo sicuro e non viene mai mostrata in chiaro una volta salvata. Il test di connessione utilizza la chiave inserita nel campo, anche prima del salvataggio.
Configurazione
Tipo di documento
Scegli il documento creato in Axonaut a partire da un ordine: Fattura o Preventivo. Questa scelta si applica a tutti gli ordini sincronizzati.
Stati di attivazione
Seleziona gli stati dell’ordine che attivano l’invio ad Axonaut (ad esempio Completato). Non appena un ordine raggiunge uno di questi stati, viene messo in coda per la sincronizzazione. Ogni ordine viene inviato una sola volta, anche se cambia stato più volte.
Contatti
Attiva questa opzione affinché l’acquirente venga creato come contatto (employee) collegato all’azienda in Axonaut. L’azienda viene sempre creata: Axonaut ne ha bisogno per collegare fatture e preventivi.
Rimborsi
Attiva questa opzione affinché un rimborso WooCommerce generi automaticamente una nota di credito in Axonaut. Si applica solo agli ordini già sincronizzati come fatture.
Data di pagamento
Quando è attivata, la data di pagamento viene trasmessa ad Axonaut per gli ordini già pagati.
Prodotti
Opzionale: sincronizza i tuoi prodotti WooCommerce con il catalogo Axonaut alla creazione o all’aggiornamento.
Manutenzione
Definisci il periodo di conservazione del registro (in giorni) e attiva la modalità debug per registrare le risposte complete dell’API in caso di diagnostica.
Sincronizzazione degli ordini
Quando un ordine raggiunge uno stato di attivazione, il connettore:
- risolve o crea l’azienda Axonaut corrispondente;
- costruisce il documento riga per riga, con l’aliquota IVA calcolata per ogni riga;
- aggiunge le spese di spedizione e le eventuali commissioni come righe dedicate;
- trasmette la data di pagamento se l’ordine è già pagato;
- crea la fattura o il preventivo in Axonaut e memorizza il suo identificativo sull’ordine.
L’elaborazione è asincrona (Action Scheduler): non allunga il tempo di pagamento. In caso di errore temporaneo dell’API (429 o 5xx), l’invio viene ritentato automaticamente con un ritardo crescente, fino a cinque volte.
Aziende, contatti e IVA intracomunitaria
L’azienda Axonaut viene creata a partire dai dati di fatturazione. Il connettore distingue automaticamente i clienti professionali (campo azienda compilato) dai privati e mappa il numero di IVA intracomunitaria rilevato dai principali plugin IVA UE.
Deduplicazione
Prima di qualsiasi chiamata all’API, il connettore cerca un’azienda già risolta: prima sull’ordine stesso, poi sull’account cliente (se presente), poi su un ordine precedente con la stessa e-mail di fatturazione. Gli acquirenti ricorrenti, anche in acquisto come ospite, vengono riconosciuti senza creare un duplicato.
Note di credito e rimborsi
Un rimborso WooCommerce, totale o parziale, su un ordine già sincronizzato come fattura, genera automaticamente una nota di credito in Axonaut, collegata alla fattura originale.
- I rimborsi per riga vengono riportati riga per riga, con l’IVA ricalcolata.
- I rimborsi per importo producono un’unica riga di nota di credito globale.
- Le spese di spedizione rimborsate vengono aggiunte come riga dedicata.
Ogni nota di credito è idempotente: uno stesso rimborso non genera mai due note di credito.
Importazione dello storico
La scheda Importazione permette di inviare i tuoi ordini esistenti ad Axonaut.
- Scegli un intervallo di date (facoltativo) e gli stati dell’ordine da includere.
- Fai clic su Avvia importazione.
- Gli ordini vengono scorsi a lotti in background tramite Action Scheduler; gli ordini già sincronizzati vengono ignorati automaticamente.
Segui l’avanzamento nella scheda Registro.
Azione in blocco nella lista degli ordini
Dalla lista degli ordini (schermata HPOS o schermata classica), seleziona uno o più ordini e scegli l’azione in blocco Sincronizza con Axonaut. Un messaggio indica quanti ordini sono stati messi in coda e quanti sono stati ignorati perché già sincronizzati.
Meta box e risincronizzazione manuale
Nella schermata di modifica di un ordine, il box Axonaut mostra lo stato di sincronizzazione: tipo e numero del documento creato, azienda collegata e data. Se l’ordine non è ancora sincronizzato, un pulsante Sincronizza ora permette un invio immediato, mostrando l’ultimo errore se presente.
Registro attività e modalità debug
La scheda Registro mostra le ultime operazioni (creazioni di aziende, fatture, note di credito, errori), con un collegamento diretto all’ordine interessato. Il periodo di conservazione è configurabile. La modalità debug aggiunge al registro il dettaglio completo delle risposte dell’API, utile per diagnosticare un problema.
Sincronizzazione dei prodotti (opzionale)
Quando l’opzione è attivata, ogni creazione o aggiornamento di prodotto WooCommerce viene riportato nel catalogo Axonaut (nome, riferimento SKU, prezzo IVA esclusa, aliquota IVA). La corrispondenza viene memorizzata per aggiornare il prodotto Axonaut corretto nelle modifiche successive.
Compatibilità HPOS
Il plugin dichiara la compatibilità con l’archiviazione ordini ad alte prestazioni (HPOS). Tutti i metadati di sincronizzazione vengono salvati tramite l’API degli ordini di WooCommerce, il che garantisce un funzionamento identico con l’archiviazione classica e con HPOS.
Hook per sviluppatori
Il connettore espone diversi punti di estensione per adattare i dati inviati ad Axonaut:
df_axonaut_company_payload— filtra i dati dell’azienda prima della creazione.df_axonaut_employee_payload— filtra i dati del contatto prima della creazione.df_axonaut_document_payload— filtra i dati della fattura o del preventivo.df_axonaut_credit_note_payload— filtra i dati della nota di credito.df_axonaut_product_payload— filtra i dati del prodotto sincronizzato.df_axonaut_vat_meta_keys— personalizza le chiavi meta in cui cercare il numero di IVA.df_axonaut_order_synced— azione attivata dopo la sincronizzazione riuscita di un ordine.df_axonaut_refund_synced— azione attivata dopo la creazione di una nota di credito.
Risoluzione dei problemi
Il test di connessione fallisce
Verifica che la chiave API sia corretta e attiva nel tuo account Axonaut e che il tuo server possa raggiungere l’API Axonaut in uscita HTTPS.
Un ordine non viene sincronizzato
Assicurati che il suo stato figuri tra gli stati di attivazione e che non sia già stato sincronizzato. Consulta il registro e il box Axonaut dell’ordine per l’ultimo errore. Verifica inoltre che la coda di Action Scheduler sia in esecuzione (WooCommerce > Stato > Azioni pianificate).
Una nota di credito non è stata creata
Le note di credito vengono generate solo per gli ordini già sincronizzati come fattura (non preventivo) e quando l’opzione dei rimborsi è attivata.
Non modificare manualmente l’identificativo del documento Axonaut memorizzato su un ordine: è ciò che garantisce che un ordine non venga mai inviato due volte.