- Automazioni Ficoo Pro
- Indice
- Come funziona
- Prerequisiti
- Configurare le automazioni
- Catalogo delle automazioni disponibili
- Tutti gli eventi Fatture in Cloud
- Impostazioni avanzate
- Domande frequenti e risoluzione problemi
- Ho attivato un'automazione ma non sembra funzionare. Cosa controllo per primo?
- Lo stock non si aggiorna su WooCommerce dopo un cambio su FIC.
- L'ordine WooCommerce non viene completato quando pago la fattura su FIC.
- Quando attivo un'automazione appare un errore. Cosa fare?
- Ho cambiato dominio al sito. Le automazioni continuano a funzionare?
- Posso ricevere notifiche per eventi che non hanno un'automazione predefinita?
Automazioni Ficoo Pro #
La funzionalità Automazioni di Ficoo Pro collega in tempo reale Fatture in Cloud con il tuo negozio WooCommerce tramite i webhook di FIC. Ogni volta che qualcosa cambia su Fatture in Cloud — un prodotto creato, lo stock aggiornato, una fattura pagata, un cliente modificato — Ficoo riceve immediatamente la notifica ed esegue in automatico l’azione configurata su WordPress.
Come funziona #
I webhook sono notifiche automatiche: quando un evento si verifica su Fatture in Cloud, FIC invia una chiamata HTTP al tuo sito WordPress. Ficoo Pro riceve questa chiamata tramite un endpoint REST dedicato e decide quali azioni eseguire in base alla tua configurazione.
Il flusso completo è:
- Attivi un’automazione nel pannello Ficoo (es. “Aggiorna stock in WooCommerce”).
- Ficoo si registra automaticamente su Fatture in Cloud come destinatario degli eventi necessari (es. aggiornamento stock prodotto).
- Quando lo stock cambia su FIC, Fatture in Cloud invia una notifica all’endpoint
/wp-json/ficoo/v1/webhookdel tuo sito. - Ficoo elabora la notifica e aggiorna lo stock del prodotto WooCommerce corrispondente.
[Screenshot: schema del flusso webhook — FIC manda notifica → WordPress riceve → Ficoo esegue l’azione]
Prerequisiti #
- Ficoo Pro installato e attivato
- Connessione API con Fatture in Cloud configurata (verifica in Ficoo → Impostazioni)
- Il sito WordPress deve essere accessibile via HTTPS da internet
- Per le automazioni sui prodotti: i prodotti WooCommerce devono essere collegati ai prodotti FIC tramite FIC ID
- Per le automazioni sulle fatture: gli ordini WooCommerce devono essere collegati alle fatture FIC (questo avviene automaticamente quando Ficoo crea una fattura da un ordine)
Configurare le automazioni #
Vai su Ficoo Pro → Automazioni (o sulla scheda Automazioni all’interno del pannello Ficoo Pro).
Le automazioni sono organizzate in gruppi tematici: Prodotti, Documenti, Clienti. Per ciascuna vedi una card con nome, descrizione e uno switch per attivarla o disattivarla.
[Screenshot: pagina delle automazioni con le card per ogni gruppo]
Attivare un’automazione #
- Individua l’automazione che ti interessa.
- Clicca lo switch a destra della card per portarla in stato Attiva.
- Ficoo si registra su Fatture in Cloud e, dopo qualche secondo, lo stato diventa verde.
- Se l’automazione ha opzioni configurabili, appare una sezione aggiuntiva nella parte inferiore della card. Imposta le opzioni e clicca Salva.
Disattivare un’automazione #
- Clicca lo switch per portarlo su Inattiva.
- Ficoo annulla la registrazione su Fatture in Cloud: d’ora in poi gli eventi di quel tipo non verranno più ricevuti né elaborati.
Catalogo delle automazioni disponibili #
Prodotti #
Crea Prodotto in WooCommerce #
Quando viene creato un nuovo prodotto su Fatture in Cloud, Ficoo crea automaticamente il corrispondente prodotto semplice in WooCommerce, copiando nome, SKU, prezzo e giacenza.
Come funziona nel dettaglio:
- Se esiste già un prodotto WooCommerce con lo stesso SKU, Ficoo non crea un duplicato ma si limita a collegare i due prodotti tramite FIC ID.
- La descrizione breve viene importata dalla nota del prodotto FIC.
- Se il prodotto FIC ha la gestione magazzino attiva, anche il prodotto WooCommerce viene creato con la giacenza impostata.
Opzioni configurabili:
| Opzione | Valori | Descrizione |
|---|---|---|
| Stato prodotto | Bozza / Pubblicato | I nuovi prodotti vengono creati in bozza (da revisionare prima di pubblicare) oppure direttamente pubblicati. |
| Tipo di prezzo | Automatico / Prezzo netto / Prezzo lordo | Quale prezzo importare da FIC. “Automatico” usa la configurazione IVA di WooCommerce per scegliere tra netto e lordo. |
| Categoria | Non assegnare / Abbina o crea da FIC / Solo abbinamento | Come gestire la categoria del prodotto: ignorarla, cercare una categoria WooCommerce con lo stesso nome (o crearla se non esiste), oppure abbinarla solo se già esiste. |
Evento FIC utilizzato: it.fattureincloud.webhooks.products.create
Aggiorna Stock in WooCommerce #
Quando la giacenza di un prodotto cambia su Fatture in Cloud (vendita, rettifica manuale, ecc.), Ficoo aggiorna automaticamente la quantità in stock del corrispondente prodotto WooCommerce.
Come funziona nel dettaglio:
- L’aggiornamento avviene solo se il prodotto WooCommerce è già collegato al prodotto FIC tramite FIC ID.
- Se lo stock su FIC è già uguale a quello su WooCommerce, nessuna modifica viene apportata.
- Ficoo imposta direttamente la quantità (non aggiunge o sottrae): il valore su WooCommerce diventa identico a quello su FIC.
Opzioni configurabili: nessuna.
Evento FIC utilizzato: it.fattureincloud.webhooks.products.stock_update
Documenti #
Completa ordine al pagamento fattura #
Quando tutti i pagamenti (anche rateali) di una fattura su Fatture in Cloud risultano contrassegnati come pagati, Ficoo aggiorna lo stato del corrispondente ordine WooCommerce.
Come funziona nel dettaglio:
- Funziona anche con fatture a rate: l’ordine WooCommerce viene aggiornato solo quando tutte le rate risultano pagate, non alla prima rata.
- Il collegamento tra fattura FIC e ordine WooCommerce avviene automaticamente quando Ficoo crea la fattura dall’ordine.
- Se l’ordine è già nello stato di destinazione, non viene fatto nulla.
Opzioni configurabili:
| Opzione | Valori | Descrizione |
|---|---|---|
| Stato ordine | Tutti gli stati WooCommerce disponibili | Lo stato in cui portare l’ordine WooCommerce quando la fattura risulta completamente pagata. Il valore predefinito è “Completato”. |
Evento FIC utilizzato: it.fattureincloud.webhooks.issued_documents.invoices.update
Clienti #
Crea Clienti #
Quando un nuovo cliente viene aggiunto su Fatture in Cloud, Ficoo crea automaticamente un utente WordPress con ruolo cliente e compila tutti i dati disponibili (nome, cognome, email, indirizzo di fatturazione, dati fiscali).
Come funziona nel dettaglio:
- Il cliente FIC deve avere un indirizzo email valido — senza email la creazione viene saltata.
- Se esiste già un utente WordPress con la stessa email, Ficoo non crea un duplicato ma aggiorna i dati dell’utente esistente e lo collega al cliente FIC.
- Lo username viene derivato dalla parte locale dell’email (prima della @); se è già in uso viene aggiunto un suffisso numerico.
- La password viene generata automaticamente in modo casuale.
Opzioni configurabili: nessuna.
Evento FIC utilizzato: it.fattureincloud.webhooks.entities.clients.create
Aggiorna Clienti #
Quando i dati di un cliente vengono modificati su Fatture in Cloud, Ficoo aggiorna automaticamente il profilo dell’utente WordPress collegato (indirizzo, ragione sociale, dati fiscali, ecc.).
Come funziona nel dettaglio:
- Funziona solo se il cliente FIC è già collegato a un utente WordPress (collegamento creato manualmente dalla scheda clienti o tramite l’automazione “Crea Clienti”).
- Vengono aggiornati i campi di fatturazione WooCommerce e i meta Ficoo (codice fiscale, P.IVA, ecc.).
- Non modifica email, username o password dell’utente WordPress.
Opzioni configurabili: nessuna.
Evento FIC utilizzato: it.fattureincloud.webhooks.entities.clients.update
Tutti gli eventi Fatture in Cloud #
Ficoo si abbona solo agli eventi strettamente necessari per le automazioni attive. Oltre agli eventi usati dalle automazioni predefinite, Fatture in Cloud supporta molti altri tipi di evento. La lista completa degli eventi disponibili è la seguente:
Prodotti #
| Evento | Descrizione |
|---|---|
| Prodotti — Crea | Un nuovo prodotto viene creato su FIC |
| Prodotti — Aggiorna | Un prodotto viene modificato su FIC |
| Prodotti — Elimina | Un prodotto viene eliminato da FIC |
| Prodotti — Aggiornamento Stock | La giacenza di un prodotto cambia su FIC |
Clienti e Fornitori #
| Evento | Descrizione |
|---|---|
| Clienti — Crea / Aggiorna / Elimina | Un cliente viene creato, modificato o eliminato su FIC |
| Fornitori — Crea / Aggiorna / Elimina | Un fornitore viene creato, modificato o eliminato su FIC |
Documenti emessi #
| Tipo documento | Azioni disponibili |
|---|---|
| Fatture | Crea, Aggiorna, Elimina, Email inviata |
| Preventivi | Crea, Aggiorna, Elimina, Email inviata |
| Proforma | Crea, Aggiorna, Elimina, Email inviata |
| Scontrini | Crea, Aggiorna, Elimina, Email inviata |
| DDT (Bolle) | Crea, Aggiorna, Elimina, Email inviata |
| Note di credito | Crea, Aggiorna, Elimina, Email inviata |
| Ordini cliente | Crea, Aggiorna, Elimina, Email inviata |
| Rapporti di lavoro | Crea, Aggiorna, Elimina, Email inviata |
| Ordini fornitore | Crea, Aggiorna, Elimina, Email inviata |
| Autofatture | Crea, Aggiorna, Elimina, Email inviata |
Altri eventi #
| Evento | Descrizione |
|---|---|
| Documenti ricevuti — Crea / Aggiorna / Elimina | Documenti in entrata (es. fatture fornitori) |
| Fatturazione Elettronica — Cambio stato SDI | La fattura elettronica cambia stato sul Sistema di Interscambio |
| Fatturazione Elettronica — Ricezione | Ricezione di una nuova fattura elettronica da SDI |
| Prima nota — Crea / Aggiorna / Elimina | Movimenti di prima nota |
| Tributi — Crea / Aggiorna / Elimina | Voci tributi |
| Archivio — Crea / Aggiorna / Elimina | Documenti archiviati |
ficoo_webhook_automation_catalog e il hook ficoo_pro_webhook_received.
Impostazioni avanzate #
Nella parte inferiore della pagina Automazioni trovi una sezione Impostazioni Avanzate (collassabile), utile per gestione e risoluzione problemi.
URL di Callback #
L’URL di callback è l’indirizzo a cui Fatture in Cloud invia le notifiche webhook. Di default corrisponde a:
https://il-tuo-sito.com/wp-json/ficoo/v1/webhookSe stai sviluppando in locale o hai bisogno di un URL diverso, puoi sovrascriverlo:
- Inserisci il nuovo URL nel campo di testo (es. l’URL del tunnel ngrok).
- Clicca Salva. La pagina si ricaricherà automaticamente.
- Per tornare all’URL predefinito, clicca Cancella.
https://, compare un avviso in cima alla pagina e le automazioni non funzioneranno. Fatture in Cloud richiede un endpoint HTTPS valido.
Sottoscrizioni #
In questa sezione puoi vedere quante sottoscrizioni webhook sono attive su Fatture in Cloud e gestirle in caso di problemi.
| Azione | Descrizione |
|---|---|
| Sincronizza da Fatture in Cloud | Scarica da FIC l’elenco aggiornato delle sottoscrizioni attive e allinea il database locale. Utile se hai modificato le sottoscrizioni direttamente dal pannello FIC o se le automazioni sembrano non rispondere. |
| Annulla tutte le sottoscrizioni | Rimuove tutte le sottoscrizioni webhook da Fatture in Cloud e svuota il database locale. Equivale a disattivare tutte le automazioni contemporaneamente. Utile in caso di migrazione sito o problemi gravi. |
Cliccando su Mostra sottoscrizioni attive ottieni l’elenco degli eventi registrati con il relativo stato (Verificato oppure In attesa).
Domande frequenti e risoluzione problemi #
Ho attivato un’automazione ma non sembra funzionare. Cosa controllo per primo? #
- Verifica che il sito sia raggiungibile via HTTPS. L’avviso rosso in cima alla pagina indica che l’URL non è sicuro.
- Controlla che la sottoscrizione sia nello stato “Verificato” (sezione Impostazioni Avanzate → Mostra sottoscrizioni attive). Se appare “In attesa”, prova a disattivare e riattivare l’automazione.
- Prova a fare l’azione su Fatture in Cloud e attendi qualche secondo. I webhook non sono istantanei: FIC impiega di solito da pochi secondi a un minuto.
- Controlla i log PHP del server per messaggi che iniziano con
[FICOO][WEBHOOK]— ti diranno se il webhook è stato ricevuto e cosa è successo durante l’elaborazione.
Lo stock non si aggiorna su WooCommerce dopo un cambio su FIC. #
Questo avviene quasi sempre per uno di questi motivi:
- Il prodotto WooCommerce non ha un FIC ID assegnato. Verifica nella scheda Magazzino.
- Il prodotto WooCommerce non ha la gestione magazzino attivata nella scheda Inventario.
- L’automazione “Aggiorna Stock” è attiva ma la sottoscrizione non è verificata su FIC. Prova a disattivarla e riabilitarla.
L’ordine WooCommerce non viene completato quando pago la fattura su FIC. #
- Controlla che l’ordine sia collegato alla fattura FIC. Il collegamento avviene automaticamente solo se la fattura è stata creata da Ficoo a partire dall’ordine.
- Verifica che tutti i pagamenti della fattura siano contrassegnati come pagati su FIC, non solo il primo.
- L’automazione reagisce all’evento “Fattura — Aggiornamento”. Assicurati che la sottoscrizione a questo evento sia verificata.
Quando attivo un’automazione appare un errore. Cosa fare? #
Il messaggio di errore compare sulla card dell’automazione. I problemi più comuni sono:
- Credenziali API non valide o scadute — rigenera il token in Fatture in Cloud e aggiornalo nelle impostazioni Ficoo.
- Piano FIC che non supporta i webhook — verifica che il tuo abbonamento Fatture in Cloud includa le API avanzate.
- URL di callback non raggiungibile da FIC (sito in manutenzione, firewall, ecc.).
Ho cambiato dominio al sito. Le automazioni continuano a funzionare? #
No: le sottoscrizioni esistenti puntano al vecchio dominio. Dopo la migrazione:
- Vai in Impostazioni Avanzate e clicca Annulla tutte le sottoscrizioni.
- Disattiva e riattiva ogni automazione che ti serve per registrare le sottoscrizioni sul nuovo URL.
Posso ricevere notifiche per eventi che non hanno un’automazione predefinita? #
Sì. Ficoo espone il hook WordPress ficoo_pro_webhook_received che viene eseguito per ogni evento ricevuto da FIC, indipendentemente dalle automazioni attive. Gli sviluppatori possono agganciarvisi tramite add_action nel file functions.php del tema o in un plugin personalizzato per eseguire logiche personalizzate.
