# Real Profit Dashboard — Guida completa

> Real Profit Dashboard calcola la redditività reale del tuo negozio WooCommerce, ordine per ordine. Questa guida copre l'installazione, la configurazione dei costi (COGS, commissioni di pagamento, spedizione), il collegamento delle…

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

Real Profit Dashboard calcola la redditività reale del tuo negozio WooCommerce, ordine per ordine. Questa guida copre l'installazione, la configurazione dei costi (COGS, commissioni di pagamento, spedizione), il collegamento delle tre integrazioni pubblicitarie (Meta, Google, TikTok), l'utilizzo del cruscotto e la manutenzione corrente.

## Requisiti

- WordPress 6.2 o successivo
- WooCommerce 8.0 o successivo (compatibile HPOS e Cart & Checkout Blocks)
- PHP 8.0 o successivo
- Accesso amministratore al back-office WordPress
- Credenziali API per Meta Ads, Google Ads e/o TikTok Ads se vuoi attivare l'import automatico della spesa pubblicitaria (facoltativo)

## Installazione

1. Vai in **Plugin → Aggiungi nuovo → Carica plugin**.
2. Seleziona il file `dfrealprofit.zip` e clicca su **Installa**.
3. Attiva il plugin.
4. Un nuovo menu principale **Profit Dashboard** appare nella barra laterale, sotto WooCommerce.

All'attivazione, il plugin crea tre tabelle (`wp_dfrp_ad_spend`, `wp_dfrp_order_metrics`, `wp_dfrp_sync_log`) e programma due task CRON orari: sincronizzazione della spesa pubblicitaria e ricalcolo mobile degli ultimi 14 giorni.

## Primi passi

### Inserire il costo di acquisto (COGS) sui tuoi prodotti

Il COGS (Cost of Goods Sold, costo delle merci vendute) è il pilastro del calcolo del margine. Senza di esso, il profitto mostrato è sovrastimato.

- **Prodotto semplice:** apri la scheda del prodotto, tab **Generale**, compila il campo _Costo di acquisto_ con l'importo IVA esclusa pagato al fornitore.
- **Prodotto variabile:** ogni variazione ha il suo campo _Costo di acquisto_. È indispensabile compilarlo variazione per variazione se i costi differiscono (taglie, colori, materiali).
- **In blocco:** il campo è scrivibile anche via API REST WooCommerce (`PUT /wp-json/wc/v3/products/{id}`, meta `_dfrp_cogs`), il che permette un import massivo da un ERP.

Una colonna _COGS_ appare nell'elenco prodotti per identificare rapidamente quelli non ancora configurati.

### Configurare le commissioni di pagamento

Vai in **Profit Dashboard → Impostazioni → Commissioni di pagamento**.

- **Stripe, WooCommerce PayPal Payments, Mollie:** nessuna configurazione. Il plugin legge le commissioni reali direttamente dalle meta dell'ordine (`_stripe_fee`, `_ppcp_paypal_fees`, `_mollie_fee`).
- **Altri gateway:** inserisci lo schema percentuale + fisso applicabile. Ad esempio per un bonifico gratuito: 0 % / 0 €. Per un assegno con commissioni bancarie: 0 % / 0,15 €. Questi valori predefiniti vengono utilizzati se nessuna meta di commissione reale viene trovata sull'ordine.

### Configurare i costi di spedizione

Vai in **Profit Dashboard → Impostazioni → Costi di spedizione predefiniti**. La tabella elenca automaticamente tutti i metodi di spedizione delle tue zone WooCommerce.

Per ogni metodo, inserisci il costo reale medio pagato al corriere (al netto del margine che aggiungi al cliente). Ad esempio, se fatturi 6,90 € una spedizione BRT che ti costa 4,50 €, inserisci **4,50**.

Questi valori sono valori predefiniti. Puoi sempre sovrascrivere il costo reale ordine per ordine (metabox laterale della scheda ordine) se una spedizione specifica ti è costata di più o di meno.

## Integrazioni pubblicitarie

Ogni integrazione è indipendente. Puoi attivarne solo una, due o tutte e tre. Tutte si configurano in **Profit Dashboard → Impostazioni**.

### Meta Ads (Facebook + Instagram)

1. Crea un'applicazione in [Meta for Developers](https://developers.facebook.com/) o utilizzane una esistente.
2. Genera un **access token long-lived** con lo scope `ads_read`. La documentazione ufficiale è disponibile in _Marketing API → Get Started_.
3. Recupera il tuo **Ad Account ID** da _Meta Business Manager → Impostazioni → Account pubblicitari_ (formato numerico, senza il prefisso `act_`).
4. Nelle impostazioni del plugin, spunta **Attiva Meta Ads**, incolla l'access token e l'Ad Account ID.
5. Salva e clicca su **Sincronizza Ads adesso** dal cruscotto per validare la connessione.

