Funil Doka

1.1O sistema em uma frase

O Funil Doka é um site interno que junta, num só lugar, números que hoje vivem espalhados em cinco plataformas diferentes — Google Search Console, Google Analytics, RD Station Marketing, RD Station CRM e as redes sociais — e os organiza em seis etapas, da primeira vez que alguém vê a marca até o momento em que uma venda é marcada como fechada.

Antes dele, responder “quantas pessoas viraram oportunidade no mês passado?” exigia abrir quatro sistemas, exportar planilhas e cruzar tudo à mão. O sistema faz esse trabalho automaticamente, sempre que alguém abre a página.

1.2As seis etapas

O funil é lido de cima para baixo. Cada etapa é mais estreita que a anterior, porque só uma parte das pessoas avança. Entre uma etapa e a próxima o sistema mostra a taxa de conversão — o percentual que passou adiante.

1.3O que o sistema não é

• Não é um CRM. Ele lê o RD Station CRM, mas nunca escreve nada lá. Nenhuma ação feita no painel altera uma negociação.
• Não é uma ferramenta de faturamento. Nenhum valor em reais entra no sistema.
• Não substitui o Google Analytics nem o RD. Para análises profundas de comportamento, continue usando as ferramentas originais. O Funil existe para ter a visão geral rápida e comparável.
• Não guarda dados pessoais de clientes. O que fica gravado são contagens e, no caso dos eventos de webhook, o e-mail de contato usado apenas para identificar o evento.
• Não é público. O endereço é acessível por quem tiver o link, mas não é divulgado. Não há tela de login.

1.4Quem usa, e para quê

1.5Como ler esta documentação

O documento é dividido por tipo de necessidade, não por ordem cronológica. Vá direto para a parte que corresponde à sua pergunta:

Use o campo de busca no topo do índice para filtrar as seções por palavra. O documento é uma página só — a busca do navegador (Ctrl+F ou Cmd+F) também encontra qualquer texto daqui.

2.1Endereços do sistema

O sistema roda na Vercel, um serviço que hospeda o site. Toda alteração enviada ao GitHub é publicada automaticamente pela Vercel em poucos minutos. Não existe um servidor físico nem uma máquina ligada no escritório.

2.2A tela principal, item por item

De cima para baixo, o painel tem sete blocos:

1. Cabeçalho
   Nome do sistema, data e hora da última atualização dos dados, botão de tema claro/escuro e os links para as outras páginas.
2. Filtros
   Período, marca e canal. Detalhados em 2.3.
3. Barra de status
   Aparece no topo quando alguma integração falha. Some sozinha quando está tudo certo.
4. Seis cartões de etapa
   Um por etapa do funil, com o número total, o recorte por marca e a taxa de conversão vinda da etapa anterior. Cada cartão tem um botão ? que abre a explicação da etapa em linguagem simples. Clicar no cartão abre o detalhamento.
5. Funil vertical
   A representação visual em barras, da mais larga (Impressões) à mais estreita (Vendas). A largura é calculada em escala logarítmica — sem isso, as barras de MQL, SQL e Vendas ficariam invisíveis ao lado das impressões.
6. MQL por Fonte e Perfil de Clientes
   Dois painéis de análise. Detalhados em 2.5.
7. Status das integrações
   No rodapé: um indicador por plataforma, verde quando os dados chegaram e vermelho quando houve falha.

2.3Os filtros

2.4Detalhamento de uma etapa

Clicar em qualquer cartão de etapa abre uma janela com a composição daquele número:

Dentro da janela há botões para alternar entre Doka e Immersi quando a etapa tem essa separação.

2.5MQL por Fonte e Perfil de Clientes

MQL por Fonte

Cinco cartões, um para cada nota de 1 a 5 estrelas dada pelo time comercial no CRM. Cada cartão lista as fontes de origem que mais trouxeram oportunidades com aquela nota. Serve para responder: “o Instagram traz volume, mas traz oportunidade boa?”.

A fonte vem do campo nativo deal_source do RD CRM — o mesmo que aparece na tela de negociação lá dentro. Se todos os cartões mostrarem “Não identificada”, veja a ficha de erro E-11.

Perfil de Clientes

