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

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.

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 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, 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.

TikTok Ads

1. Crie uma aplicação no TikTok Business Developers.
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.

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.