### Google Ads

Google Ads usa OAuth 2. Ti servono cinque credenziali.

1. **Developer token:** richiedilo dal tuo account Google Ads Manager (MCC), sezione _Strumenti e impostazioni → Configurazione → Centro API_.
2. **Customer ID:** l'ID a 10 cifre dell'account pubblicitario che vuoi seguire (senza trattini).
3. **OAuth client ID** e **client secret:** crea un progetto in [Google Cloud Console](https://console.cloud.google.com/), attiva l'API Google Ads, crea un client OAuth 2 di tipo _Applicazione desktop_.
4. **Refresh token:** ottienilo una volta tramite il flusso OAuth (vedi documentazione Google Ads API v18). Non cambia mai.

Il plugin scambia automaticamente il refresh token con un access token a ogni sincronizzazione e mette in cache quest'ultimo per la sua durata di validità (un'ora). Non devi fare nulla una volta inserite le credenziali.

### TikTok Ads

1. Crea un'applicazione in [TikTok Business Developers](https://business-api.tiktok.com/portal/).
2. Autorizzala sul tuo account pubblicitario per ottenere un **access token**.
3. Recupera l'**Advertiser ID** in TikTok Ads Manager (menu account, in alto a destra).
4. Nelle impostazioni del plugin, spunta **Attiva TikTok Ads**, incolla l'access token e l'Advertiser ID.

## Attribuzione multi-touch

Non appena il plugin è attivo, due cookie vengono impostati su ogni visitatore: `dfrp_ft` (first-touch, primo canale conosciuto) e `dfrp_lt` (last-touch, canale più recente). Entrambi vivono 90 giorni.

A ogni visita, il plugin cattura i seguenti parametri dall'URL:

- UTM standard: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
- Identificatori di clic: `fbclid` (Facebook), `gclid` (Google), `ttclid` (TikTok)

Al momento della creazione dell'ordine, entrambi i cookie vengono fissati nelle meta dell'ordine (`_dfrp_utm_ft`, `_dfrp_utm_lt`). Il canale normalizzato viene poi derivato dal last-touch (con fallback sul first-touch) e classificato in una di queste nove categorie: _Facebook, Instagram, Google, TikTok, Email, Organic, Direct, Referral, Other_.

### Allocazione della spesa pubblicitaria

Due modalità disponibili nelle impostazioni:

- **Per ordine** (predefinita): la spesa giornaliera totale di un canale viene divisa per il numero di ordini attribuiti a quel canale quel giorno. Ogni ordine riceve una quota uguale.
- **In proporzione al fatturato**: la spesa viene distribuita proporzionalmente al peso di ciascun ordine sul fatturato giornaliero del canale. Un ordine da 300 € riceve tre volte più costo pubblicitario di uno da 100 €.

## Utilizzo del cruscotto

Il cruscotto principale è accessibile da **Profit Dashboard → Cruscotto**.

### KPI principali

Sette indicatori sono mostrati in cima alla pagina, per l'intervallo selezionato:

- **Fatturato**: fatturato netto (IVA esclusa secondo impostazione, rimborsi esclusi)
- **COGS**: somma dei costi di acquisto delle righe vendute
- **Commissioni di pagamento**: totale delle commissioni dei gateway
- **Spedizione**: totale dei costi reali di spedizione
- **Pubblicità**: totale della spesa pubblicitaria allocata
- **Profitto netto**: Fatturato − COGS − Commissioni − Spedizione − Pubblicità − Altri costi
- **Margine**: profitto netto / fatturato in percentuale

### Grafico e canali

Sotto i KPI, un grafico a barre mostra il profitto giornaliero dell'intervallo (barre verdi per profitto positivo, rosse per perdite).

Il blocco **Performance per canale** aggrega gli ordini per canale normalizzato con, per ciascuno: numero di ordini, fatturato, spesa pubblicitaria, ROAS (Return On Ad Spend = fatturato / spesa pubblicitaria), profitto netto e margine.

### Filtri e intervalli di date

Sette intervalli predefiniti: Oggi, 7 giorni, 30 giorni, 90 giorni, Mese in corso, Anno in corso, Intervallo personalizzato. Gli intervalli sono relativi al giorno corrente e si aggiornano automaticamente a ogni caricamento della pagina.

## Metabox nella scheda ordine

Ogni ordine ha una metabox **Real Profit Dashboard** nella colonna laterale destra della sua schermata di modifica. Mostra il canale di acquisizione rilevato e propone tre campi di inserimento manuale che sovrascrivono i valori calcolati:

- **Commissioni di pagamento (€)**: se vuoi forzare un valore (ad esempio dopo un rimborso parziale delle commissioni)
- **Costo di spedizione reale (€)**: l'importo realmente pagato al corriere per questo specifico ordine
- **Altri costi (€)**: campo libero per qualsiasi costo specifico (dogana, packaging speciale, reso cliente, ecc.)

Un riepilogo sotto i campi mostra in tempo reale: fatturato netto, costi dettagliati, profitto e margine. Ogni salvataggio dell'ordine attiva un ricalcolo automatico.

## CRON e sincronizzazione

Due task automatici sono programmati:

- **dfrp_cron_sync_ads** (orario): chiama ogni integrazione attiva per recuperare la spesa degli ultimi 7 giorni, campagna per campagna, e aggiorna la tabella `wp_dfrp_ad_spend`.
- **dfrp_cron_recalculate_orders** (orario, concatenato): ricalcola le metriche degli ordini degli ultimi 14 giorni per tenere conto della nuova spesa pubblicitaria importata.

Il log completo di ogni esecuzione è accessibile tramite **Profit Dashboard → Log sincro**: stato, durata, numero di record inseriti e aggiornati, messaggio di errore eventuale.

Se il tuo WordPress è su hosting condiviso con un WP-Cron poco affidabile, è consigliato disattivare `DISABLE_WP_CRON` e programmare un CRON di sistema reale ogni ora: `curl -s https://tuo-dominio.com/wp-cron.php > /dev/null`.

## Ricalcolo manuale

Il pulsante **Ricalcola 60 giorni** del cruscotto rigenera le metriche di tutti gli ordini degli ultimi 60 giorni. Usalo dopo:

- l'installazione iniziale del plugin (per avviare lo storico)
- una modifica massiva dei COGS prodotti
- un cambio degli schemi di commissioni di pagamento o spedizione
- un cambio del modo di allocazione della spesa pubblicitaria

L'operazione è idempotente: rilanciarla più volte dà lo stesso risultato.

## API REST

Tre endpoint sono esposti sotto `/wp-json/dfrealprofit/v1/`. Richiedono la capability `manage_woocommerce` e accettano autenticazione tramite cookie WordPress o Application Password.

- `GET /summary?from=YYYY-MM-DD&to=YYYY-MM-DD` — KPI aggregati (fatturato, COGS, commissioni, pubblicità, profitto, margine)
- `GET /series?from=YYYY-MM-DD&to=YYYY-MM-DD` — serie giornaliera (fatturato, costi, profitto per giorno)
- `GET /channels?from=YYYY-MM-DD&to=YYYY-MM-DD` — performance per canale (ordini, fatturato, pubblicità, ROAS, profitto, margine)

Questi endpoint permettono di collegare un cruscotto esterno (Looker Studio, Metabase, Grafana, foglio di calcolo) alle metriche del plugin.

## Disinstallazione

La sola disattivazione non elimina alcun dato. L'eliminazione completa da **Plugin** attiva `uninstall.php`, che:

- elimina le tre tabelle custom (`ad_spend`, `order_metrics`, `sync_log`)
- elimina le opzioni del plugin
- rimuove i task CRON
- **conserva** i COGS dei prodotti e le meta degli ordini (dati di business preziosi)

Per una pulizia totale incluse le meta, occorre decommentare due righe SQL in `uninstall.php` prima di disinstallare.

## FAQ rapida

### Il plugin è compatibile con WooCommerce Subscriptions?

Sì. Ogni rinnovo genera un ordine standard trattato come qualsiasi altro.

### Cosa succede se cambio il prezzo di un prodotto?

Nulla per gli ordini esistenti: il COGS e il prezzo storici restano congelati al momento della vendita. Solo i nuovi ordini useranno il nuovo prezzo.

### Come gestire un rimborso?

Crea un rimborso standard da WooCommerce. Il fatturato netto viene ricalcolato automaticamente (il totale rimborsato viene dedotto). I costi già sostenuti (COGS, spedizione, commissioni, pubblicità) restano, il che dà la perdita reale.

### Posso usare il plugin senza integrazione Ads?

Sì. Senza integrazione pubblicitaria, i costi pub sono a zero e il calcolo si limita a fatturato netto − COGS − commissioni − spedizione − altri costi. È già di gran lunga meglio di quello che WooCommerce mostra per impostazione predefinita.

### I dati vengono inviati a un server esterno?

No. Le uniche chiamate esterne sono quelle che configuri tu stesso verso le API Meta, Google e TikTok, per **recuperare** la tua spesa. Nessun dato del tuo negozio viene inviato a DataFirefly né a terzi.