Cinco recortes das oportunidades criadas no período, extraídos de campos personalizados do CRM: produto de interesse, como conheceu a Doka, representante, marca de interesse e cidade. O cartão mostra os cinco primeiros; clicar abre a lista completa com percentuais.

2.6Barra de status das integrações

O sistema nunca deixa a página em branco por causa de uma integração com problema. Se o Search Console falhar, as outras cinco etapas continuam aparecendo normalmente e apenas Impressões mostra o aviso de erro.

2.7As outras páginas

/manual — lançamento manual

Tem três abas: impressões de redes sociais, dados históricos do RD Marketing e dados históricos do RD CRM. Acima delas há um mapa de calor com as últimas 52 semanas, mostrando quais já têm dado lançado e quais estão vazias. Cada semana começa numa quinta-feira (veja 4.7).

/emails — assinantes do resumo

Lista de e-mails que recebem o resumo de segunda-feira, com campo para cadastrar, botão para remover e um botão para disparar o envio na hora.

/mapa-dados-funil.html — mapa de dados

Página estática de referência, feita antes desta documentação, que detalha campo a campo o que cada API devolve. Continua útil como consulta rápida e traz atalhos para as rotas de diagnóstico.

3.1Diagrama geral

Fluxo completo do dado. A caixa tracejada do webhook indica que o recebimento já está construído, mas o webhook ainda não foi registrado na RD — veja 5.7.

3.2As plataformas conectadas

3.3O caminho de um número até a tela

Sequência exata do que acontece quando alguém abre o painel:

1. O navegador pede os dados
   A página chama /api/funnel passando período, marca e canal.
2. Seis consultas partem ao mesmo tempo
   Search Console (Doka e Immersi), Analytics (Doka e Immersi), RD Marketing, impressões manuais no Postgres e eventos de webhook no Sheets. São disparadas em paralelo, e o sistema espera todas — mas não desiste se alguma falhar.
3. O CRM é consultado à parte, uma única vez
   Essa chamada devolve, de uma vez só, MQL, SQL, Vendas e Perfil de Clientes. É a operação mais lenta do sistema, porque pagina de 200 em 200 negociações.
4. Cada resultado é conferido
   O que deu certo entra com o valor real. O que falhou entra como null — que a tela mostra como — — e carrega junto a mensagem de erro.
5. Os leads de webhook são classificados por marca
   Cada evento recebido é lido pelo nome: se contém “immersi”, é Immersi; se contém “doka”, é Doka; se não contém nenhum dos dois, entra só no total geral.
6. As somas são feitas
   Impressões = Search Console Doka + Search Console Immersi + total manual das redes. Leads = conversões da RD + eventos de webhook. As demais etapas vêm direto do CRM.
7. As taxas de conversão são calculadas
   Sempre etapa seguinte dividida por etapa anterior, com uma casa decimal. Se o denominador é zero, a taxa é zero.
8. Um efeito colateral é registrado
   Os dias em que o Search Console trouxe dado real são marcados no Postgres, para a regra “API sempre vence” descrita em 4.5. Se essa marcação falhar, ninguém percebe e nada quebra — é intencional.
9. A resposta volta pronta
   Um único pacote com os seis totais, todos os detalhamentos, as cinco taxas de conversão e o horário exato da consulta.

3.4As quatro categorias de leads

Esta é provavelmente a parte menos óbvia do sistema, e a que mais gera dúvida. Nem toda conversão da RD Station chega pelo mesmo caminho. Elas foram separadas em quatro categorias durante a construção:

Já foram identificados e reconstruídos 8.288 eventos de categoria C e 281 de categoria D, cobrindo de janeiro de 2025 a agosto de 2026. Eles estão na aba Webhook_RD_MKT da planilha e já entram no total de Leads quando o período consultado os abrange.

3.5Onde cada dado fica guardado

4.1Definição de cada etapa

Os textos abaixo são os mesmos que aparecem nos botões ? do painel. Foram revisados e aprovados pela gestão — use-os literalmente ao apresentar os números.

Impressões

Quantas vezes os conteúdos da Doka e da Immersi apareceram para pessoas na internet — no Google, via Search Console, e nas redes sociais, com dados inseridos manualmente. Uma impressão não significa clique, apenas que o conteúdo foi exibido. Quanto maior o número, maior o alcance da marca.

