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 endpoints do AnalyticsController documentados abaixo — dashboard, win rate, conversão, velocidade, análise completa, forecast e exportação — 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 — inclusive no forecast, que valida as duas datas mesmo sem usá-las no cálculo.

Todas as rotas desta página pertencem ao módulo Pipeline Pro: numa conta em que ele está desligado a resposta é 403 com "code": "pipeline_board_disabled".

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.

Forecast de Receita

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

Previsão de receita dos cards em aberto, agrupada por mês da data prevista de fechamento (forecast_close_date), com valores separados por moeda.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Nao	Limita a um pipeline. Inexistente ou de outra conta retorna 404; pipeline que o agente não vê retorna 403. Sem ele, agrega os pipelines visíveis ao usuário (administrador vê todos).
`months_ahead`(query)	`integer`	Nao	Quantos meses olhar à frente a partir de hoje (no fuso da conta). Padrão 6; valores fora de 1 a 24 são ajustados para o limite mais próximo. Valor não inteiro retorna 422.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/pipeline/analytics/forecast?pipeline_id=7&months_ahead=3" \
  -H "api_access_token: YOUR_TOKEN" | jq .

O que entra no cálculo

Entram apenas cards com status open, não removidos, com forecast_close_date dentro da janela (de hoje até hoje + months_ahead meses). O valor de cada card é o da oferta marcada como padrão em item_details, quando existe; senão, expected_revenue.weighted_total pondera esse valor pela probability do card (sem probabilidade definida, conta 100%); raw_total soma o valor cheio.

Moedas diferentes nunca são somadas: quando um mês (ou a janela inteira) mistura moedas, weighted_total, raw_total e currency vêm null, mixed_currency vem true e os valores ficam em by_currency. Sem nenhum card na janela, os totais vêm 0. excluded conta os cards em aberto sem data prevista (e, entre eles, os sem valor); warning é um texto em português quando há cards sem data prevista, ou null.

200Forecast (resposta direta, sem wrapper data)

json

{
  "monthly": {
    "2026-10": {
      "cards": 4,
      "weighted_total": 18500.0,
      "raw_total": 32000.0,
      "currency": "BRL",
      "mixed_currency": false,
      "by_currency": {
        "BRL": { "cards": 4, "weighted_total": 18500.0, "raw_total": 32000.0 }
      }
    }
  },
  "total": {
    "cards": 4,
    "weighted_total": 18500.0,
    "raw_total": 32000.0,
    "currency": "BRL",
    "mixed_currency": false,
    "by_currency": {
      "BRL": { "cards": 4, "weighted_total": 18500.0, "raw_total": 32000.0 }
    }
  },
  "excluded": {
    "open_without_forecast_date": 3,
    "open_without_forecast_value": 1
  },
  "warning": "3 cards em aberto sem previsão de fechamento foram ignorados no forecast.",
  "period": { "start_date": "2026-09-27", "end_date": "2026-12-27", "months_ahead": 3 }
}

Exportar Relatório (CSV)

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

Baixa em CSV os números do relatório de um pipeline: indicadores do período e a quebra por etapa. Não exporta os cards.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`pipeline_id`(query)	`integer`	Sim	Pipeline da conta. Ausente retorna 422; inexistente ou de outra conta, 404; agente sem acesso ao pipeline, 403.
`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/export?pipeline_id=7&start_date=2026-09-01&end_date=2026-09-30" \
  -H "api_access_token: YOUR_TOKEN" -o pipeline-7.csv

200Arquivo text/csv (pipeline-{id}-{AAAA-MM-DD}.csv): duas seções separadas por uma linha vazia

json

Metric,Value
Pipeline,Vendas
Period start,2026-09-01
Period end,2026-09-30
Total items,42
Active items,28
Won in period,5
Lost in period,2
Total value (BRL),125000.0
Average value (BRL),5208.33
Cards with value (BRL),24

Stage,Cards parked now,Average time (days),Conversion in period (%),Bottleneck risk
Lead,12,3.0,45.0,low
Ganho,10,1.0,,

Leitura das colunas

A primeira seção reúne os indicadores do pipeline no período e repete as três linhas de valor para cada moeda presente. A segunda traz uma linha por etapa. Quando a conversão ou o risco de gargalo não se aplicam à etapa (etapa de desfecho, última etapa do funil, ou etapa sem tráfego no período), a célula vem vazia — nunca 0. Células de texto que começam com caracteres de fórmula de planilha são prefixadas com apóstrofo.

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" }
  ]
}