📊 Documentação da API - Quantificadores e Métricas de Analytics

Endpoints

KPIs Gerais

GET /api/gestor/v1/analytics/kpis

Análise de Cancelamento (Churn)

GET /api/gestor/v1/analytics/churn

Funil de Conversão

GET /api/gestor/v1/analytics/funnel

Timeline de Leads

GET /api/gestor/v1/analytics/timeline

Fontes de Leads

GET /api/gestor/v1/analytics/sources

Descrição

Estas rotas fornecem métricas quantitativas e analíticas essenciais para monitoramento de performance, análise de funil de vendas e identificação de oportunidades de melhoria. Todos os endpoints consultam dados consolidados no DuckDB Analytics com cache otimizado para alta performance.

Características principais:

✅ Dados em tempo real com cache inteligente
✅ Filtros globais por data, fonte, agente e tipo de cliente
✅ Multi-tenant com isolamento automático
✅ Suporte a análises comparativas

🔐 Autenticação

Todas as rotas requerem autenticação via token JWT e api-key.

Headers obrigatórios:

api-key: <sua-api-key>

🌐 Hostnames

DEV:

VPN: 100.113.139.94:3002
PUBLIC: 136.116.58.209:3002

URLs Completas de Exemplo (DEV):

http://136.116.58.209:3002/api/gestor/v1/analytics/kpis
http://136.116.58.209:3002/api/gestor/v1/analytics/churn
http://136.116.58.209:3002/api/gestor/v1/analytics/funnel
http://136.116.58.209:3002/api/gestor/v1/analytics/timeline
http://136.116.58.209:3002/api/gestor/v1/analytics/sources

📥 Parâmetros Globais (Query Parameters)

Todos os endpoints aceitam os seguintes filtros opcionais:

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`startDate`	string	Não	Data inicial do período (formato YYYY-MM-DD)	`2026-01-10`
`endDate`	string	Não	Data final do período (formato YYYY-MM-DD)	`2026-02-09`
`source`	string	Não	Filtrar por origem/fonte específica	`site`, `indicacao`
`agentId`	number	Não	Filtrar por ID do colaborador/agente	`19`
`customerType`	string	Não	Filtrar por tipo de cliente (`PF` ou `PJ`)	`PF`

Parâmetros Específicos

`/analytics/timeline`

Parâmetro	Tipo	Obrigatório	Descrição	Valores Aceitos	Padrão
`period`	string	Não	Granularidade temporal	`day`, `week`, `month`	`month`

📤 Respostas de Sucesso

1. KPIs Gerais (`/analytics/kpis`)

Status Code: 200 OK

{
  "success": true,
  "data": {
    "totalLeads": 1250,
    "activeLeads": 487,
    "convertedLeads": 206,
    "lostLeads": 312,
    "overallConversionRate": 16.5,
    "avgLeadsPerDay": "41.7",
    "periodStart": "2026-01-10",
    "periodEnd": "2026-02-09",
    "topSource": "Site Institucional"
  },
  "meta": {
    "tenant": "384577",
    "generatedAt": "2026-02-09T15:30:45.123Z",
    "cached": false
  }
}

Descrição dos campos:

Campo	Tipo	Descrição
`totalLeads`	number	Total de leads no período
`activeLeads`	number	Leads em negociação ou proposta (etapas 2 e 3)
`convertedLeads`	number	Leads convertidos (etapa 4 - Finalizados)
`lostLeads`	number	Leads perdidos/desistentes (etapa 5)
`overallConversionRate`	number	Taxa de conversão geral (%)
`avgLeadsPerDay`	string	Média de leads por dia no período
`periodStart`	string	Data inicial do período analisado
`periodEnd`	string	Data final do período analisado
`topSource`	string	Fonte com maior volume de leads

2. Análise de Cancelamento (`/analytics/churn`)

Status Code: 200 OK