Visitantes

Número de usuários únicos que acessaram o site da Doka ou da Immersi no período, obtido via Google Analytics 4. A taxa de conversão mostra quantos por cento das impressões viraram visitas reais.

Leads

Pessoas que preencheram algum formulário no site — catálogo, arquivo técnico, manual ou outro conteúdo. Demonstraram interesse, mas não necessariamente intenção de compra.

MQL

Sigla de Marketing Qualified Lead, ou lead qualificado pelo marketing. Na Doka são as Oportunidades: pessoas que ativamente levantaram a mão demonstrando intenção clara de compra, preenchendo formulários como “Onde Comprar”, a landing page da Oportunidade do Mês ou o WhatsApp. São os leads com maior potencial de virar cliente.

SQL

Sigla de Sales Qualified Lead, ou lead qualificado pelo time de vendas. Na Doka são as negociações classificadas no CRM com nota 4 ou 5 estrelas. Inclui negociações abertas e fechadas.

Vendas digitais

Oportunidades marcadas como “Vendido” no RD Station CRM pela equipe comercial. Atenção: este número não representa faturamento real — é a quantidade de negócios sinalizados como fechados no sistema, incluindo todos os funis anteriores.

4.2Como cada número é calculado

As cinco taxas de conversão

Cada taxa é a etapa seguinte dividida pela etapa anterior, em percentual com uma casa decimal: impressões → visitantes, visitantes → leads, leads → MQL, MQL → SQL, SQL → vendas. Quando a etapa anterior é zero, a taxa é exibida como zero, não como erro.

A taxa mais baixa da coluna indica o maior gargalo do funil — o ponto onde uma ação de marketing tem o maior efeito potencial.

4.3A janela de 45 dias da RD Marketing

O plano contratado da RD Station Marketing só devolve conversões de datas até 45 dias atrás contando de hoje. Esse detalhe é mais traiçoeiro do que parece:

O que o sistema faz diante disso:

1. Calcula quantos dias separam hoje da data inicial pedida.
2. Se for mais de 44, empurra a data inicial para 44 dias atrás e avisa na resposta que o período foi ajustado.
3. Se mesmo essa data ajustada já for posterior ao fim do período pedido — ou seja, o período inteiro está velho demais —, nem chega a chamar a API. Devolve zero e uma nota explicando, e o número passa a depender só do cache, do webhook e dos lançamentos manuais.

Isso evita disparar uma consulta que já se sabe que vai falhar, e é o motivo pelo qual períodos antigos mostram um total de Leads menor do que o real quando não há cache preenchido.

4.4O cache

Cache é uma cópia guardada de uma resposta já obtida, para não precisar perguntar de novo. No Funil Doka o cache mora em duas abas do Google Sheets e segue duas regras:

Sempre que a RD Marketing é consultada com sucesso, o resultado é gravado no cache automaticamente. Cada período tem uma linha; gravar de novo o mesmo período substitui a linha anterior.

4.5A regra “API sempre vence”

Existe um risco embutido no lançamento manual: se um dia uma plataforma social passar a ser lida automaticamente por API, o mesmo dia poderia ser contado duas vezes — uma pela API e outra pelo valor digitado à mão.

Para impedir isso, toda vez que uma consulta de API traz dado real de um dia específico, o sistema anota esse dia numa tabela de cobertura. Na hora de somar as impressões manuais, se qualquer dia do período de um lançamento já estiver anotado como coberto por API, aquele lançamento inteiro é descartado da soma e devolvido à parte, marcado como conflito para revisão humana.

A regra é deliberadamente conservadora: não faz rateio proporcional, não tenta adivinhar quanto do valor pertence a qual dia. Prefere descartar e sinalizar.

4.6Como marca e canal filtram

Marca

Cada etapa separa Doka de Immersi de um jeito diferente, porque as fontes são diferentes:

Canal

O filtro de canal atua só sobre Visitantes. “Pago” são as visitas cuja mídia de sessão é cpc — o que cobre Google Ads, Meta Ads e demais campanhas pagas. “Orgânico” é literalmente todo o resto: busca orgânica, tráfego direto, social não pago, referência e e-mail.

