Oportunidades

Lee desde el SDK los contadores, las acciones recomendadas, la salud del pipeline y los motivos de pérdida de las oportunidades del CRM, por MCP.

Actualizado el 9 de octubre de 2026. 3 min de lectura

Incluido en el plan Avanzado. Ver precios

sdk.mcp.opportunities lleva a tu integración las cifras que el CRM enseña en Oportunidades, necesitas entrar con tu cuenta: cuántas son tuyas, de tu equipo o de todos; qué conviene hacer hoy; qué oportunidades están estancadas o vencidas; por qué se pierden y quién gana más. Todo llega por el carril MCP, con la herramienta crm_opportunities_stats del servidor del CRM, y en nombre de una persona: necesitas su sesión OAuth.

Casi todo exige Analítica avanzada del CRM

Todos los métodos de esta página salvo listStages() usan la herramienta crm_opportunities_stats, que solo funciona si el plan de tu organización incluye Analítica avanzada del CRM. listStages() usa otra herramienta, crm_opportunities, y le basta con que el plan incluya Oportunidades. Si falta la capacidad, la herramienta responde con un error que explica qué falta. No se resuelve dando permisos, sino ampliando el plan: lo detalla Errores de plan.

Antes de empezar

Credencial: el carril MCP actúa en nombre de una persona, así que el SDK tiene que estar configurado con OAuth. Con la clave de una aplicación externa (X-Api-Key) el servidor MCP rechaza la petición.
Scope del token: crm:opportunities:view (o un conjunto que lo incluya, como crm:read o crm:full).
Permisos de la persona: «Ver oportunidades» (OPPORTUNITIES_VIEW) para casi todo; «Ver pipeline del equipo» (OPPORTUNITIES_VIEW_TEAM_PIPELINE) para los mejores contribuidores; y «Ver información financiera de oportunidades» (OPPORTUNITIES_VIEW_FINANCIALS) para las cifras económicas de getPipelineStats y getForecast.

Si falta un permiso, el servidor responde con un mensaje en castellano que lo explica y el SDK lo lanza como UtiliaSDKError: captúralo y enséñalo.

Qué	JavaScript	Python
Contadores «Mías», «Equipo» y «Todas»	`assignmentCounts(filtros?)`	`assignment_counts(filtros)`
Acciones recomendadas para hoy	`recommendations()`	`recommendations()`
Oportunidades estancadas y vencidas	`analyticsStaleDetection()`	`analytics_stale_detection()`
Motivos de pérdida más frecuentes	`analyticsLossReasons(periodo)`	`analytics_loss_reasons(periodo)`
Mejores contribuidores	`analyticsTopContributors(periodo)`	`analytics_top_contributors(periodo)`
Estadísticas del pipeline	`getPipelineStats()`	`get_pipeline_stats()`
Previsión	`getForecast(meses?)`	`get_forecast(months)`
Actividad de una oportunidad	`getTimeline(...)`	`get_timeline(...)`
Etapas configuradas	`listStages()`	`list_stages()`

En JavaScript cada método devuelve { data }; en Python, directamente el modelo con los campos en snake_case. getPipelineStats, getForecast y getTimeline devuelven un objeto sin tipar: su contrato aún puede cambiar.

Ejemplo

import { UtiliaSDK } from '@utilia-os/sdk-js';
 
const sdk = new UtiliaSDK({
  baseURL: 'https://os.utilia.ai/api',
  oauth: { clientId: process.env.UTILIA_CLIENT_ID!, redirectUri: 'http://localhost:3000/callback' },
});
 
const { data: counts } = await sdk.mcp.opportunities.assignmentCounts({ status: ['OPEN'] });
console.log(counts.mine, counts.team, counts.all); // team vale 0 sin permiso de equipo
 
const { data: recs } = await sdk.mcp.opportunities.recommendations();
for (const item of recs.items) console.log(item.type, item.priority, item.title);
 
const { data: health } = await sdk.mcp.opportunities.analyticsStaleDetection();
console.log('Estancadas:', health.overallStaleCount, 'Vencidas:', health.overdueCount);
 
const { data: losses } = await sdk.mcp.opportunities.analyticsLossReasons('90d');
for (const r of losses.reasons) console.log(r.reason, r.count, r.totalLostValue);

Las recomendaciones son hasta cinco fichas ordenadas por gravedad, con type igual a overdue (vencida), won_no_invoice (ganada sin factura), aging (envejecida), won_no_project (ganada sin proyecto) o budget_pending (presupuesto pendiente): cada una apunta al siguiente paso natural del ciclo de venta.

No hay un método para la tasa de conversión suelta: viene dentro de getPipelineStats(), con el permiso «Ver información financiera de oportunidades».

Sin el SDK

Si tu copiloto habla MCP directamente, el contrato es el mismo: la herramienta crm_opportunities_stats en POST /api/mcp/crm, con operation igual a assignment_counts, recommendations, analytics_stale_detection, analytics_loss_reasons, analytics_top_contributors, get_pipeline_stats, get_forecast o get_timeline. Las etapas salen de la herramienta crm_opportunities, con operation igual a list_stages.

HTTP

POST /api/mcp/crm
Content-Type: application/json
Authorization: Bearer <token>
 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crm_opportunities_stats",
    "arguments": { "operation": "analytics_loss_reasons", "period": "90d" }
  }
}

Siguiente paso

En esta página