{
  "success": true,
  "data": {
    "totalActive": 487,
    "churned30Days": 42,
    "churnRate": 8.6,
    "avgDaysToChurn": 12.5,
    "minDaysToChurn": 1,
    "maxDaysToChurn": 45,
    "atRiskLeads": [
      {
        "id": 12345,
        "long_id": "cf9fab22-1a15-4f22-a9c6-50c47798a6ac",
        "name": "Maria Silva Santos",
        "email": "[email protected]",
        "phone": "11999887766",
        "originConsolidated": "Site",
        "corretor_nome": "Paloma Soares",
        "days_inactive": 15,
        "etapa_kanban": 2,
        "riskScore": 0.5,
        "recommendedAction": "Personalized email with new offers"
      }
    ],
    "summary": {
      "highRisk": 8,
      "mediumRisk": 15,
      "lowRisk": 19
    }
  },
  "meta": {
    "tenant": "384577",
    "generatedAt": "2026-02-09T15:30:45.123Z",
    "cached": false
  }
}

Descrição dos campos:

Campo	Tipo	Descrição
`totalActive`	number	Total de leads ativos no funil (etapas 1, 2, 3)
`churned30Days`	number	Leads que foram perdidos nos últimos 30 dias
`churnRate`	number	Taxa de cancelamento (%)
`avgDaysToChurn`	number	Tempo médio até cancelamento (dias)
`minDaysToChurn`	number	Menor tempo até cancelamento
`maxDaysToChurn`	number	Maior tempo até cancelamento
`atRiskLeads`	array	Lista de até 50 leads em risco (sem atividade ≥7 dias)
`summary`	object	Resumo por nível de risco

Campos do objeto atRiskLeads:

Campo	Tipo	Descrição
`id`	number	ID do lead
`long_id`	string	Long ID (UUID) do lead
`name`	string	Nome do lead
`email`	string	E-mail do lead
`phone`	string	Telefone do lead
`originConsolidated`	string	Origem consolidada do lead
`corretor_nome`	string	Nome do corretor responsável
`days_inactive`	number	Dias sem atividade
`etapa_kanban`	number	Etapa atual no kanban
`riskScore`	number	Pontuação de risco (0.0 a 1.0)
`recommendedAction`	string	Ação recomendada para reativação

3. Funil de Conversão (`/analytics/funnel`)

Status Code: 200 OK

{
  "success": true,
  "data": [
    {
      "etapa": 0,
      "etapaName": "Não Distribuídos",
      "count": 125,
      "percentage": 10.0
    },
    {
      "etapa": 1,
      "etapaName": "Leads Atribuídos",
      "count": 320,
      "percentage": 25.6
    },
    {
      "etapa": 2,
      "etapaName": "Negociação",
      "count": 280,
      "percentage": 22.4
    },
    {
      "etapa": 3,
      "etapaName": "Proposta",
      "count": 207,
      "percentage": 16.6
    },
    {
      "etapa": 4,
      "etapaName": "Finalizados",
      "count": 206,
      "percentage": 16.5
    },
    {
      "etapa": 5,
      "etapaName": "Desistências",
      "count": 112,
      "percentage": 8.9
    }
  ],
  "total": 1250,
  "meta": {
    "tenant": "384577",
    "generatedAt": "2026-02-09T15:30:45.123Z",
    "cached": false
  }
}

Descrição dos campos:

Campo	Tipo	Descrição
`etapa`	number	Código da etapa do kanban (0-5)
`etapaName`	string	Nome descritivo da etapa
`count`	number	Quantidade de leads nesta etapa
`percentage`	number	Percentual do total de leads (%)
`total`	number	Total geral de leads considerados

Mapeamento de etapas:

0: Não Distribuídos
1: Leads Atribuídos
2: Negociação
3: Proposta
4: Finalizados (Convertidos)
5: Desistências (Perdidos)

4. Timeline de Leads (`/analytics/timeline`)

Status Code: 200 OK

{
  "success": true,
  "data": [
    {
      "period": "2026-01",
      "total": 542,
      "converted": 89,
      "lost": 47,
      "inProgress": 280
    },
    {
      "period": "2026-02",
      "total": 708,
      "converted": 117,
      "lost": 65,
      "inProgress": 387
    }
  ],
  "meta": {
    "tenant": "384577",
    "period": "month",
    "generatedAt": "2026-02-09T15:30:45.123Z",
    "cached": false
  }
}

