Analítica de oportunidades

Esta página documenta los endpoints que alimentan la vista Análisis de Oportunidades en el CRM. Si buscas el recorrido funcional por las vistas y la pestaña Equipo, empieza por Oportunidades.

Autenticación, permisos y plan

Son endpoints de la API del panel, bajo /api/crm/opportunities: se llaman con la sesión de un usuario (Authorization: Bearer <token>), no con la clave de API de una aplicación externa. Cada endpoint exige su permiso, y el alcance del usuario (OWN, ASSIGNED, DEPARTMENT o ALL) se aplica en el servidor: importes y recuentos representan siempre solo la parte que ese usuario puede ver. Los campos de importe solo salen con OPPORTUNITIES_VIEW_FINANCIALS.

Listado y contadores

GET /api/crm/opportunities

Permiso: OPPORTUNITIES_VIEW.

Listado paginado de oportunidades dentro del alcance del usuario. Parámetros que usa la vista Análisis:

• team (boolean): con true, filtra las oportunidades asignadas a compañeros del mismo departamento, sin las del propio usuario. Exige OPPORTUNITIES_VIEW_TEAM_PIPELINE; sin él, responde 403.
• status, stage, stages[], priority, type, assignedTo, clientId, contactId, createdById, search, minValue, maxValue, expectedCloseDateFrom, expectedCloseDateTo, actualCloseDateFrom, actualCloseDateTo, page, limit, sortBy y sortOrder.

status admite un valor o varios, en cualquiera de estas formas equivalentes: ?status=OPEN, ?status=OPEN&status=WON o ?status=OPEN,WON. Lo mismo vale para los contadores y la exportación.

GET /api/crm/opportunities/assignment-counts

Permiso: OPPORTUNITIES_VIEW.

Devuelve en una sola petición los recuentos del selector Mías / Equipo / Todas, con los mismos filtros opcionales que el listado.

{
  "mine": 12,
  "team": 28,
  "all": 47
}

Si el usuario no tiene OPPORTUNITIES_VIEW_TEAM_PIPELINE, team vale siempre 0: no hay error, y la interfaz oculta la pestaña.

GET /api/crm/opportunities/recommendations

Permiso: OPPORTUNITIES_VIEW.

Hasta cinco recomendaciones ordenadas por gravedad:

La lista de oportunidades ya no muestra este bloque, pero el endpoint sigue activo: lo usan el detalle de la oportunidad, el bloque «¿Y ahora?» y las aplicaciones que lo consultan por SDK o MCP.

Embudo y conversión

GET /api/crm/opportunities/pipeline/stats

Permiso: OPPORTUNITIES_VIEW.

Estadísticas de las oportunidades abiertas. conversionRate es la tasa real (won / (won + lost + abandoned)) sobre los mismos filtros que el listado, y solo sale con OPPORTUNITIES_VIEW_FINANCIALS.

{
  "totalOpportunities": 47,
  "totalValue": 184500,
  "totalExpectedRevenue": 92750,
  "averageProbability": 41.2,
  "conversionRate": 31.4,
  "stageBreakdown": [
    { "stage": "QUALIFICATION", "count": 10, "totalValue": 32000, "totalExpectedRevenue": 6400, "averageProbability": 20 },
    { "stage": "NEEDS_ANALYSIS", "count": 9, "totalValue": 27000, "totalExpectedRevenue": 10800, "averageProbability": 40 },
    { "stage": "PROPOSAL", "count": 12, "totalValue": 41000, "totalExpectedRevenue": 24600, "averageProbability": 60 },
    { "stage": "NEGOTIATION", "count": 11, "totalValue": 52000, "totalExpectedRevenue": 36400, "averageProbability": 70 },
    { "stage": "CLOSING", "count": 5, "totalValue": 32500, "totalExpectedRevenue": 14550, "averageProbability": 90 }
  ]
}

stageBreakdown da el recuento, el valor y la probabilidad por etapa.

GET /api/crm/opportunities/analytics/conversion

Permiso: OPPORTUNITIES_VIEW. Importes solo con OPPORTUNITIES_VIEW_FINANCIALS.

Conversión histórica agregada:

{
  "totalCreated": 120,
  "totalWon": 38,
  "totalLost": 52,
  "totalAbandoned": 12,
  "conversionRate": 31.6,
  "averageCycleDays": 27.4,
  "averageWonValue": 2950
}

GET /api/crm/opportunities/analytics/funnel

Permiso: OPPORTUNITIES_VIEW.

Embudo por etapa de las oportunidades creadas en el periodo (period: 30d, 90d o 365d; por defecto 90d) dentro del embudo elegido (pipelineId; por defecto, el de tu organización). Cada oportunidad cuenta una sola vez, en la etapa más alta que alcanzó, así que las reaperturas no inflan las cifras. Devuelve la conversión entre etapas seguidas, el tiempo medio por etapa (las estancias aún abiertas aparte, como «en curso») y la tasa de cierre. Respeta el alcance del usuario.

