Pipeline Analytics

Métricas detalhadas do pipeline de vendas: dashboard, win rate, velocidade de vendas, análise de conversão e performance da equipe.

Autenticação, visibilidade e período

Todos os endpoints exigem um token de usuário da conta; sem autenticação, a resposta é 401. Nos endpoints que aceitam pipeline_id, um ID inexistente retorna 404 e um agente sem acesso ao pipeline recebe 403. Dashboard, win rate, velocidade e motivos de perda sem filtro usam apenas os pipelines visíveis ao agente. A performance de equipe é uma visão da conta inteira.

Nos cinco endpoints do AnalyticsController documentados abaixo — dashboard, win rate, conversão, velocidade e análise completa — start_date e end_date são interpretados no fuso da conta e expandidos, respectivamente, para início e fim do dia. O padrão vai do início do dia de 30 dias atrás até o fim do dia atual. Nesses endpoints, formato inválido ou start_date maior que end_date retorna 422.

Dashboard

GET/api/v1/accounts/{account_id}/pipeline/analytics/dashboard

Métricas agregadas do dashboard do pipeline (win rate, velocidade, distribuição de leads e resumo).

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`start_date`(query)	`string`	Nao	Início do período. Padrão: início do dia de 30 dias atrás, no fuso da conta.
`end_date`(query)	`string`	Nao	Fim do período. Padrão: fim do dia atual, no fuso da conta.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/analytics/dashboard" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Dashboard agregado (resposta não envolta em data)

json

{
  "win_rate": { "...": "metricas de WinRateCalculator" },
  "sales_velocity": { "...": "metricas de SalesVelocityCalculator" },
  "lead_distribution": {
    "hot": 8, "warm": 18, "cold": 16,
    "average": 52.3, "total": 42, "filter": "all_time"
  },
  "pipeline_summary": {
    "total_open": 28, "total_won": 10, "total_lost": 4, "total_items": 42,
    "filter": "all_time",
    "all_time": { "total_open": 28, "total_won": 10, "total_lost": 4, "total_items": 42 },
    "in_period": { "total_open": 12, "total_won": 5, "total_lost": 2, "total_items": 19 }
  },
  "period": { "start_date": "2026-01-01T00:00:00Z", "end_date": "2026-01-31T23:59:59Z" }
}

Dashboard agregado de um pipeline

GET/api/v1/accounts/{account_id}/pipeline/analytics/pipeline_dashboard

Métricas agregadas e atividade recente paginada de um único pipeline, sem carregar os cards completos.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Sim	Pipeline da conta autenticada e visível ao usuário.
`date_start`(query)	`string (YYYY-MM-DD)`	Nao	Primeiro dia local, inclusivo. Envie junto com date_end; omita ambos para todo o histórico.
`date_end`(query)	`string (YYYY-MM-DD)`	Nao	Último dia local, inclusivo. Envie junto com date_start; omita ambos para todo o histórico.
`activity_page`(query)	`integer`	Nao	Página da atividade recente. Padrão 1; intervalo permitido: 1 a 10000.
`activity_per_page`(query)	`integer`	Nao	Itens de atividade por página. Padrão 10; intervalo permitido: 1 a 50.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/analytics/pipeline_dashboard?pipeline_id=7&date_start=2026-07-01&date_end=2026-07-31" \
  -H "api_access_token: YOUR_TOKEN" | jq .

Fuso, moedas e privacidade

Os limites inclusivos de date_start e date_end usam o fuso de relatórios da conta. As métricas filtram created_at; a atividade recente filtra updated_at.

Valores permanecem separados por moeda. A atividade retorna somente id, título (que pode ser nulo), estágio e data de atualização; não inclui card completo, contato, conversa, descrição, atributos personalizados ou item_details.

200Resposta direta, sem wrapper data ou payload

json

{
  "pipeline_id": 7,
  "metrics": {
    "total_items": 42,
    "active_items": 28,
    "won_items": 10,
    "lost_items": 4,
    "total_value_by_currency": { "BRL": 125000.0, "USD": 9000.0 },
    "average_value_by_currency": { "BRL": 5208.33, "USD": 2250.0 },
    "cards_with_value_count_by_currency": { "BRL": 24, "USD": 4 },
    "cards_with_value_count": 28,
    "items_by_stage": { "Lead": 12, "Qualificado": 12, "Proposta": 8, "Ganho": 10 },
    "average_time_per_stage_days": { "Lead": 3, "Qualificado": 4, "Proposta": 6, "Ganho": 1 },
    "sla_exceeded_total": 3,
    "sla_exceeded_by_stage": { "Lead": 2, "Proposta": 1 }
  },
  "recent_activity": [
    {
      "id": 901,
      "title": "Renovação anual",
      "stage_id": "proposal",
      "stage": "Proposta",
      "updated_at": "2026-07-20T14:30:00Z"
    }
  ],
  "recent_activity_meta": {
    "page": 1,
    "per_page": 10,
    "total_count": 42,
    "total_pages": 5,
    "has_more": true
  },
  "period": {
    "date_start": "2026-07-01",
    "date_end": "2026-07-31",
    "timezone": "America/Sao_Paulo",
    "metrics_field": "created_at",
    "activity_field": "updated_at"
  }
}

Erros e autorização