4.7A semana começa na quinta

Na página de lançamento manual, cada semana vai de quinta-feira a quarta-feira. Essa escolha veio da rotina de fechamento do time, não de uma limitação técnica.

Consequências práticas:

• Ao lançar impressões, a data que identifica a semana é sempre a quinta-feira de início.
• O sistema calcula sozinho o fim do período: quinta + 6 dias.
• O mapa de calor das 52 semanas usa essa mesma contagem.
• Quem exportar dados das redes sociais precisa alinhar o recorte da exportação a esse intervalo, ou os números não vão corresponder à semana lançada.

4.8Por que os números divergem de outros relatórios

Divergência entre o painel e a ferramenta original quase sempre tem uma destas oito causas. Antes de abrir um chamado, confira a lista:

5.1Lançar impressões de redes sociais

Quando: toda quinta-feira, referente à semana que acabou de fechar. Quem: qualquer pessoa do marketing. Leva: cerca de dez minutos, a maior parte deles exportando os números de cada rede.

1. Reúna os números nas redes
   Abra o painel de cada rede e anote as impressões (ou alcance, conforme o indicador acordado) do período de quinta a quarta. As oito entradas possíveis são: Instagram Doka, Instagram Immersi, Facebook Doka, Facebook Immersi, Pinterest Doka, YouTube Doka, TikTok Doka e LinkedIn Doka.
2. Abra funildoka.vercel.app/manual
   A aba de impressões já vem selecionada.
3. Escolha a semana no mapa de calor
   As 52 semanas aparecem em blocos. Semanas sem dado ficam claras. Clique na quinta-feira correspondente.
4. Preencha só o que você tem
   Campos deixados em branco são ignorados — não viram zero e não apagam nada. Se você só tem o Instagram nesta semana, preencha só ele.
5. Informe quem está lançando
   Selecione seu nome na lista. Isso vai para o registro de auditoria e permite descobrir depois quem lançou um valor estranho.
6. Salve e confira
   O bloco da semana no mapa de calor muda de cor. Abra o painel principal com o período de 7 dias e confirme que o total de Impressões subiu.

5.2Importar várias semanas por CSV

Quando: ao preencher meses de histórico de uma vez, ou ao migrar de uma planilha antiga.

A primeira linha do arquivo tem os nomes das colunas. A coluna semana é obrigatória e deve conter a quinta-feira no formato ano-mês-dia. As demais são opcionais.

# colunas aceitas — use só as que precisar
semana,instagram_doka,instagram_immersi,facebook_doka,facebook_immersi,
pinterest_doka,youtube_doka,tiktok_doka,linkedin_doka,leads,mqls,sqls,vendas

# exemplo real
semana,instagram_doka,facebook_doka,youtube_doka
2026-08-06,142300,38900,12400
2026-08-13,151200,41100,13850

1. Monte a planilha
   No Excel ou no Google Sheets, com os cabeçalhos exatamente como acima. Salve como CSV separado por vírgula.
2. Envie em /manual
   Use o campo de importação por CSV, na parte de cima da página.
3. Leia o resultado
   O sistema devolve linha a linha: salvo ou ignorado, com o motivo. Datas fora do formato ano-mês-dia são recusadas.
4. Confira no mapa de calor
   As semanas importadas devem ter mudado de cor.

5.3Corrigir ou apagar um lançamento

Corrigir um valor

Basta lançar a mesma semana de novo com o valor certo, seguindo 5.1. O novo valor substitui o antigo.

Apagar uma semana inteira

1. Selecione a semana
   No mapa de calor de /manual.
2. Use o botão de apagar da semana
   Ele remove todas as plataformas daquela semana de uma vez, não uma plataforma isolada.
3. Confirme
   O bloco volta a aparecer como vazio.

5.4Preencher dados antigos de RD

Quando: ao querer ver corretamente um período com mais de 45 dias, que a API da RD já não responde.

A página /manual tem duas abas para isso: uma para RD Marketing (leads e MQLs da semana) e outra para RD CRM (SQLs e vendas, com abertura por funil: Consumidor Final, Arquiteto, E-commerce, Immersi, Construtora e Hotéis).

