# DataFirefly Inventory Forecasting: guia completo

> Guia completo de instalação, configuração e utilização do DataFirefly Inventory Forecasting para prever as suas ruturas de stock, gerar notas de encomenda a fornecedor e desencadear alertas automáticas no WooCommerce.

- Página: <https://www.datafirefly.com/pt/documentation/datafirefly-inventory-forecasting/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafirefly-inventory-forecasting/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-inventory-forecasting/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-inventory-forecasting/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-inventory-forecasting/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-inventory-forecasting/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-inventory-forecasting/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-inventory-forecasting/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

## Visão de conjunto

O DataFirefly Inventory Forecasting é um plugin WooCommerce de previsão de stock, geração automática de notas de encomenda a fornecedor e alertas de rutura. Transforma o back-office do WordPress num posto de pilotagem da cadeia de abastecimento, sem passar por um SaaS externo e sem custos por SKU.

O plugin assenta num algoritmo **Holt-Winters multiplicativo** que decompõe as suas vendas históricas em duas componentes: uma tendência estimada por regressão linear sobre uma média móvel de sete dias, e uma sazonalidade calculada como índice mensal multiplicativo. As previsões a 30, 60 e 90 dias são depois comparadas com o stock atual para produzir um ponto de reencomenda, uma quantidade de reabastecimento (tendo em conta a MOQ e o tamanho do lote) e uma estimativa da data de rutura.

**Posicionamento.** O Inventory Forecasting foi concebido como alternativa autoalojada ao Veeqo, ao Cin7 ou ao Lokad. Destina-se a catálogos de 100 a alguns milhares de SKU, com ou sem histórico sazonal estável.

## Requisitos e instalação

### Requisitos técnicos

- WordPress 6.4 ou superior
- WooCommerce 8.0 ou superior
- PHP 8.1 ou superior
- MySQL 5.7 ou MariaDB 10.3 no mínimo
- WP-Cron ativo (ou substituído por um cron de sistema que acione o wp-cron.php)

### Instalação

1. Descarregue o arquivo ZIP a partir da sua conta de cliente em datafirefly.com.
2. No WordPress, vá a _Plugins → Adicionar plugin → Carregar plugin_.
3. Selecione o ZIP e clique em _Instalar agora_.
4. Ative a extensão. Na ativação, o plugin cria sete tabelas com prefixo `wp_dfif_`, declara a compatibilidade HPOS e agenda quatro tarefas cron diárias.

**Verificação pós-instalação.** Aparece um novo menu _Inventory Forecasting_ na barra lateral da administração, com o ícone de gráfico. Abra o painel para verificar que os contadores de KPI aparecem a zero.

### Primeiro arranque: reconstruir o histórico

O plugin precisa de conhecer as suas vendas passadas para calibrar a tendência e os índices sazonais. Na primeira utilização, clique em _Reconstruir o histórico_ a partir do painel. Esta ação percorre as encomendas concluídas da janela configurada (365 dias por predefinição) e agrega as quantidades vendidas por produto e por dia na tabela `wp_dfif_sales_daily`.

Num catálogo de algumas centenas de produtos e 12 meses de histórico, a operação demora de um a cinco minutos. É paginada em blocos de 100 encomendas e compatível com HPOS.

## Conceitos fundamentais

### Tendência e sazonalidade

Em cada ciclo de previsão, o plugin constrói para cada produto uma série diária suavizada por média móvel de sete dias. Uma regressão linear sobre essa série dá a **tendência** (declive e ordenada na origem). Em separado, os índices **sazonais** mensais são calculados como a razão entre as vendas de cada mês do calendário e a média anual, com um mínimo de 0,3 e um máximo de 3,0 para absorver os valores aberrantes.

A previsão ao horizonte H dias combina depois tendência e índice do mês alvo: vendas_previstas = vendas_médias × (1 + tendência × H) × índice_sazonal.

### Stock de segurança

O stock de segurança é calculado pela fórmula clássica z × σ × √lead_time, em que z é o quantil normal correspondente ao nível de serviço pretendido (1,645 para 95%, 2,326 para 99%), σ o desvio-padrão das vendas diárias e lead_time o prazo de entrega do fornecedor em dias. Esta reserva absorve as variações aleatórias da procura durante o reabastecimento.

### Ponto de reencomenda e quantidade de reencomenda

