# Connettore Axonaut per WooCommerce — Documentazione

> 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…

- Pagina: <https://www.datafirefly.com/it/documentation/axonaut-connector-woocommerce/>
- Lingua: it
- Aggiornato il: 2026-07-08
- Altre lingue: [fr](https://www.datafirefly.com/documentation/axonaut-connector-woocommerce/index.md), [en](https://www.datafirefly.com/en/documentation/axonaut-connector-woocommerce/index.md), [es](https://www.datafirefly.com/es/documentation/axonaut-connector-woocommerce/index.md), [de](https://www.datafirefly.com/de/documentation/axonaut-connector-woocommerce/index.md), [pl](https://www.datafirefly.com/pl/documentation/axonaut-connector-woocommerce/index.md), [nl](https://www.datafirefly.com/nl/documentation/axonaut-connector-woocommerce/index.md), [pt](https://www.datafirefly.com/pt/documentation/axonaut-connector-woocommerce/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

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

1. Nell'amministrazione di WordPress, vai su _Plugin > Aggiungi nuovo > Carica plugin_.
2. Seleziona il file ZIP del plugin e fai clic su _Installa ora_.
3. Attiva il plugin.
4. 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:

1. risolve o crea l'azienda Axonaut corrispondente;
2. costruisce il documento riga per riga, con l'aliquota IVA calcolata per ogni riga;
3. aggiunge le spese di spedizione e le eventuali commissioni come righe dedicate;
4. trasmette la data di pagamento se l'ordine è già pagato;
5. 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.

1. Scegli un intervallo di date (facoltativo) e gli stati dell'ordine da includere.
2. Fai clic su _Avvia importazione_.
3. 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.