1. Levante os números na origem
   Exporte da própria RD Station os totais da semana em questão, enquanto ela ainda estiver acessível por lá.
2. Escolha a semana e a aba correspondente
   Lembre: a semana começa na quinta.
3. Preencha e salve
   Esses valores vão para o cache permanente, e o painel passa a usá-los quando aquele período for consultado.

5.5Gerenciar o e-mail semanal

Toda segunda-feira por volta das 8h de Brasília, o sistema envia um resumo dos últimos 7 dias em formato de funil vertical, com as seis etapas, os três principais itens de cada uma e a taxa de conversão entre elas.

Cadastrar alguém

1. Abra funildoka.vercel.app/emails
2. Digite o endereço e confirme
   Endereços repetidos são recusados com aviso.

Remover alguém

Na mesma página, use o botão de remover ao lado do endereço. O efeito é imediato.

Enviar o resumo agora

O botão de envio imediato dispara o mesmo e-mail para toda a lista, com os dados do momento. Útil antes de uma reunião — e para testar se o envio ainda funciona.

5.6Rodar um diagnóstico completo

Faça isso primeiro sempre que algo parecer errado. É o passo inicial de praticamente toda ficha de erro da seção 7.

1. Abra funildoka.vercel.app/api/debug
   A página mostra texto puro, sem formatação. Isso é esperado.
2. Leia o resumo no final
   Há um bloco _summary com quantos testes passaram de um total de sete.
3. Localize o que falhou
   Cada integração aparece com "ok": true ou "ok": false. Quando falha, vem junto a mensagem de erro original da plataforma.
4. Confira as variáveis de ambiente
   No início da resposta há a lista de configurações. Qualquer uma marcada como faltando é a causa mais provável.
5. Vá para a ficha correspondente
   A seção 7.2 liga cada falha a um procedimento.

Existem ainda seis rotas de diagnóstico específicas, uma por integração, descritas em 6.10. Elas mostram todos os campos disponíveis em cada plataforma — úteis para investigar um problema pontual ou avaliar se um dado novo pode ser incorporado.

5.7Registrar o webhook da RD

Situação atual: o receptor de eventos está pronto, testado e no ar. O que falta é avisar a RD Station para começar a enviar os eventos. É uma ação deliberadamente manual — não é automatizada — e precisa ser feita por alguém confortável com chamadas de API.

1. Confira o que já existe
   Abra /api/debug-rd-webhooks. A página lista os webhooks já registrados na conta e mostra, sem enviar nada, o conteúdo exato da requisição que criaria o novo. Só de ler essa página já se sabe se o registro é necessário.
2. Confirme que o endereço responde
   A RD só aceita registrar um webhook depois de verificar que o endereço devolve uma resposta de sucesso. O endereço é funildoka.vercel.app/api/webhooks/rd-mkt.
3. Envie o registro
   É um envio para https://api.rd.services/integrations/webhooks, autenticado com o mesmo token do RD Marketing já usado pelo sistema — não é preciso pedir permissão nova. O conteúdo declara o tipo de evento como conversão de contato, informa o endereço de destino e traz a lista de identificadores de evento da categoria C.
4. Confirme
   Abra /api/debug-rd-webhooks de novo: o novo webhook deve aparecer na lista.
5. Verifique a chegada dos eventos
   Depois de algumas horas, abra a aba Webhook_RD_MKT da planilha. Linhas novas devem estar aparecendo.

Os identificadores da categoria C já confirmados como ausentes do relatório de conversões — e que portanto precisam do webhook — são: onde-comprar-doka, receber-novidades-doka, profissionais-arquitetura, seja-revenda-doka, fale-conosco, onde-comprar-doka-hoteis, onde-comprar-doka-construtoras, whastapp-oportunidade-mes-doka, whastapp-oportunidade-mes-immersi, whatsapp-immersi e botao-whatsapp-site-6c8e4561d65a832ed531.

5.8Trocar uma credencial

Credenciais são as senhas que o sistema usa para conversar com cada plataforma. Elas nunca ficam no código nem neste documento: vivem apenas como variáveis de ambiente na Vercel, em Configurações → Variáveis de Ambiente.