Descrição dos campos:

Campo	Tipo	Descrição
`period`	string	Período (formato varia conforme granularidade)
`total`	number	Total de leads criados no período
`converted`	number	Leads convertidos (etapa 4)
`lost`	number	Leads perdidos (etapa 5)
`inProgress`	number	Leads em negociação ou proposta (etapas 2 e 3)

Formatos de period por granularidade:

day: 2026-02-09
week: 2026-W06 (ano e número da semana)
month: 2026-02 (ano e mês)

5. Fontes de Leads (`/analytics/sources`)

Status Code: 200 OK

{
  "success": true,
  "data": [
    {
      "source": "Site Institucional",
      "total": 485,
      "converted": 82,
      "lost": 41,
      "inProgress": 240,
      "conversionRate": 16.9,
      "pfCount": 320,
      "pjCount": 165
    },
    {
      "source": "Indicação",
      "total": 342,
      "converted": 68,
      "lost": 28,
      "inProgress": 180,
      "conversionRate": 19.9,
      "pfCount": 285,
      "pjCount": 57
    },
    {
      "source": "Parceiro Comercial",
      "total": 215,
      "converted": 31,
      "lost": 19,
      "inProgress": 120,
      "conversionRate": 14.4,
      "pfCount": 88,
      "pjCount": 127
    }
  ],
  "meta": {
    "tenant": "384577",
    "generatedAt": "2026-02-09T15:30:45.123Z",
    "cached": false
  }
}

Descrição dos campos:

Campo	Tipo	Descrição
`source`	string	Nome da origem/fonte do lead
`total`	number	Total de leads desta fonte
`converted`	number	Leads convertidos (etapa 4)
`lost`	number	Leads perdidos (etapa 5)
`inProgress`	number	Leads em negociação/proposta (etapas 2 e 3)
`conversionRate`	number	Taxa de conversão desta fonte (%)
`pfCount`	number	Quantidade de leads Pessoa Física
`pjCount`	number	Quantidade de leads Pessoa Jurídica

❌ Respostas de Erro

500 - Internal Server Error

Retornado em caso de erro no processamento dos dados analíticos.

{
  "success": false,
  "error": "Error querying analytics database: Connection timeout"
}

📊 Exemplos de Uso

Exemplo 1: KPIs do período com filtro de data

Request:

curl -X GET "http://136.116.58.209:3002/api/gestor/v1/analytics/kpis?startDate=2026-01-10&endDate=2026-02-09" \
  -H "Authorization: Bearer seu-token-jwt" \
  -H "api-key: sua-api-key"

Response:

{
  "success": true,
  "data": {
    "totalLeads": 1250,
    "activeLeads": 487,
    "convertedLeads": 206,
    "overallConversionRate": 16.5,
    "topSource": "Site Institucional"
  }
}

Exemplo 2: Análise de churn (últimos 30 dias)

Request:

curl -X GET "http://136.116.58.209:3002/api/gestor/v1/analytics/churn" \
  -H "Authorization: Bearer seu-token-jwt" \
  -H "api-key: sua-api-key"

Response:

{
  "success": true,
  "data": {
    "totalActive": 487,
    "churned30Days": 42,
    "churnRate": 8.6,
    "atRiskLeads": [...]
  }
}

Exemplo 3: Funil de conversão filtrado por tipo PF

Request:

curl -X GET "http://136.116.58.209:3002/api/gestor/v1/analytics/funnel?customerType=PF&startDate=2026-01-01" \
  -H "Authorization: Bearer seu-token-jwt" \
  -H "api-key: sua-api-key"

Exemplo 4: Timeline semanal

Request:

curl -X GET "http://136.116.58.209:3002/api/gestor/v1/analytics/timeline?period=week&startDate=2026-01-01&endDate=2026-02-09" \
  -H "Authorization: Bearer seu-token-jwt" \
  -H "api-key: sua-api-key"

