Metrik · Painel Comercial

🚀 Conectar outra conta Kommo

passo a passo pra integrar uma nova conta

1
Crie uma Integração no Kommo

Acesse o Kommo da conta que vai conectar e vá em:

Configurações → Integrações → +Criar integração → Privada

Preencha o redirect URI exatamente com:
```
https://<seu-dominio>/api/auth/kommo/callback
```
Permissões: marca todos os escopos disponíveis. Se for usar painel Equipe, o token precisa ser de um usuário admin do Kommo (caso contrário o endpoint /users retorna 403).
2
Pegue o Client ID e Secret

Depois de criar, o Kommo mostra na aba "Chaves e escopos":
- ID da integração (Client ID — UUID)
- Chave secreta (Client Secret)
- Subdomínio (parte antes de .kommo.com)
3
Cadastre no servidor (env var Vercel)

No painel do Vercel deste projeto, em Settings → Environment Variables, edita a variável KOMMO_CLIENTS_JSON e adiciona o cliente novo:
```
{
  "minhaempresa": {
    "id": "uuid-da-integração",
    "secret": "chave-secreta",
    "name": "Minha Empresa"
  }
}
```
A chave do objeto é o subdomínio Kommo. Pra adicionar mais contas, é só incluir mais entradas no mesmo JSON. Depois clica em Redeploy pro Vercel pegar o env novo.
4
Conecte a conta

Manda o link abaixo pra quem vai conectar (precisa estar logado no Kommo da conta dela):
```
https://<seu-dominio>/connect/<subdominio>
```
Ou clica no botão "Conectar conta" no canto superior direito do dashboard — ele abre direto a tela de OAuth do Kommo.
5
Pronto — auto-discovery roda sozinho

Depois do OAuth, o dashboard detecta automaticamente:
- Pipelines e estágios (mapeamento padrão pra "novo / qualificado / consulta / contrato / perdido")
- Custom fields (área/categoria, valor, origem, tipo de serviço)
- Usuários e groups (se token for admin)
Se algo precisar ajuste manual, vem listado em "Avisos do Auto-Discovery" abaixo. As outras seções dessa tela permitem refinar o mapeamento.

🔌 Conta Conectada

OAuth Kommo · token & switcher

⚠ Avisos do Auto-Discovery

revise o que precisa ser corrigido

📖 Regras de Configuração no Kommo

como deixar sua conta Kommo preparada pro dashboard puxar dados corretos

Leia antes de rodar a Descoberta Automática. Se sua conta Kommo não seguir essas regras, alguns widgets vão ficar vazios ou com dados parciais. Não dá pra adivinhar o que não está no CRM.

1

Pipeline organizado e nomes claros nos estágios

O dashboard mapeia cada estágio do Kommo pra uma das 5 fases: Novo · Qualificado · Consulta · Contrato · Perdido.

✅ Bons exemplos

Lead novo, Entrada, Captação → Novo
Qualificação, Triagem, Pré-venda → Qualificado
Reunião agendada, Consulta marcada, Apresentação → Consulta
Contrato fechado, Cliente, Ganho, Vendido → Contrato
Perdido, Cancelado, Não qualificado → Perdido

❌ Evite

Nomes genéricos: Etapa 1, Status A, Custom 1
Estágios técnicos misturados (ZapSign, Webhook) — marque como "Ignorar" no mapeamento
Múltiplos estágios pra "vendido" sem usar o tipo nativo Kommo

Dica crítica: no Kommo, o estágio que representa "venda fechada" precisa estar marcado como tipo "Won" (e o de perda como "Lost"). Isso é nativo — quando você cria/edita um pipeline, esses dois estágios aparecem separados no fim. Se você usar um estágio "open" pra contrato, o sistema não consegue distinguir 100% sem mapping manual.

2

Custom Fields obrigatórios — TIPO correto importa

O dashboard espera 4 custom fields no Kommo (em Configurações → Leads → Campos personalizados). O tipo de cada um precisa ser exatamente o esperado, senão o widget bugga.

