--- id: casos/visao-do-pipeline area: RevOps uso: muito usado esforco: médio grao: Negócio x passagem por etapa (entrada, saída, duração); agregado mês x pipeline x etapa testado_com_agente: out/2026 --- # Visão do pipeline (funil) Quantos negócios entram em cada etapa, quantos avançam e quanto tempo ficam, reconstruído do histórico do CRM e não da foto de hoje. ## Resumo executivo **Para quem:** Times comerciais e de RevOps que precisam saber onde o funil trava, com um número que todo painel repete. **O que resolve** - A conversão de cada etapa vem do caminho real do negócio, não da etapa em que ele está hoje. - O gargalo aparece em dois eixos: onde mais se perde e onde mais se espera. - Todo painel e o agente de IA contam etapa, ganho e perda do mesmo jeito. **Por que importa:** O CRM guarda a etapa atual, então um negócio perdido em proposta some do funil de proposta e quem pulou etapa nunca aparece nela. Sem o histórico, a conversão por etapa é chute e o time investe no topo quando o problema está no meio. É a base da previsão, da cobertura de meta, da saúde de deals e do funil por canal. **Perguntas de negócio que responde** - Em qual etapa perdemos mais negócios neste trimestre? - Quanto tempo um negócio leva, em média, da proposta até o ganho? - Quantos negócios entraram em negociação em setembro e quantos já avançaram? - A conversão de reunião para proposta caiu em relação ao trimestre passado? - Qual etapa concentra os negócios que estão há mais tempo esperando? **O que você precisa** - CRM conectado na Nekt com histórico de mudança de etapa (ou uma foto diária das etapas guardada desde já) - A lista de pipelines que são funil de venda, a ordem oficial das etapas e quais etapas são laterais (no-show, pausado, nutrição) **O que você recebe** - Uma tabela com uma linha por passagem de negócio por etapa, com entrada, saída e duração - Funil mensal por pipeline e etapa, com zero onde não houve movimento - Dashboard de conversão e tempo por etapa - Um agente de IA que responde sobre o funil com as definições certas ## Detalhado ### O problema O CRM mostra cada negócio só na etapa em que está agora. Quem conta o funil por essa foto perde todos os negócios que passaram pela etapa e seguiram, ou foram perdidos, e quem conta todos os pipelines juntos mistura venda com cadastro de clientes. O resultado são painéis com conversões diferentes para a mesma etapa e um gargalo que ninguém consegue apontar. ### Regras de negócio 1. **Funil vem do histórico, não da foto.** Monte uma linha por passagem do negócio por etapa, com data de entrada e de saída, a partir do histórico do CRM: propertiesWithHistory.dealstage no HubSpot (vem do registro mais novo para o mais antigo, reordene por data), deal_flow no Pipedrive, OpportunityHistory no Salesforce, eventos de mudança de status no Kommo, stage_history no Bitrix24, firstTimeIn por fase no Pipefy. Se o CRM não guarda histórico, grave uma foto diária das etapas a partir de hoje ou capture a mudança por webhook. No HubSpot, hs_v2_date_entered_ guarda só a última entrada na etapa: não serve como primeira entrada nem para montar as visitas. (Evite: Contar negócios pela etapa atual e chamar isso de funil.) 2. **Só pipeline de aquisição entra no funil.** Classifique cada pipeline antes de contar: funil de aquisição, cadastro de clientes, fila de operação, carteira, pós-venda, recrutamento ou eventos. Só funil de aquisição entra na conversão. Num caso real, contar um pipeline de clientes junto com o de vendas dava cerca de 91% de taxa de ganho, falsa. Exclua também pipelines arquivados e de rascunho. Pipeline de parceiros, ou qualquer pipeline com mais de uma etapa de ganho, fica fora até alguém declarar qual etapa é o ganho. (Evite: Somar todos os pipelines do CRM.) 3. **Chegou à etapa conta mesmo se pulou.** Um negócio chegou à etapa N se entrou nela ou em qualquer etapa posterior do mesmo funil. Negócio que pulou etapa conta na etapa pulada, com a data da primeira etapa posterior. Lead que nasce numa etapa por automação aparece no histórico só com a saída: use a data da saída como entrada. A ordem é a oficial, declarada pelo time: etapas laterais (no-show, pausado, nutrição) não são avanço e ficam fora da ordem. A ordem de exibição do CRM é só ponto de partida, e a probabilidade das etapas nem sempre cresce com a posição. (Evite: Exigir que o negócio tenha passado por todas as etapas.) 4. **Perdido não é progressão.** A etapa de perda não avança o negócio no funil. A perda conta na última etapa ativa antes dela. O status vem da semântica do CRM (ganho, perdido, aberto), nunca do nome da etapa, e uma etapa com nome de vendedor não é etapa. Num caso real, tratar a ida para Perdido como passo à frente criou mais de mil progressões falsas. Perda que vem direto de outro pipeline, ou negócio que já nasce perdido, não tem etapa ativa no funil: conte como perda sem etapa, à parte, e não na primeira etapa. (Evite: Ordenar etapas por posição e tratar Perdido como a última.) 5. **Fechado e ganho vêm da semântica, não do metadado.** No HubSpot, o metadata.isClosed das etapas chega true em todas elas pelo conector, inclusive nas abertas. Derive fechado e ganho da probabilidade da etapa (1.0 ganho, 0.0 perdido) ou de hs_is_closed_won e hs_is_closed no negócio. No Bitrix24, use stage_semantic_id; no Kommo, os status 142 (ganho) e 143 (perdido) valem para qualquer funil. (Evite: Filtrar etapas abertas por metadata.isClosed = false.) 6. **Nova visita só quando a etapa muda.** O histórico traz registros repetidos da mesma etapa sem mudança real. Marque o início de uma visita só quando a etapa difere do registro anterior do mesmo negócio; senão a data da última entrada fica inflada. Para o funil, use a primeira entrada em cada etapa; para tempo, some todas as visitas. (Evite: Pegar a maior data de cada etapa no histórico bruto.) 7. **Coorte e produção não se misturam.** Funil de coorte: parte dos negócios criados no mês e acompanha até onde cada um chegou. Produção do mês: cada etapa contada no mês do seu próprio evento. As duas leituras são válidas, mas nunca filtre a coorte pela data de uma etapa posterior, e nunca some mês de criação com mês de fechamento. (Evite: Conversão = ganhos do mês / negócios criados no mês.) 8. **Tempo da etapa aberta fica separado.** Para negócio ainda aberto, o tempo na etapa atual é medido até hoje e cresce a cada dia. Mostre o tempo de etapas concluídas separado da idade de quem ainda está na etapa, senão a média sobe sozinha. Tempo só se mede em etapas abertas: o tempo parado em Ganho ou Perdido não é tempo de funil. Converta datas para America/Sao_Paulo uma vez só: o Bitrix24 grava no fuso do servidor, outros CRMs em UTC. (Evite: Média de dias na etapa misturando visitas concluídas e abertas.) 9. **Negócio movido de pipeline não some.** Negócio movido para outro pipeline sai do funil de origem e muda o passado se a conta usar o pipeline atual. Atribua cada passagem ao pipeline da etapa em que ela aconteceu. Em muitos CRMs o ganho é movido para um pipeline de clientes ativos logo depois: o ganho conta pela passagem na etapa de ganho, não pela etapa atual. (Evite: Contar ganhos pelos negócios que estão hoje na etapa Ganho.) 10. **Etapa apagada continua no histórico.** O histórico guarda ids de etapas que foram apagadas ou recriadas no CRM e não aparecem mais na lista de etapas do pipeline. Sem mapeamento, essas passagens somem do funil ou ficam sem pipeline. Mapeie cada etapa antiga para a etapa atual equivalente, ou declare que fica fora, e confira que nenhuma passagem fica sem etapa. (Evite: Descartar em silêncio as passagens cujo id de etapa não está mais no pipeline.) ### De onde vem o histórico e o status em cada CRM O histórico monta as passagens; o status diz se o negócio ganhou, perdeu ou segue aberto. - **HubSpot** → Histórico em propertiesWithHistory.dealstage, do mais novo para o mais antigo; hs_v2_date_entered guarda só a última entrada (`dealstage history · probability 1.0 ganho · 0.0 perdido`) - **Pipedrive** → Histórico no deal_flow; status do negócio (`status = won | lost | open`) - **Salesforce** → Histórico em OpportunityHistory; fechado e ganho na oportunidade (`IsClosed · IsWon`) - **Bitrix24** → Histórico em stage_history; semântica da etapa (`stage_semantic_id = P | S | F`) - **Kommo** → Histórico nos eventos de mudança de status; ids globais de ganho e perda (`status 142 ganho · 143 perdido`) - **RD Station CRM** → Status nativo; pausado conta como aberto (`won | lost | ongoing | paused`) - **Pipefy** → Data por fase; se o card voltou para Perdido, vale a última vez (`firstTimeIn · lastTimeIn`) ### Definições | Métrica | Definição | |---|---| | Entrada na etapa | negócio que entrou na etapa, ou numa etapa posterior do mesmo funil, pela primeira vez; conta uma vez por negócio, no mês da entrada | | Conversão da etapa | negócios que chegaram à etapa seguinte / negócios que entraram na etapa, dentro da mesma coorte | | Perda na etapa | negócios perdidos cuja última etapa ativa antes da perda foi esta, no mesmo pipeline; perda vinda de outro pipeline ou de negócio nascido perdido fica em perda sem etapa | | Tempo na etapa | saída - entrada de cada visita concluída a uma etapa aberta, em dias; soma das visitas quando o negócio volta à etapa; Ganho e Perdido não têm tempo | | Idade na etapa atual | hoje - entrada na etapa atual, só para negócios abertos | | Taxa de ganho | ganhos / (ganhos + perdidos) entre os negócios já fechados da coorte; abertos ficam fora do denominador | | Ciclo | data do ganho - data de criação, só de negócios ganhos | | Gargalo | a etapa com a menor conversão e a etapa com a maior mediana de tempo, mostradas lado a lado | ### Armadilhas - **Ganho falso de cadastro.** Um pipeline de clientes ativos contado junto com o de vendas levou a taxa de ganho para perto de 91%. Como evitar: Classifique os pipelines antes de qualquer conta. - **Etapa com zero some.** Etapas sem negócio no mês desapareciam do resultado e o funil ficava com degraus faltando. Como evitar: Monte a grade de todas as etapas e preencha com zero. - **Data errada como entrada.** Usar a data de atualização do negócio como entrada zerava o tempo a cada edição de campo. Usar hs_v2_date_entered_ do HubSpot, que guarda só a última entrada, jogava o negócio que voltou à etapa para o mês errado. Como evitar: Use a primeira entrada da etapa no histórico de etapas (no HubSpot, propertiesWithHistory.dealstage). - **Teste, importação e duplicado no topo.** Negócios de teste de integração, bases importadas e cards perdidos por duplicidade inflavam as entradas. Como evitar: Exclua por motivo de perda e por origem de importação, com a lista declarada. No HubSpot: closed_lost_reason de duplicado ou lead inválido, hs_was_imported no negócio e sourceType IMPORT no histórico de etapas. - **Definição presa no BI.** A definição de MQL vivia numa medida do BI e dois painéis mostraram números diferentes na mesma reunião de liderança. Como evitar: Defina etapa e indicador uma vez, na transformação, e faça os painéis lerem dela. - **Histórico que começa tarde.** Um histórico de etapa só começou a ser gravado meses depois do CRM, e os meses anteriores tinham cerca de um terço das mudanças reais. Como evitar: Declare a partir de quando o funil é confiável e não compare antes disso. Validado em dados reais: Na conta de HubSpot da própria Nekt, todas as etapas de todos os pipelines chegam com metadata.isClosed = true, inclusive as abertas. E mais de 8 em cada 10 negócios que passaram pela etapa de ganho do pipeline de vendas hoje estão em outro pipeline: contar o ganho pela etapa atual mostraria menos de um décimo dos ganhos reais. ### Teste de aceitação - [ ] Para um mês fechado, o total de negócios criados nos pipelines de aquisição, descontadas as exclusões declaradas, bate com o relatório de negócios criados do CRM (diferença abaixo de 1%). Por pipeline, atribua o negócio ao pipeline em que nasceu: o relatório do CRM usa o pipeline atual e diverge quando o negócio muda de pipeline. - [ ] Os ganhos do mês batem com os negócios que passaram pela etapa de ganho no mês, incluindo os que depois foram movidos de pipeline. - [ ] Em cada coorte, as entradas na etapa N+1 nunca passam das entradas na etapa N. - [ ] Toda etapa do funil aparece em todos os meses, com zero quando não houve movimento. - [ ] Nenhum pipeline classificado como cadastro, carteira, operação ou parceiros aparece no funil, e nenhuma passagem fica com etapa sem mapeamento. ### Context document ```text Funil de vendas por etapa - Fonte: tabela de passagens por etapa (uma linha por negócio x visita à etapa, com entrada, saída e duração). Não conte funil pela etapa atual do negócio. - No HubSpot, as passagens vêm de propertiesWithHistory.dealstage. hs_v2_date_entered_ guarda só a última entrada: nunca use como primeira entrada. - Só pipelines classificados como funil de aquisição entram, com uma etapa de ganho. Pipelines de clientes, carteira, operação, parceiros, recrutamento e eventos ficam fora. - Chegou à etapa N = entrou em N ou em qualquer etapa posterior do mesmo funil. Negócio que pulou etapa conta na etapa pulada. Etapas laterais (no-show, pausado) não são avanço. - A perda conta na última etapa ativa antes da perda, no mesmo pipeline. Perdido não é progressão. Perda vinda de outro pipeline ou de negócio nascido perdido é perda sem etapa. - Ganho e perdido pela semântica do CRM (no HubSpot, probabilidade da etapa 1.0 ou 0.0). Nunca pelo nome da etapa nem por metadata.isClosed. - Ganho = ter passado pela etapa de ganho, mesmo que o negócio esteja hoje em outro pipeline. - Diga sempre se a leitura é de coorte (mês de criação) ou de produção (mês do evento). Não misture as duas. - Tempo na etapa: só visitas concluídas a etapas abertas; Ganho e Perdido não têm tempo. Idade de quem ainda está na etapa é outra métrica. - Datas em America/Sao_Paulo. Exceções por cliente: - : pipelines de funil = ; ordem das etapas = ; etapas laterais = . - : etapas apagadas no histórico = -> . - : exclusões de topo = . - : histórico confiável a partir de ; antes disso, só a foto mensal. ``` ### Variações - **Por responsável:** A mesma tabela com o dono do negócio no momento de cada passagem, não o dono atual. - **CRM sem histórico:** Foto diária das etapas guardada desde já, ou webhook de mudança de etapa, até ter meses suficientes. - **Do lead à venda:** Ligue o objeto de lead ao de negócio pela conversão (no Salesforce, convertedOpportunityId) para ter lead, MQL, SQL e venda numa linha.