Exemplo 5: Fontes filtradas por agente específico

Request:

curl -X GET "http://136.116.58.209:3002/api/gestor/v1/analytics/sources?agentId=19&startDate=2026-01-10" \
  -H "Authorization: Bearer seu-token-jwt" \
  -H "api-key: sua-api-key"

🔄 Fluxo de Processamento

Fluxo Geral (todos os endpoints)

Autenticação: Valida token JWT via middleware verificaToken
Identificação de Tenant: Extrai ANS do tenant da configuração da requisição
Cache Check: Verifica se há dados em cache válidos (TTL variável por endpoint)
Build Filters: Monta cláusula WHERE com filtros globais:
- Tenant ANS (sempre obrigatório)
- Range de datas (startDate/endDate)
- Fonte/origem (source)
- Colaborador (agentId)
- Tipo de cliente (customerType)
Query DuckDB: Executa consulta SQL otimizada no DuckDB Analytics
Processamento: Formata e enriquece dados conforme necessário
Cache Store: Armazena resultado em cache com TTL apropriado
Response: Retorna JSON padronizado com metadados

Fluxo Específico - Churn Analysis

Consulta leads ativos (etapas 1, 2, 3)
Consulta leads perdidos nos últimos 30 dias
Calcula taxa de churn e tempo médio até perda
Identifica leads em risco (≥7 dias sem atividade)
Calcula riskScore para cada lead em risco
Classifica por nível de risco (alto/médio/baixo)
Sugere ação recomendada baseada no riskScore

🚀 Cache e Performance

Estratégia de Cache

Cada endpoint possui um TTL (Time To Live) otimizado:

Endpoint	TTL	Justificativa
`/kpis`	10 min	Dados mudam frequentemente
`/churn`	10 min	Análise de risco requer atualização regular
`/funnel`	10 min	Funil é consultado constantemente
`/timeline`	15 min	Dados históricos mudam menos
`/sources`	15 min	Distribuição por fonte é mais estável

Tempo Médio de Resposta

Endpoint	Com Cache	Sem Cache	Cold Start
`/kpis`	50-100ms	300-500ms	800ms-1.2s
`/churn`	80-150ms	500-800ms	1-1.5s
`/funnel`	40-80ms	200-400ms	600ms-1s
`/timeline`	60-120ms	300-600ms	900ms-1.3s
`/sources`	70-140ms	400-700ms	1-1.4s

Otimizações Implementadas

✅ Cache em memória com TTL por endpoint
✅ Queries SQL otimizadas com índices apropriados
✅ Agregações no banco de dados (não em aplicação)
✅ Limit automático em queries longas
✅ Conexão persistente com DuckDB

🔐 Segurança

✅ Autenticação JWT obrigatória via middleware verificaToken
✅ Isolamento multi-tenant automático (filtro por ANS)
✅ Validação de entrada de parâmetros
✅ Proteção contra SQL injection (queries parametrizadas)
✅ Rate limiting via cache service

🔧 Middlewares Aplicados

verificaToken: Validação de token JWT e identificação de tenant
cacheService.middleware: Cache inteligente com TTL configurável por endpoint

📝 Notas Importantes