Campo no dashboard	Tipo no Kommo	Exemplo de nome	Valores permitidos
Área / Categoria	Lista (select / radio)	Área de Interesse, Especialidade, Motivação, Tipo de Tratamento	Lista FECHADA: ex. Cardiologia, Dermatologia, Pediatria ou Trabalhista, Cível, Família
Valor / Ticket	Numérico	Valor do contrato, Ticket, Honorário	Número (1500, 2500.50). Não use "R$ 1.500" como texto.
Origem do Lead	Lista (select)	Origem, Canal, De onde veio	Lista FECHADA: Meta Ads, Google Ads, WhatsApp, Indicação, Site, Orgânico
Tipo de Serviço	Lista (select)	Modalidade, Plano, Forma de cobrança	Lista FECHADA: Mensal, Único, Pacote, Por sessão, Êxito

⚠ Erro mais comum: criar o campo "Área de Interesse" como tipo texto (livre). Cada vendedor digita do jeito dele ("trabalhsta", "Trabalhista", "trabalho", "TRABALHISTA"...) e o widget vira uma floresta de barras impossível de ler.

Solução: mudar o campo pra tipo Lista com opções fixas. Quem tá usando o campo errado, edita os leads antigos pra preencher com a opção correta.

3

Preenchimento — todo lead precisa ter os campos

Custom field vazio = lead some das contagens. Pra evitar:

Marca os 4 campos como obrigatórios em pelo menos um estágio (ex: obrigatório no estágio "Qualificado" pra avançar)
No Kommo: Configurações → Leads → Campos personalizados → editar campo → marca "Obrigatório no estágio X"
Faz uma limpeza nos leads antigos preenchendo os 4 campos antes de rodar o Discovery
Treina a equipe pra não pular o preenchimento — leads sem campo viram dado fantasma

4

Tags — convenção pra IA e origem

O dashboard reconhece tags com nomes específicos automaticamente:

Tag IA é a mais importante: todo lead atendido pela sua IA precisa ter uma dessas tags. Se sua automação cria o lead, configura ela pra adicionar a tag ia automaticamente.

5

Integrações ativas (Source nativo do Kommo)

Quando um lead vem de integração oficial (Facebook Lead Ads, WhatsApp Chat, Google Forms, formulário web), o Kommo registra automaticamente em _embedded.source.name. O dashboard usa isso no widget "Fonte de Entrada (Kommo nativo)".

Mantém todas as integrações conectadas e ativas no Kommo
Lead criado manualmente NÃO tem fonte preenchida — daí entra a regra do custom field "Origem" (regra 2) ou tag (regra 4) como fallback

6

Permissões da integração privada

Quando você criou a integração no Kommo (passo 1 do "Conectar conta"), precisa marcar TODAS as permissões disponíveis:

CRM (obrigatório — sem isso nada funciona)
Files + Files delete
Push notifications + Notifications

⚠ Importante: a integração precisa ser criada por um usuário admin do Kommo. Se for criada por usuário comum, a view "Equipe" não funciona (Kommo retorna 403 "Admin access only" no endpoint /users).

🔍 Descoberta Automática

escaneia sua conta Kommo e sugere todo o mapeamento (estágios, custom fields, áreas, tags)

Clica em "Escanear minha conta" e a gente analisa os últimos 90 dias da sua conta Kommo pra detectar:

Estágios do funil → mapeamento sugerido pra novo/qualif./consulta/contrato/perdido
Custom fields → quais são área/categoria, valor, origem, tipo de serviço
Áreas / categorias mais usadas
Tags com papel detectado (origem, IA, segmentação)
Widgets que vão funcionar (com dado real) vs os que não

Demora ~10s. Não modifica nada na sua conta — só lê. Sem PII de clientes na resposta.

🎯 Mapeamento de Estágios

qual stage Kommo = qual fase do funil

📋 Custom Fields

aponta os campos: área, valor, origem, tipo

👔 Equipe — Funções

classifica usuários: SDR / Atendente / Vendedor

🧮 Campos Personalizados

crie métricas customizadas com fórmulas (sum, avg, count) sobre os dados do CRM

⚙ Configurações Gerais

SLA, período padrão

Leads · Oportunidades de Vendas

Atendimento · Tempo de Resposta

Análise Comercial

Análise de Atendimento

Análise Operacional

Clientes · Consultas e Contratos

Equipe · Performance por Usuário

Painel de Agendamento · Consultas

Marketing · Captação

Vendas · Receita · Conversão

Vendas Ganhas — Breakdown

Vendas Perdidas — Breakdown

IA · Leads atendidos por Inteligência Artificial

Configurações · Integração Kommo