# Real Profit Dashboard: guia completo

> O Real Profit Dashboard calcula a rentabilidade real da sua loja WooCommerce, encomenda a encomenda. Este guia cobre a instalação, a configuração dos custos (COGS, comissões de pagamento, expedição), a…

- Página: <https://www.datafirefly.com/pt/documentation/real-profit-dashboard/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [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), [it](https://www.datafirefly.com/it/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)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

O Real Profit Dashboard calcula a rentabilidade real da sua loja WooCommerce, encomenda a encomenda. Este guia cobre a instalação, a configuração dos custos (COGS, comissões de pagamento, expedição), a ligação das três integrações publicitárias (Meta, Google, TikTok), a utilização do painel e a manutenção corrente.

## Requisitos

- WordPress 6.2 ou mais recente
- WooCommerce 8.0 ou mais recente (compatível com HPOS e com os Cart & Checkout Blocks)
- PHP 8.0 ou mais recente
- Um acesso de administrador ao back-office do WordPress
- Credenciais de API para Meta Ads, Google Ads e/ou TikTok Ads, se quiser ativar a importação automática das despesas de publicidade (facultativo)

## Instalação

1. Vá a **Plugins → Adicionar → Carregar plugin**.
2. Selecione o ficheiro `dfrealprofit.zip` e clique em **Instalar**.
3. Ative o plugin.
4. Aparece um novo menu principal **Profit Dashboard** na barra lateral, por baixo do WooCommerce.

Na ativação, o plugin cria três tabelas (`wp_dfrp_ad_spend`, `wp_dfrp_order_metrics`, `wp_dfrp_sync_log`) e agenda duas tarefas CRON horárias: sincronização das despesas de publicidade e recálculo deslizante dos últimos 14 dias.

## Primeiros passos

### Indicar o custo de compra (COGS) nos seus produtos

O COGS (Cost of Goods Sold, custo das mercadorias vendidas) é o pilar do cálculo da margem. Sem ele, o lucro apresentado fica sobrestimado.

- **Produto simples:** abra a ficha de produto, separador **Geral**, e preencha o campo _Custo de compra_ com o montante sem IVA pago ao fornecedor.
- **Produto variável:** cada variação tem o seu próprio campo _Custo de compra_. É indispensável preenchê-lo variação a variação se os custos forem diferentes (tamanhos, cores, materiais).
- **Em massa:** o campo também está acessível em escrita através da API REST do WooCommerce (`PUT /wp-json/wc/v3/products/{id}`, meta `_dfrp_cogs`), o que permite uma importação em massa a partir de um ERP.

Aparece uma coluna _COGS_ na lista de produtos, para identificar rapidamente os que ainda não foram preenchidos.

### Configurar as comissões de pagamento

Vá a **Profit Dashboard → Definições → Comissões de pagamento**.

- **Stripe, WooCommerce PayPal Payments, Mollie:** não é preciso configurar nada. O plugin lê diretamente as comissões reais faturadas a partir das metas da encomenda (`_stripe_fee`, `_ppcp_paypal_fees`, `_mollie_fee`).
- **Outros gateways:** indique a tabela de percentagem mais valor fixo aplicável. Por exemplo, numa transferência bancária gratuita: 0% / 0 €. Estes valores predefinidos são usados se não for encontrada qualquer meta de comissão real na encomenda.

### Configurar os custos de expedição

Vá a **Profit Dashboard → Definições → Custos de expedição predefinidos**. A tabela lista automaticamente todos os métodos de entrega das suas zonas WooCommerce.

Para cada método, indique o custo real médio pago à transportadora (líquido da margem que acrescenta ao cliente). Por exemplo, se fatura 6,90 € por uma entrega que lhe custa 4,50 €, introduza **4,50**.

Estes são valores predefinidos. Pode sempre substituir o custo real encomenda a encomenda (metabox lateral da ficha de encomenda) se um envio em concreto lhe tiver custado mais ou menos.

## Integrações publicitárias

Cada integração é independente. Pode ativar só uma, duas ou as três. Todas se configuram em **Profit Dashboard → Definições**.

### Meta Ads (Facebook e Instagram)