A rota retorna 401 sem autenticação, 403 quando um agente não pode ver o pipeline, 404 para pipeline inexistente ou de outra conta, e 422 para parâmetro ausente, estruturado, malformado, invertido ou fora dos limites. active_items inclui os status open e o legado active.

Win Rate

GET/api/v1/accounts/{account_id}/pipeline/analytics/win_rate

Análise de taxa de conversão (ganhos vs perdidos).

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`start_date`(query)	`string`	Nao	Início do período. Padrão: início do dia de 30 dias atrás, no fuso da conta.
`end_date`(query)	`string`	Nao	Fim do período. Padrão: fim do dia atual, no fuso da conta.
`pipeline_id`(query)	`integer`	Nao	Filtrar por pipeline

Métricas de Conversão

GET/api/v1/accounts/{account_id}/pipeline/analytics/conversion_metrics

Taxa de conversão entre estágios do pipeline.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Sim	ID do pipeline (obrigatório — sem ele retorna 422)
`start_date`(query)	`string`	Nao	Início do período, expandido para o início do dia no fuso da conta
`end_date`(query)	`string`	Nao	Fim do período, expandido para o fim do dia no fuso da conta

Resposta direta

A resposta deste endpoint não é envolta em data — o corpo JSON retornado pelo serviço de cálculo é renderizado diretamente. O exemplo abaixo é ilustrativo; os campos exatos dependem da versão do ConversionMetricsService.

Velocidade de Vendas

GET/api/v1/accounts/{account_id}/pipeline/analytics/sales_velocity

Análise de velocidade do pipeline (tempo médio por estágio, ciclo de vendas).

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Nao	Filtrar por pipeline
`start_date`(query)	`string`	Nao	Início do período, expandido para o início do dia no fuso da conta
`end_date`(query)	`string`	Nao	Fim do período, expandido para o fim do dia no fuso da conta

Resposta direta

A resposta é o corpo retornado pelo SalesVelocityCalculator, renderizado diretamente (sem wrapper data). Os campos exatos dependem da versão do serviço.

Análise Completa

GET/api/v1/accounts/{account_id}/pipeline/analytics/pipeline_analysis

Análise abrangente do pipeline com tendências e previsões.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Sim	ID do pipeline (obrigatório)
`start_date`(query)	`string`	Nao	Início do período. Padrão: início do dia de 30 dias atrás, no fuso da conta.
`end_date`(query)	`string`	Nao	Fim do período. Padrão: fim do dia atual, no fuso da conta.

Performance da Equipe

GET/api/v1/accounts/{account_id}/pipeline/analytics/team_pipeline

Performance por membro da equipe (agentes e administradores da conta).

200Performance da equipe. top_performer repete o objeto completo do primeiro membro ordenado, ou null quando não há membros.

json

{
  "team": [
    {
      "user_id": 3,
      "user_name": "Maria Santos",
      "avatar_url": "https://...",
      "pipeline_value": 120000.0,
      "deals_count": 8,
      "conversion_rate": 83.3,
      "hot_leads": 5
    }
  ],
  "totals": {
    "total_pipeline_value": 205000.0,
    "total_deals": 20,
    "average_conversion_rate": 71.6,
    "total_hot_leads": 8
  },
  "top_performer": {
    "user_id": 3,
    "user_name": "Maria Santos",
    "avatar_url": "https://...",
    "pipeline_value": 120000.0,
    "deals_count": 8,
    "conversion_rate": 83.3,
    "hot_leads": 5
  },
  "team_size": 2,
  "updated_at": "2026-01-31T12:00:00Z"
}

GET/api/v1/accounts/{account_id}/pipeline/analytics/pipeline/{user_id}

Pipeline individual de um membro.

200Pipeline do usuário (resposta direta, sem wrapper data)

json

{
  "user_id": 3,
  "user_name": "Maria Santos",
  "pipeline": { "total_value": 120000.0, "deals_count": 8, "hot_leads": 5, "warm_leads": 2, "cold_leads": 1 },
  "conversion_rate": 83.3,
  "average_deal_size": 15000.0,
  "won_this_month": 45000.0,
  "forecast": 99960.0
}

Motivos de Perda

GET/api/v1/accounts/{account_id}/pipeline/deal_status/lost_reasons

Análise dos motivos de perda registrados no período.

Contrato de datas desta rota

lost_reasons é atendido pelo DealStatusController, não pelo AnalyticsController. Cada data é interpretada no fuso da conta e expandida para o início ou fim do dia; uma data malformada retorna 422. Esta rota não rejeita especificamente um intervalo em que start_date seja posterior a end_date, portanto envie as datas em ordem. common_reasons não recebe parâmetros de período.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`start_date`(query)	`string`	Nao	Início do período. Padrão: início do dia de 30 dias atrás, no fuso da conta.
`end_date`(query)	`string`	Nao	Fim do período. Padrão: fim do dia atual, no fuso da conta.

GET/api/v1/accounts/{account_id}/pipeline/deal_status/common_reasons

Motivos comuns de perda de deals.

200Motivos comuns (array de objetos com id, label e category)

json

{
  "reasons": [
    { "id": "price", "label": "Preço muito alto", "category": "pricing" },
    { "id": "competitor", "label": "Escolheu concorrente", "category": "competition" },
    { "id": "no_budget", "label": "Sem orcamento", "category": "budget" },
    { "id": "no_response", "label": "Sem resposta", "category": "engagement" }
  ]
}