1. Gere o valor novo na plataforma de origem
   Sem apagar o antigo ainda, se a plataforma permitir manter os dois.
2. Atualize a variável na Vercel
   Substitua o valor mantendo exatamente o mesmo nome de variável. Um nome errado é indistinguível de uma variável ausente.
3. Publique de novo
   Esta etapa é obrigatória e a mais esquecida. Alterar o valor na tela da Vercel não atualiza o sistema que já está rodando. É preciso disparar uma nova publicação.
4. Confirme com o diagnóstico
   Abra /api/debug e verifique se a integração voltou a passar.
5. Só então revogue o valor antigo
   Na plataforma de origem.

5.9Publicar uma alteração de código

O sistema publica sozinho: toda alteração enviada ao repositório no GitHub dispara uma nova publicação na Vercel, que leva de um a três minutos.

1. Altere o arquivo
   Pelo próprio site do GitHub, para mudanças pequenas, ou por um editor de código.
2. Descreva a mudança ao salvar
   Uma frase que explique o que mudou e por quê. Quem investigar um problema daqui a um ano vai ler exatamente isso.
3. Acompanhe a publicação
   No painel da Vercel. Se a publicação falhar, o site anterior continua no ar — o sistema não fica quebrado por causa de um erro de digitação.
4. Teste
   Abra o painel, confira os seis números e rode /api/debug.

5.10Dar acesso a uma pessoa nova

Para usar o painel não é preciso acesso nenhum: basta o link. A lista abaixo é para quem vai manter o sistema.

5.11Adicionar uma plataforma social

Exige alteração de código em quatro lugares, na ordem abaixo. É a alteração mais comum e a mais segura de fazer.

1. Cadastre a plataforma no banco
   Insira uma linha na tabela platforms do Postgres, com a chave no padrão rede_marca — por exemplo threads_doka. A terminação _immersi é o que faz o valor entrar no recorte da Immersi.
2. Inclua a chave na lista fechada
   No arquivo lib/manual-impressions-db.js, na lista PLATFORM_KEYS. Chaves fora dessa lista são recusadas com erro — é uma proteção contra erro de digitação, não um obstáculo.
3. Inclua o campo na tela
   No arquivo app/manual/page.js, na lista de plataformas, com nome, marca, ícone e cores.
4. Publique e teste
   Lance um valor de teste, confira que ele soma nas Impressões e depois apague a semana de teste.

5.12Incluir um novo evento como MQL

Quando uma nova landing page ou formulário de alta intenção entra no ar, o identificador do evento precisa ser incluído na lista de MQLs.

1. Descubra o identificador exato
   Abra /api/debug-rd-mkt e localize o nome do evento como a RD o devolve. Copie exatamente, incluindo erros de grafia existentes — a lista atual contém whastapp, com a letra trocada, porque é assim que está cadastrado na RD.
2. Adicione à lista
   No arquivo lib/rd-mkt.js, na lista MQL_EVENT_IDS.
3. Verifique a marca
   Se o nome do evento contiver “doka” ou “immersi”, a classificação por marca é automática. Se não contiver nenhum dos dois, o evento entra só no total geral.
4. Se for de categoria C, inclua também no webhook
   Eventos sem landing page, formulário ou pop-up por trás só chegam por webhook — veja 5.7.
5. Publique e confira
   O evento deve aparecer no detalhamento de Leads.

6.1Mapa de arquivos

Telas que a pessoa vê

Tradutores — cada um conversa com uma plataforma

Configuração e páginas estáticas

6.2Rotas da API

Rotas são endereços internos que o sistema chama sozinho. Só as marcadas como seguras devem ser abertas manualmente no navegador.

6.3Variáveis de ambiente

Configuradas na Vercel, em Configurações → Variáveis de Ambiente. Os valores não aparecem neste documento e não devem aparecer em nenhum outro.

Variáveis que já existiram e não devem voltar, porque pertencem a caminhos abandonados: as do Upstash, as de versão 2 do CRM e as de token e projeto da própria Vercel.

6.4Contas, IDs e propriedades

6.5Banco de dados Postgres

Hospedado na Neon, conectado à Vercel por integração. Três tabelas no esquema público:

Comportamentos que valem saber

• Lançar de novo a mesma plataforma e a mesma semana substitui o valor. Não cria uma segunda linha.
• Por isso o banco guarda sempre o valor atual, e o histórico de correções vive só na planilha de auditoria. Essa divisão foi uma escolha consciente.
• Apagar uma semana remove todas as plataformas daquela semana de uma vez.
• Valores negativos, plataformas fora da lista e datas invertidas são recusados com mensagem clara.

6.6Planilha Google Sheets

Uma única planilha, sete abas. Todas são criadas automaticamente com o cabeçalho correto se não existirem.

6.7Listas fixas dentro do código

Quatro listas estão escritas diretamente no código, não vêm de nenhuma API. Cada uma tem um motivo:

Eventos que contam como MQL — 14 itens, em lib/rd-mkt.js

oportunidade-mes-doka, oportunidade-mes-doka2, whastapp-oportunidade-mes-doka, onde-comprar-doka-hoteis, onde-comprar-doka-construtoras, onde-comprar-doka, fale-conosco, formulario-onde-comprar-doka, onde-comprar-immersi, oportunidade-mes-immersi, whastapp-oportunidade-mes-immersi, oportunidade-falar-consultor-immersi, oportunidade-falar-consultor-metal-rainbow, oportunidade-falar-consultor-air-massage.

Sim, whastapp está com as letras trocadas. É assim que está cadastrado na RD, e o código precisa bater exatamente. Corrigir aqui sem corrigir lá quebraria a contagem.

Campos personalizados do CRM — 7 itens, em lib/rd-crm.js

A versão 1 da API do CRM devolve os campos personalizados como uma lista de códigos hexadecimais, sem nome legível. Por isso existe um mapa fixo de código para nome, confirmado em agosto de 2026 pela rota /api/debug-cf. Os campos mapeados são: área de atuação, produto de interesse, como conheceu a Doka, representante, marca de interesse e cidade — esta última com dois códigos diferentes, porque existem dois campos de cidade no CRM.

Esses códigos só mudam se o campo for apagado e recriado no CRM. Se acontecer, rode /api/debug-cf e atualize o mapa.

Fontes de origem — 18 itens, em lib/rd-crm.js

Mapa de código para nome das fontes de origem, usado pelo painel MQL por Fonte. O sistema tenta primeiro o nome que a API já devolve embutido; o mapa é plano B. Cobre busca orgânica em seis buscadores, busca paga em seis origens, display, social, tráfego direto e Casoca.

Plataformas sociais — 8 itens, em lib/manual-impressions-db.js

instagram_doka, instagram_immersi, facebook_doka, facebook_immersi, pinterest_doka, youtube_doka, tiktok_doka, linkedin_doka. Precisa estar em sintonia com a tabela platforms do banco e com a lista da tela de lançamento — ver 5.11.

6.8Tarefas agendadas

6.9Resposta de /api/funnel

Estrutura devolvida a cada carregamento. Útil para quem for construir algo em cima destes dados.

{
  periodo, startDate, endDate, marca, canal,
  atualizadoEm,                     // data e hora exatas da consulta
  funil: {
    impressoes: { total, doka, immersi, manualSocial,
                  bySocial,         // valor por rede social
                  byPageDoka, byPageImmersi,
                  error, immersiError },
    visitantes: { total, doka, immersi,
                  byChannel, byChannelImmersi, error, immersiError },
    leads:      { total, breakdown, doka, immersi,
                  breakdownDoka, breakdownImmersi,
                  webhookTotal,     // parcela vinda de webhook
                  error },
    mqls:       { total, byAudience, bySource, error, src },
    sqls:       { total, byAudience, error },
    vendas:     { total, byAudience, perdas, error },
    perfilCRM                        // cinco campos do Perfil de Clientes
  },
  conversoes: {
    impressoesParaVisitantes, visitantesParaLeads, leadsParaMqls,
    mqlsParaSqls, sqlsParaVendas
  }
}

Todo campo error vem como nulo quando está tudo certo, ou com a mensagem original da plataforma quando falha. Um total nulo significa “não sei”; zero significa zero de verdade.

6.10Rotas de diagnóstico