1. Crie uma aplicação no [Meta for Developers](https://developers.facebook.com/) ou use uma aplicação existente.
2. Gere um **access token long-lived** com o scope `ads_read`. A documentação oficial está em _Marketing API → Get Started_.
3. Obtenha o seu **Ad Account ID** em _Meta Business Manager → Definições → Contas publicitárias_ (formato numérico, sem o prefixo `act_`).
4. Nas definições do plugin, assinale **Ativar Meta Ads** e cole o access token e o Ad Account ID.
5. Guarde e clique em **Sincronizar Ads agora** a partir do painel para validar a ligação.

### Google Ads

O Google Ads usa OAuth 2. Precisa de cinco credenciais.

1. **Developer token:** peça-o a partir da sua conta Google Ads Manager (MCC), em _Ferramentas e definições → Configuração → Centro de API_.
2. **Customer ID:** o ID de 10 dígitos da conta publicitária cujas despesas quer acompanhar (sem os hífenes).
3. **OAuth client ID** e **client secret:** crie um projeto na [Google Cloud Console](https://console.cloud.google.com/), ative a API Google Ads e crie um cliente OAuth 2 do tipo _Aplicação de ambiente de trabalho_.
4. **Refresh token:** obtenha-o uma vez através do fluxo OAuth (ver a documentação da Google Ads API v18). Nunca mais muda.

O plugin troca automaticamente o refresh token por um access token em cada sincronização, e coloca este último em cache durante o seu período de validade (uma hora). Não tem de fazer nada depois de introduzir as credenciais.

### TikTok Ads

1. Crie uma aplicação no [TikTok Business Developers](https://business-api.tiktok.com/portal/).
2. Autorize-a na sua conta publicitária para obter um **access token**.
3. Obtenha o **Advertiser ID** no TikTok Ads Manager (menu da conta, no canto superior direito).
4. Nas definições do plugin, assinale **Ativar TikTok Ads** e cole o access token e o Advertiser ID.

## Atribuição multi-toque

Assim que o plugin é ativado, são colocados dois cookies em cada visitante: `dfrp_ft` (first-touch, primeiro canal conhecido) e `dfrp_lt` (last-touch, canal mais recente). Duram 90 dias.

Em cada visita, o plugin captura os seguintes parâmetros do URL:

- UTM padrão: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
- Identificadores de clique: `fbclid` (Facebook), `gclid` (Google), `ttclid` (TikTok)

No momento da criação da encomenda, os dois cookies ficam fixados nas metas da encomenda (`_dfrp_utm_ft`, `_dfrp_utm_lt`). O canal normalizado é depois deduzido do last-touch (com recurso ao first-touch) e arrumado numa destas nove categorias: _Facebook, Instagram, Google, TikTok, Email, Organic, Direct, Referral, Other_.

### Alocação das despesas de publicidade

Dois modos disponíveis nas definições:

- **Por encomenda** (predefinido): a despesa total de um canal num dia é dividida pelo número de encomendas atribuídas a esse canal nesse dia. Cada encomenda recebe uma parte igual.
- **Proporcional ao volume de negócios**: a despesa é distribuída proporcionalmente ao volume de negócios de cada encomenda no total do dia para esse canal. Uma encomenda de 300 € recebe três vezes mais custo publicitário do que uma encomenda de 100 €.

## Utilização do painel

O painel principal está acessível em **Profit Dashboard → Painel**.

### KPI principais

São apresentados sete indicadores no topo da página, para o intervalo selecionado:

- **Volume de negócios**: receita líquida (sem impostos, conforme a definição, e sem reembolsos)
- **COGS**: soma dos custos de compra das linhas vendidas
- **Comissões de pagamento**: total das comissões dos gateways
- **Expedição**: total dos custos reais de expedição
- **Publicidade**: total das despesas de publicidade alocadas
- **Lucro líquido**: volume de negócios menos COGS, comissões de pagamento, expedição, publicidade e outros custos
- **Margem**: lucro líquido a dividir pelo volume de negócios, em percentagem

### Gráfico e canais

Por baixo dos KPI, um gráfico de barras mostra o lucro diário do intervalo (barras verdes para lucro positivo, vermelhas para prejuízo).

O bloco **Desempenho por canal** agrega as encomendas por canal normalizado com, para cada um: número de encomendas, volume de negócios, despesa de publicidade, ROAS (retorno do investimento publicitário, ou seja volume de negócios a dividir pela despesa), lucro líquido e margem.

### Filtros e intervalos de datas

Sete intervalos predefinidos: Hoje, 7 dias, 30 dias, 90 dias, Mês em curso, Ano em curso e Intervalo personalizado. Os intervalos são relativos ao dia atual e atualizam-se automaticamente a cada carregamento da página.

## Metabox na ficha de encomenda

Cada encomenda tem uma metabox **Real Profit Dashboard** na coluna lateral direita do seu ecrã de edição. Mostra o canal de aquisição detetado e propõe três campos de introdução manual que substituem os valores calculados:

- **Comissões de pagamento (€)**: se quiser forçar um valor (por exemplo, num reembolso parcial de comissões)
- **Custo real de expedição (€)**: o custo efetivamente pago à transportadora nesta encomenda em concreto
- **Outros custos (€)**: campo livre para qualquer custo específico (encargos aduaneiros, embalagem especial, devolução de cliente, etc.)

Um resumo por baixo dos campos mostra em tempo real: receita líquida, custos detalhados, lucro e margem. Cada gravação da encomenda desencadeia automaticamente um recálculo.

## CRON e sincronização

São agendadas duas tarefas automáticas:

- **dfrp_cron_sync_ads** (horária): chama cada integração ativa para obter as despesas dos últimos 7 dias, campanha a campanha, e atualiza a tabela `wp_dfrp_ad_spend`.
- **dfrp_cron_recalculate_orders** (horária, encadeada): recalcula as métricas das encomendas dos últimos 14 dias, para ter em conta as novas despesas de publicidade importadas.

O registo completo de cada execução está acessível em **Profit Dashboard → Registos de sincronização**: estado, duração, número de registos inseridos e atualizados, e eventual mensagem de erro.

Se o seu WordPress estiver num alojamento partilhado com um WP-Cron pouco fiável, recomenda-se ativar a constante `DISABLE_WP_CRON` e agendar um verdadeiro CRON de sistema de hora a hora: `curl -s https://o-seu-dominio.com/wp-cron.php > /dev/null`.

## Recálculo manual

O botão **Recalcular 60 dias** no painel regenera as métricas de todas as encomendas dos últimos 60 dias. Use-o depois de:

- uma instalação inicial do plugin (para iniciar o histórico)
- uma alteração massiva dos COGS dos produtos
- uma alteração das tabelas de comissões de pagamento ou de expedição
- uma alteração do modo de alocação das despesas de publicidade

A operação é idempotente: voltar a lançá-la várias vezes dá o mesmo resultado.

## API REST

São expostos três endpoints em `/wp-json/dfrealprofit/v1/`. Exigem a permissão `manage_woocommerce` e aceitam autenticação por cookie do WordPress ou por Application Password.

- `GET /summary?from=AAAA-MM-DD&to=AAAA-MM-DD`: KPI agregados (volume de negócios, COGS, comissões, publicidade, lucro, margem)
- `GET /series?from=AAAA-MM-DD&to=AAAA-MM-DD`: série diária (volume de negócios, custos, lucro por dia)
- `GET /channels?from=AAAA-MM-DD&to=AAAA-MM-DD`: desempenho por canal (encomendas, volume de negócios, publicidade, ROAS, lucro, margem)

Estes endpoints permitem ligar um painel externo (Looker Studio, Metabase, Grafana, folha de cálculo) às métricas do plugin.

## Desinstalação

A desativação, por si só, não elimina qualquer dado. A remoção completa a partir de **Plugins** aciona o `uninstall.php`, que:

- elimina as três tabelas personalizadas (`ad_spend`, `order_metrics`, `sync_log`)
- elimina as opções do plugin
- desagenda os CRON
- **conserva** os COGS dos produtos e as metas de encomenda (dados de negócio valiosos)

Para uma limpeza total, incluindo as metas, é preciso descomentar duas linhas SQL no `uninstall.php` antes de desinstalar.

## FAQ rápida

### O plugin é compatível com o WooCommerce Subscriptions?

Sim. Cada renovação gera uma encomenda normal, tratada como qualquer outra.

### O que acontece se eu alterar o preço de um produto?

Nada nas encomendas existentes: o COGS e o preço históricos ficam fixados no momento da venda. Só as novas encomendas usam o novo preço.

### Como gerir um reembolso?

Crie um reembolso normal no WooCommerce. A receita líquida é automaticamente recalculada (o total reembolsado é deduzido). Os custos já suportados (COGS, expedição, comissões de pagamento, publicidade) mantêm-se, o que dá o verdadeiro prejuízo real.

### Posso usar o plugin sem integração de Ads?

Sim. Sem integração publicitária, os custos de publicidade ficam a zero e o cálculo limita-se a receita líquida menos COGS, comissões de pagamento, expedição e outros custos. Já é bastante melhor do que aquilo que o WooCommerce mostra por predefinição.

### Os dados são enviados para um servidor externo?

Não. As únicas chamadas externas são as que você próprio configura para as API da Meta, da Google e do TikTok, para **obter** as suas despesas. Nenhum dado da sua loja é enviado à DataFirefly nem a qualquer terceiro.