Relatório do funil
GET /analytics/reports/funnel — entradas, saídas e tempo por etapa, e envelhecimento dos negócios abertos por etapa e por responsável.
/analytics/reports/funnelBetaEscopo necessário: analytics:read
Responde quantos negócios entraram e saíram de cada etapa na janela, quanto tempo ficaram nela antes de sair e há quantos dias os negócios abertos estão na etapa atual. O mesmo envelhecimento vem por responsável. O relatório é agregado: não traz contatos nem negócios individuais.
Endpoint
GET https://crm.oficinamartech.com/api/v1/analytics/reports/funnelParâmetros de query
| Parâmetro | Tipo | Descrição |
|---|---|---|
days | int (1-90) | Janela em dias. Default: 30. Termina no fim de hoje, no fuso da organização. |
pipeline_id | UUID | Um funil específico. Sem o filtro, entram só os funis ativos. Um funil de outra organização devolve listas vazias. |
Um parâmetro fora desta lista é recusado com 400.
A janela termina no fim de hoje no fuso da organização (window.timezone). window.start é o primeiro dia e window.end é o dia seguinte ao último dia da janela. A resposta usa Cache-Control: private, no-store.
Exemplo
curl -s "https://crm.oficinamartech.com/api/v1/analytics/reports/funnel?days=30" \
-H "Authorization: Bearer crm_live_SEU_PREFIXO_SEU_SEGREDO"Resposta 200
{
"captured_at": "2026-11-13T15:20:41.318Z",
"window": {
"days": 30,
"timezone": "America/Sao_Paulo",
"start": "2026-10-15",
"end": "2026-11-14"
},
"pipelines": [
{
"pipeline_id": "9b1c0f52-58cc-4372-a567-0e02b2c3d479",
"pipeline_name": "Vendas",
"stages": [
{
"stage_id": "5a7e1d20-58cc-4372-a567-0e02b2c3d479",
"stage_name": "Qualificação",
"position": 1,
"kind": "open",
"entries": 84,
"exits": 61,
"measured_exits": 58,
"avg_hours": 52.4,
"median_hours": 30.1,
"p90_hours": 140.7,
"open": 23,
"open_0_7": 12,
"open_8_14": 5,
"open_15_30": 4,
"open_31_plus": 1,
"open_unknown_age": 1,
"open_avg_days": 8.3,
"open_oldest_days": 36,
"without_next_followup": 6,
"overdue_followup": 3
}
]
}
],
"operators": [
{
"operator_id": "11111111-58cc-4372-a567-0e02b2c3d479",
"operator_name": "Ana Souza",
"open": 14,
"open_0_7": 8,
"open_8_14": 3,
"open_15_30": 2,
"open_31_plus": 0,
"open_unknown_age": 1,
"open_avg_days": 6.1,
"open_oldest_days": 24,
"without_next_followup": 2,
"overdue_followup": 1
}
]
}Campos
| Campo | Definição |
|---|---|
captured_at | Instante em que o relatório foi calculado (UTC). |
window | days, timezone (fuso da organização), start (primeiro dia) e end (dia seguinte ao último). |
pipelines[].stages[].kind | open, won ou lost. |
entries | Negócios que entraram na etapa na janela (criação ou mudança de etapa). |
exits | Negócios que saíram da etapa na janela. |
measured_exits | Saídas cuja entrada está registrada. Só elas entram em avg_hours, median_hours e p90_hours; as demais ficam fora dos três. |
avg_hours, median_hours, p90_hours | Tempo na etapa antes de sair, em horas. null quando não há saída medida. |
open | Negócios abertos hoje na etapa (ou com o responsável, em operators). |
open_0_7, open_8_14, open_15_30, open_31_plus | Abertos por dias na etapa atual: 0–7, 8–14, 15–30 e 31 ou mais. |
open_unknown_age | Abertos sem registro de entrada na etapa atual. Ficam fora das faixas e de open_avg_days. |
open_avg_days, open_oldest_days | Média e máximo de dias na etapa atual. null quando nenhum aberto tem idade conhecida. |
without_next_followup | Abertos sem próximo contato agendado. |
overdue_followup | Abertos com o próximo contato vencido. |
operators[].operator_id, operator_name | Responsável pelo negócio. operator_id null agrupa os negócios sem responsável. |
Os campos de open_*, without_next_followup e overdue_followup descrevem o estado atual e não dependem da janela. entries, exits e os tempos usam a janela.
Erros
| Status | Código | Quando |
|---|---|---|
400 | invalid_query | days fora de 1–90, pipeline_id malformado ou parâmetro desconhecido. |
401 | missing_api_key / invalid_api_key | API key ausente, inválida, expirada ou revogada. |
403 | missing_scope | A chave não tem o escopo analytics:read. |
413 | report_too_large | O relatório passou do limite de tamanho. Informe pipeline_id para ler um funil por vez. |
429 | rate_limited | Acima de 120 req/min por chave ou por organização. |
500 | — | Erro interno. |
Um nome de relatório desconhecido no caminho responde 404 not_found.