Todas devolvem texto puro, sem formatação, e nenhuma altera dado algum.

7.1Como agir diante de um erro

1. Não altere código ainda
   A grande maioria das falhas é de credencial, permissão ou limite de plataforma — nenhuma delas se resolve mexendo no programa.
2. Rode o diagnóstico
   Abra /api/debug. Em trinta segundos você sabe qual das sete integrações falhou e com que mensagem.
3. Descubra se é só você
   Peça a outra pessoa para abrir o painel. Se funciona para ela, o problema é de rede, cache do navegador ou extensão instalada.
4. Localize a ficha
   Use a tabela de 7.2 e siga o procedimento indicado.
5. Confirme a volta ao normal
   Cada ficha diz exatamente como verificar. Sem essa confirmação, você não sabe se resolveu ou se o erro só sumiu por um momento.
6. Registre
   Se foi um erro novo, acrescente uma ficha nova aqui. Documentação de erro envelhece rápido quando ninguém escreve o que aconteceu.

7.2Tabela rápida: sintoma → causa

7.3Fichas de erro detalhadas

7.4Erros silenciosos

Os erros mais perigosos não aparecem na tela. Eles não geram —, não acendem luz vermelha: apenas produzem números menores do que a realidade. Quem apresenta esses números não tem como saber que estão errados.

8.1Rotina de manutenção

8.2Calendário de riscos

Coisas que quebram sozinhas com o tempo, sem ninguém mexer em nada:

8.3Acessos necessários

Para o sistema continuar existindo, pelo menos duas pessoas precisam ter todos os acessos abaixo. Uma só é um ponto único de falha humano.

8.4Checklist de transferência

A transferência está completa quando a pessoa que assume consegue operar, corrigir e alterar o sistema sem precisar falar com quem saiu. Esse é o critério — não “eu expliquei tudo”.

Antes da saída

• Conceder à pessoa que assume os nove acessos de 8.3 e confirmar que cada um funciona, entrando de fato
• Acompanhá-la fazendo um lançamento manual completo sozinha, do começo ao fim
• Acompanhá-la rodando /api/debug e interpretando o resultado
• Acompanhá-la publicando uma alteração pequena e revertendo em seguida
• Percorrer juntos as fichas de erro da seção 7, especialmente E-08, E-14 e E-16
• Ler juntos a lista de decisões já tomadas em 8.6 e explicar o motivo de cada uma
• Repassar as pendências de 8.5 com o estado atual de cada uma
• Confirmar que ela sabe onde as credenciais ficam — e que elas não estão neste documento
• Apresentá-la aos contatos: gestão de CRM, quem administra o Workspace e o suporte da RD
• Atualizar esta documentação com o que mudou durante a passagem

Depois da saída

• Remover os acessos de quem saiu em todas as nove plataformas
• Trocar o segredo das rotas protegidas
• Se a conta de envio de e-mail era pessoal, migrar para uma conta institucional
• Rodar o diagnóstico e confirmar que nada quebrou com a remoção de acessos
• Registrar aqui a data da transferência e quem passou a ser responsável

8.5Pendências e próximos passos

Estado em 10 de setembro de 2026. O funil em si está concluído e em uso — o que segue são frentes abertas.

8.6Decisões já tomadas

Cada linha abaixo custou tempo de investigação, testes com API ao vivo ou conversa com suporte. Refazer qualquer uma delas é desperdício. Se você pensou em mudar algo daqui, leia o motivo primeiro.

Arquitetura

Contagem e dados

Limites confirmados nas plataformas — não insista

Interface

8.7Manter esta documentação viva

Documentação desatualizada é pior que documentação nenhuma: ela é confiável na aparência e errada no conteúdo. Três regras bastam para evitar isso.

Onde este arquivo deve ficar

Publique-o dentro do próprio sistema, na pasta de arquivos públicos, para que fique acessível em funildoka.vercel.app/documentacao.html. Assim ele viaja junto com o código: quem clonar o repositório leva a documentação, e quem abrir o painel encontra o link. Uma cópia solta numa pasta compartilhada se perde na primeira reorganização.

Vale também acrescentar um link para ele no rodapé do painel e no arquivo de apresentação do repositório.