O **ponto de reencomenda** é o limiar de stock que desencadeia uma encomenda. Vale vendas_médias × lead_time + stock_de_segurança. Na prática, assim que o stock atual desce abaixo desse limiar, deve ser feita uma encomenda para evitar a rutura.

A **quantidade de reencomenda** é a quantidade a encomendar. É arredondada ao múltiplo do tamanho de lote (pack size) e depois elevada à MOQ (quantidade mínima de encomenda do fornecedor), se for necessário.

### Nível de confiança

Cada previsão vem acompanhada de uma pontuação de confiança de 0 a 100%, calculada heuristicamente conforme a extensão do histórico disponível, a regularidade das vendas e a presença de sazonalidade marcada. Uma confiança inferior a 40% aparece a vermelho e passa automaticamente para uma previsão simples (média móvel), mais prudente.

## Gestão dos fornecedores

### Criar um fornecedor

No menu _Inventory Forecasting → Fornecedores_, clique em _Adicionar um fornecedor_. Indique no mínimo o nome e o e-mail (usado para o envio das notas de encomenda). Os campos facultativos são: contacto, telefone, morada, moeda de faturação e notas internas.

### Associar um fornecedor a um produto

Na página de edição de um produto WooCommerce, aparece uma metabox _Fornecedores Inventory Forecasting_ na coluna principal. Permite acrescentar um ou vários fornecedores a esse produto, cada um com os seus próprios parâmetros:

- **Preço de compra** sem impostos, usado na linha da nota de encomenda
- **SKU do fornecedor**, muitas vezes diferente do SKU interno, impresso no PDF
- **Prazo de entrega** em dias, que entra no cálculo do ponto de reencomenda
- **MOQ**, quantidade mínima exigida pelo fornecedor
- **Tamanho de lote**, incremento pelo qual as quantidades são arredondadas
- **Fornecedor principal**, botão de opção que designa o fornecedor escolhido pela geração automática das notas de encomenda

**Vários fornecedores.** Um mesmo produto pode estar associado a vários fornecedores, por exemplo um principal mais barato e um secundário de recurso. Só o principal é usado pela geração automática, mas pode mudar manualmente para outro a partir da página do produto.

## Previsões e horizontes

A página _Inventory Forecasting → Previsões_ lista todos os produtos com, para cada um, a previsão ao horizonte selecionado, o ponto de reencomenda, a quantidade a encomendar, a data estimada de rutura e o nível de confiança.

### Filtros

- **Horizonte**: 30, 60 ou 90 dias (os três são calculados em paralelo pelo cron)
- **Gravidade**: crítica (rutura em menos de 7 dias), aviso (rutura em menos de 14 dias), normal
- **Pesquisa**: por título de produto ou SKU

### Recálculo manual

O botão _Recalcular as previsões_ do painel força um ciclo imediato sem esperar pelo cron das 2h30. Útil depois de mudar um parâmetro (nível de serviço, tamanho da janela de histórico) ou depois de uma importação massiva de encomendas.

## Notas de encomenda a fornecedor

### Ciclo de vida de uma nota de encomenda

1. **Rascunho**: criada mas não enviada, editável
2. **Enviada**: PDF gerado e expedido ao fornecedor por e-mail
3. **Parcialmente recebida**: pelo menos uma linha, mas não todas as quantidades, recebida
4. **Recebida**: todas as quantidades registadas
5. **Cancelada**: encomenda abandonada antes da receção

### Geração manual

A partir de _Inventory Forecasting → Notas de encomenda_, o botão _Gerar a partir das previsões_ percorre os produtos abaixo do ponto de reencomenda, agrupa-os por fornecedor principal e cria uma nota de encomenda em rascunho por fornecedor. Pode depois editar as quantidades, acrescentar ou retirar linhas, e enviar.

### Geração automática

O cron das 4h pode gerar automaticamente as notas de encomenda, com ou sem envio imediato. Esta opção está **desativada por predefinição**. Depois de ativada nas definições, há dois modos possíveis: criação em rascunho (envio manual após validação) ou envio imediato.

**Recomendação.** Deixe o envio automático desativado durante pelo menos duas semanas após a instalação. Verifique a pertinência das previsões antes de confiar no automatismo completo, sob pena de encomendar demasiado cedo ou em quantidade excessiva.