GET /api/crm/opportunities/analytics/forecast

Permiso: OPPORTUNITIES_FORECAST_VIEW.

Previsión de ingresos de las oportunidades abiertas con fecha de cierre prevista dentro de los próximos periodMonths meses (por defecto 6). Las que no tienen fecha de cierre prevista no entran.

{
  "period": "6_months",
  "byMonth": [
    { "month": "2026-05", "expectedRevenue": 12500, "count": 7 },
    { "month": "2026-06", "expectedRevenue": 18900, "count": 9 }
  ],
  "byStage": [
    { "stage": "PROPOSAL", "count": 12, "totalExpectedRevenue": 24600 }
  ],
  "confidenceLevels": [
    { "level": 50, "expectedRevenue": 47200, "count": 28 },
    { "level": 70, "expectedRevenue": 31800, "count": 19 },
    { "level": 90, "expectedRevenue": 18450, "count": 11 }
  ]
}

confidenceLevels es una lista; los antiguos campos sueltos confidence50, confidence70 y confidence90 ya no existen.

Salud del embudo

GET /api/crm/opportunities/analytics/stale-detection

Permiso: OPPORTUNITIES_VIEW.

Edad media por etapa y recuento de oportunidades estancadas y vencidas. Las fechas se calculan en la zona horaria de tu organización.

{
  "stageAging": [
    { "stage": "QUALIFICATION", "avgDaysInStage": 6.2, "staleCount": 1 },
    { "stage": "NEEDS_ANALYSIS", "avgDaysInStage": 11.8, "staleCount": 2 },
    { "stage": "PROPOSAL", "avgDaysInStage": 18.3, "staleCount": 5 },
    { "stage": "NEGOTIATION", "avgDaysInStage": 22.5, "staleCount": 4 },
    { "stage": "CLOSING", "avgDaysInStage": 9.1, "staleCount": 0 }
  ],
  "overallStaleCount": 12,
  "overdueCount": 4
}

• avgDaysInStage: media de días desde la última actualización, con un decimal.
• staleCount: oportunidades abiertas en la etapa con más de 14 días sin actualizarse.
• overallStaleCount: total de estancadas dentro del alcance del usuario.
• overdueCount: oportunidades abiertas con expectedCloseDate anterior a hoy.

GET /api/crm/opportunities/analytics/loss-reasons

Permiso: OPPORTUNITIES_VIEW.

Los diez motivos de pérdida más frecuentes del periodo. El resto, y los motivos escritos a mano fuera del catálogo, se suman en una fila OTHER.

{
  "reasons": [
    { "reason": "Precio fuera de presupuesto", "count": 12, "totalLostValue": 48200 },
    { "reason": "Plazo de entrega no compatible", "count": 9, "totalLostValue": 31500 },
    { "reason": "Cliente eligió competidor", "count": 7, "totalLostValue": 22100 },
    { "reason": "OTHER", "count": 14, "totalLostValue": 18900 }
  ],
  "totalLost": 42,
  "period": "90d"
}

GET /api/crm/opportunities/analytics/top-contributors

Permiso: OPPORTUNITIES_VIEW_TEAM_PIPELINE.

Los diez comerciales con más valor ganado en el periodo. Solo cuentan las oportunidades WON con actualCloseDate dentro del periodo.

{
  "contributors": [
    {
      "userId": "ckxxx...",
      "fullName": "María López",
      "avatar": "https://...",
      "wonCount": 8,
      "wonValue": 42500,
      "avgDealSize": 5312.5
    }
  ],
  "period": "90d"
}

Sin OPPORTUNITIES_VIEW_TEAM_PIPELINE responde 403, y la interfaz oculta la tarjeta: es información del departamento, no de cada comercial.

Exportación

GET /api/crm/opportunities/export

Permiso: OPPORTUNITIES_EXPORT.

Descarga un CSV con las oportunidades que el usuario puede ver, con los mismos filtros que el listado. UTF-8 con BOM (Excel lo abre bien), un máximo de 10.000 filas y fechas en la zona horaria de tu organización.

Errores frecuentes

Avisos a tu servidor

El catálogo de avisos no incluye eventos de oportunidad (OPPORTUNITY_WON y OPPORTUNITY_LOST no existen). El cierre de una oportunidad se ve a través de las entidades conectadas: cuando una oportunidad ganada da lugar a un presupuesto o a una factura, las aplicaciones suscritas reciben los eventos BUDGET_* e INVOICE_* correspondientes. El catálogo completo está en Contenido de los avisos.

Desde código

• MCP: herramienta crm_opportunities_stats, con las operaciones assignment_counts, recommendations, get_pipeline_stats, get_forecast, get_timeline, funnel, analytics_stale_detection, analytics_loss_reasons y analytics_top_contributors.
• SDK: ejemplos en Oportunidades con el SDK.