Multi-tenant: Todos os endpoints filtram automaticamente por tenant ANS da requisição
Data Format: Datas devem ser fornecidas no formato ISO YYYY-MM-DD
Cache Behavior: Primeira requisição pode ser mais lenta (cold start), requisições subsequentes usam cache
Risk Score Calculation: No endpoint de churn, o riskScore é calculado como min(1.0, days_inactive / 30)
Timeline Periods:
- day: Retorna dados diários
- week: Retorna dados por semana (formato ISO: YYYY-W##)
- month: Retorna dados mensais (formato: YYYY-MM)
Conversion Rate: Taxa de conversão é calculada como (convertidos / total) * 100
Empty Results: Se não houver dados para o período/filtros, retorna arrays vazios com success: true
DuckDB Source: Todos os dados vêm do DuckDB Analytics (sincronizado periodicamente)
Churn Definition: Lead é considerado "churned" quando move para etapa 5 (Desistências)
At-Risk Threshold: Leads sem atividade há 7+ dias são considerados em risco

🔗 Rotas Relacionadas

GET /api/gestor/v1/analytics/agents - Performance por colaborador
GET /api/gestor/v1/analytics/customer-type - Distribuição PF vs PJ
GET /api/gestor/v1/analytics/cancellation-reasons - Motivos de cancelamento
GET /api/gestor/v1/analytics/campaigns - Performance de campanhas
GET /api/gestor/v1/analytics/duplicates - Detecção de leads duplicados
GET /api/gestor/v1/analytics/kanban/by-source - Kanban por fonte
GET /api/gestor/v1/analytics/kanban/by-collab - Kanban por colaborador

📌 Versão da API

Versão: 2.0 (DuckDB Analytics)
Última Atualização: Fevereiro de 2026
Mantido por: Equipe de Desenvolvimento UNI API
Arquivos:

Routes: analytics.routes.js, analytics-advanced.routes.js
Controllers: analytics.controller.js, analytics-advanced.controller.js
Services: analytics-proxy.service.js, analytics-cache.service.js

Endpoints​

KPIs Gerais​

Análise de Cancelamento (Churn)​

Funil de Conversão​

Timeline de Leads​

Fontes de Leads​

Descrição​

🔐 Autenticação​

🌐 Hostnames​

📥 Parâmetros Globais (Query Parameters)​

Parâmetros Específicos​

/analytics/timeline​

📤 Respostas de Sucesso​

1. KPIs Gerais (/analytics/kpis)​

2. Análise de Cancelamento (/analytics/churn)​

3. Funil de Conversão (/analytics/funnel)​

4. Timeline de Leads (/analytics/timeline)​

5. Fontes de Leads (/analytics/sources)​

❌ Respostas de Erro​

500 - Internal Server Error​

📊 Exemplos de Uso​

Exemplo 1: KPIs do período com filtro de data​

Exemplo 2: Análise de churn (últimos 30 dias)​

Exemplo 3: Funil de conversão filtrado por tipo PF​

Exemplo 4: Timeline semanal​

Exemplo 5: Fontes filtradas por agente específico​

🔄 Fluxo de Processamento​

Fluxo Geral (todos os endpoints)​

Fluxo Específico - Churn Analysis​

🚀 Cache e Performance​

Estratégia de Cache​

Tempo Médio de Resposta​

Otimizações Implementadas​

🔐 Segurança​

🔧 Middlewares Aplicados​

📝 Notas Importantes​

🔗 Rotas Relacionadas​

📌 Versão da API​

Endpoints

KPIs Gerais

Análise de Cancelamento (Churn)

Funil de Conversão

Timeline de Leads

Fontes de Leads

Descrição

🔐 Autenticação

🌐 Hostnames

📥 Parâmetros Globais (Query Parameters)

Parâmetros Específicos

`/analytics/timeline`

📤 Respostas de Sucesso

1. KPIs Gerais (`/analytics/kpis`)

2. Análise de Cancelamento (`/analytics/churn`)

3. Funil de Conversão (`/analytics/funnel`)

4. Timeline de Leads (`/analytics/timeline`)

5. Fontes de Leads (`/analytics/sources`)

❌ Respostas de Erro

500 - Internal Server Error

📊 Exemplos de Uso

Exemplo 1: KPIs do período com filtro de data

Exemplo 2: Análise de churn (últimos 30 dias)

Exemplo 3: Funil de conversão filtrado por tipo PF

Exemplo 4: Timeline semanal

Exemplo 5: Fontes filtradas por agente específico

🔄 Fluxo de Processamento

Fluxo Geral (todos os endpoints)

Fluxo Específico - Churn Analysis

🚀 Cache e Performance

Estratégia de Cache

Tempo Médio de Resposta

Otimizações Implementadas

🔐 Segurança

🔧 Middlewares Aplicados

📝 Notas Importantes

🔗 Rotas Relacionadas

📌 Versão da API