### PDF nativo

O PDF é gerado por um motor em PHP puro integrado (tipo de letra Helvetica, formato A4, cerca de 250 linhas de código). Inclui o cabeçalho da sua empresa, os dados do fornecedor, a tabela de linhas com SKU do fornecedor e preço de compra, o total sem IVA, e um rodapé personalizável. Não é exigida qualquer dependência do Dompdf, do TCPDF ou do mPDF.

### Receção da mercadoria

Na vista de detalhe de uma nota de encomenda, cada linha tem um campo _Quantidade recebida_. Introduzir o valor recebido atualiza o stock WooCommerce do produto pelo _delta_ face ao valor anterior. Esta lógica evita as contagens duplicadas se corrigir uma receção à posteriori.

## Alertas de rutura

O plugin deteta diariamente quatro tipos de situação e atribui a cada uma um nível de gravidade.

### Tipos de alertas

- **IMMINENT**: rutura prevista em menos de 7 dias (parametrizável), gravidade crítica
- **WARNING**: rutura prevista em menos de 14 dias (parametrizável), gravidade de aviso
- **OVERSTOCK**: cobertura de stock superior a 180 dias, gravidade informativa
- **REORDER**: stock abaixo do ponto de reencomenda, gravidade de aviso

### Ciclo de vida

Uma alerta é criada com o estado _active_. No ciclo seguinte, se a situação persistir, é marcada como _pending_recheck_; se tiver desaparecido, passa a _resolved_ com data e hora. Este mecanismo evita o spam de alertas repetitivas.

### Notificações por e-mail

É enviado um resumo diário para o endereço configurado nas definições, com a lista das novas alertas críticas e de aviso. O conteúdo do e-mail é uma tabela HTML sóbria, filtrável por gravidade.

## Definições

A página _Inventory Forecasting → Definições_ reúne quatro secções.

### Previsões

- **Janela de histórico**: 365 dias por predefinição. Quanto mais longa for a janela, mais robusta é a sazonalidade, mas maior fica a tabela sales_daily.
- **Horizontes de previsão**: lista separada por vírgulas, 30, 60 e 90 por predefinição. Pode acrescentar, por exemplo, 14 ou 180.
- **Nível de serviço**: 95% por predefinição. Traduzido em z = 1,645 pela inversa normal. Passe a 99% (z = 2,326) para stock crítico, e a 90% (z = 1,282) para o não estratégico.

### Alertas

- **Dias de antecipação de aviso**: 14 por predefinição
- **Dias de antecipação crítica**: 7 por predefinição
- **E-mail destinatário do resumo diário**

### Notas de encomenda

- **Geração automática ativada**: desassinalada por predefinição
- **Prefixo de numeração**: PO- por predefinição, produz identificadores como PO-2026-00042
- **Moeda**: herdada do WooCommerce, substituível por fornecedor

### Empresa

Dados da sua empresa impressos no cabeçalho dos PDF das notas de encomenda: designação social, morada, número de identificação da empresa ou número de IVA, e-mail, telefone e logótipo.

## Tarefas cron

São agendadas automaticamente quatro tarefas na ativação do plugin, no fuso horário do site.

- `02:00` — **Reconstrução do histórico**: agrega as encomendas da véspera na tabela sales_daily. Leve, alguns segundos.
- `02:30` — **Cálculo das previsões**: recalcula tendência, sazonalidade e pontos de reencomenda. Mais pesado, de um a cinco minutos consoante o catálogo.
- `03:00` — **Deteção das alertas**: cria e resolve as alertas conforme os limiares. Rápido.
- `04:00` — **Geração automática das notas de encomenda**: só é executada se a opção estiver ativa nas definições.

**WP-Cron.** Por predefinição, o WP-Cron só é executado num evento de visitante. Num site de baixo tráfego, isso pode atrasar as tarefas noturnas. Configure de preferência um cron de sistema que chame o wp-cron.php a cada 15 minutos, ou desative o WP-Cron no wp-config.php e comande-o inteiramente por cron de sistema.

## API REST

O plugin expõe várias rotas REST no namespace `dfif/v1`. Todas exigem a permissão `manage_woocommerce` e o nonce do WordPress `wp_rest`.

