Leads del CRM

Con /external/v1/leads tu aplicación lee y trabaja los leads del CRM de UTILIA OS de forma controlada y auditada. Sirve a herramientas de prospección (Apollo, Cognism, Lusha), a plataformas que sincronizan con otro CRM (HubSpot, Pipedrive, Salesforce) y a herramientas de soporte que necesitan ver la captación.

Autenticación

Todas las peticiones llevan la clave de API de la aplicación:

X-Api-Key: <api_key_de_la_app>

La clave se obtiene al dar de alta la aplicación en Aplicaciones externas, necesitas entrar con tu cuenta y puedes rotarla desde su ficha sin reescribir tu aplicación.

Permisos de la API (scopes)

Sin el permiso necesario, la respuesta es 403 con errorCode: INSUFFICIENT_SCOPE.

crm:leads:convert y crm:leads:read:notes son permisos críticos: concederlos a una aplicación exige el rol de Super Administrador y un motivo de al menos 20 caracteres. Además, cada llamada a /convert exige su propio reason con esa misma longitud mínima.

Endpoints

Qué puede cambiar tu aplicación

Desde la API, un lead se cualifica, se descarta o se convierte. Los estados Contactado y Negociando los pone tu equipo desde el CRM.

La sincronización funciona igual que la de clientes: lo explica Sincronizar por cambios.

Cuerpo de las acciones

• qualify: reason (hasta 500 caracteres) y source, que admite external_app, crm_sync, manual o automation.
• disqualify: reason (hasta 500 caracteres) y source, con los mismos valores más bounce.
• convert: reason (de 20 a 1.000 caracteres), createOpportunity (opcional, false por defecto) y targetClientId (opcional): la ficha de cliente existente a la que vincular el contacto. Sin targetClientId, se crea un cliente nuevo con los datos del lead.

Forma de las respuestas:

• Listados: { data, pagination: { page, limit, total, totalPages, hasNextPage, hasPreviousPage } }.
• Cambios: { lead, changed, recordedAt }. changed=false cuando el lead ya estaba en el estado pedido.
• Sincronización: { data, nextCursor, hasMore }.
• Conversión: { lead, contactId, opportunityId?, clientId?, createdAt }.

Los campos personalizados del CRM no salen por esta API. Puedes leerlos y escribirlos por MCP: lo explica el apartado «Campos personalizados del CRM» de la referencia MCP.

Ejemplos

# Listar leads activos
curl -H "X-Api-Key: $KEY" \
  "https://os.utilia.ai/api/external/v1/leads?limit=25"
 
# Cualificar un lead
curl -X POST \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Pidió una demostración y encaja en el perfil","source":"external_app"}' \
  "https://os.utilia.ai/api/external/v1/leads/ld-42/qualify"
 
# Convertir (no se puede deshacer)
curl -X POST \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Aceptó la propuesta económica y empezamos la implantación","createOpportunity":true}' \
  "https://os.utilia.ai/api/external/v1/leads/ld-42/convert"

// SDK JavaScript
import { UtiliaSDK } from '@utilia-os/sdk-js';
 
const sdk = new UtiliaSDK({ baseURL: 'https://os.utilia.ai/api', apiKey: KEY });
 
const page = await sdk.externalLeads.list({ limit: 25 });
 
await sdk.externalLeads.qualify('ld-42', {
  reason: 'Pidió una demostración y encaja en el perfil',
  source: 'external_app',
});
 
const conv = await sdk.externalLeads.convert('ld-42', {
  reason: 'Aceptó la propuesta económica y empezamos la implantación',
  createOpportunity: true,
});

# SDK Python
from utilia_sdk import (
    ConvertLeadInput,
    ExternalLeadListFilters,
    QualifyLeadInput,
    UtiliaSDK,
)
 
async with UtiliaSDK(base_url="https://os.utilia.ai/api", api_key=KEY) as sdk:
    page = await sdk.external_leads.list(ExternalLeadListFilters(limit=25))
 
    await sdk.external_leads.qualify(
        "ld-42",
        QualifyLeadInput(
            reason="Pidió una demostración y encaja en el perfil",
            source="external_app",
        ),
    )
 
    conv = await sdk.external_leads.convert(
        "ld-42",
        ConvertLeadInput(
            reason="Aceptó la propuesta económica y empezamos la implantación",
            create_opportunity=True,
        ),
    )

Avisos a tu servidor de lead

Seis eventos a los que puedes suscribir la aplicación desde su ficha. Si el cambio lo hizo tu propia aplicación, no le llega el aviso; al resto de aplicaciones suscritas, sí.

Errores propios de estos endpoints

Límites de uso

Al superar un límite, la API responde 429 con la cabecera Retry-After, que indica los segundos que faltan para que se renueve.

Con los SDK oficiales

• JavaScript (@utilia-os/sdk-js): sdk.externalLeads con once métodos: list, get, search, byEmail, sync, qualify, disqualify, convert, create, update y updateScore.
• Python (utilia-sdk): sdk.external_leads con los mismos once métodos, en versión asíncrona y síncrona.

Las versiones de los dos SDK están en un único sitio: Versiones y compatibilidad. Consúltalo antes de fijar la dependencia de tu proyecto.

Decisiones de producto

• No hay DELETE sobre leads desde fuera: la única baja es /disqualify, que pasa el lead a LOST.
• /convert no se puede deshacer: crea un contacto y, si lo pides, una oportunidad.
• Las notas internas del lead solo salen con su permiso propio (crm:leads:read:notes).

Cada cambio queda en el registro de auditoría con la dirección IP y el cliente que lo hizo, y cada organización solo ve sus propios leads.

Siguiente paso

Tras integrar la lectura, suscribe la aplicación a los eventos LEAD_* desde su ficha para mantener la captación sincronizada sin consultar la API cada poco. Para trabajar también con la ficha de cliente vinculada, consulta Clientes del CRM; el catálogo completo de eventos está en Contenido de los avisos.