```
POST /wp-json/dfif/v1/run-forecast
POST /wp-json/dfif/v1/rebuild-history
POST /wp-json/dfif/v1/detect-alerts
POST /wp-json/dfif/v1/generate-pos
POST /wp-json/dfif/v1/send-po/{id}
POST /wp-json/dfif/v1/po/{id}/items/{item_id}/receive
GET  /wp-json/dfif/v1/stats
```

Estas rotas são usadas internamente pelos botões do painel (através do wp.apiFetch com o cabeçalho X-WP-Nonce) e podem também ser chamadas a partir de qualquer cliente autenticado por cookies do WordPress ou por application passwords.

### Hooks do WordPress

As principais etapas do plugin emitem ações e filtros que pode intercetar:

```
do_action('dfif_forecast_calculated', $product_id, $forecast_data);
do_action('dfif_purchase_order_created', $po_id, $supplier_id);
do_action('dfif_purchase_order_sent', $po_id);
do_action('dfif_alert_triggered', $alert_id, $alert_type);
apply_filters('dfif_reorder_qty', $qty, $product_id, $supplier_id);
apply_filters('dfif_pdf_company_info', $info);
```

## Resolução de problemas

### As previsões continuam a zero

Verifique que a reconstrução do histórico foi mesmo executada e que a tabela sales_daily contém linhas. Se não tiver encomendas concluídas ou em processamento na janela configurada, o plugin não consegue prever nada. Verifique também que o WooCommerce está ativo.

### As previsões parecem incoerentes

Duas causas frequentes: um histórico demasiado curto (menos de 30 dias, o plugin passa a uma previsão simples) ou uma sazonalidade extrema não representativa (uma Black Friday isolada). Olhe para o nível de confiança apresentado: abaixo de 40%, a previsão deve ser tomada com cautela.

### O PDF não é gerado

Verifique que o diretório `wp-content/uploads/dfif-po/` tem permissões de escrita. É aí que o plugin coloca os PDF antes do envio. É criado automaticamente um ficheiro .htaccess para impedir o acesso público direto.

### O e-mail não é enviado

O plugin usa o wp_mail, que por vezes falha em alguns alojamentos. Instale um plugin de SMTP (WP Mail SMTP, FluentSMTP) e configure um serviço de entregabilidade (Postmark, SendGrid, Mailjet, Brevo). Verifique também que o e-mail do fornecedor está bem introduzido e é válido.

### O cron não corre

Use o plugin WP Crontrol para listar os hooks agendados e ver a próxima execução. Os quatro hooks têm o prefixo `dfif_`. Se não os vir, desative e volte a ativar o Inventory Forecasting.

## Desinstalação

Na desativação, os crons são desagendados mas as tabelas e os dados são conservados. Na desinstalação completa através de _Plugins → Eliminar_, há dois comportamentos possíveis consoante a opção `dfif_delete_data_on_uninstall` nas definições:

- **Desassinalada por predefinição**: as tabelas são conservadas e pode reinstalar sem perder o histórico.
- **Assinalada**: as sete tabelas e o diretório `wp-content/uploads/dfif-po/` são eliminados.

## FAQ

### Posso usar o plugin num catálogo variável (variações de produto)?

Sim. As previsões e as notas de encomenda funcionam ao nível da variação individual. Cada variação pode ter os seus próprios fornecedores e os seus próprios parâmetros.

### O plugin é compatível com multisite?

Sim, mas cada site da rede gere o seu próprio catálogo, os seus fornecedores e as suas previsões. Não há partilha entre sites.

### Posso exportar os dados?

Todas as tabelas são acessíveis por SQL padrão. Está prevista uma exportação CSV nativa numa versão posterior. Até lá, basta um simples `SELECT INTO OUTFILE` ou um plugin como o WP All Export.

### O plugin bloqueia a administração se o cron não tiver corrido?

Não. O plugin continua a funcionar, apenas as previsões apresentadas podem ter vários dias. Um distintivo _Último cron_ no painel indica a frescura dos dados.

### Como se comporta o plugin num catálogo de vários milhares de SKU?

A reconstrução do histórico e o cálculo das previsões mantêm-se lineares no número de produtos ativos. Com 5000 SKU e 12 meses de histórico, conte com 10 a 30 minutos de processamento noturno, consoante a potência do servidor. Sem qualquer impacto no desempenho do front-office: todos os cálculos são assíncronos.