API de leads

Crear un lead#

Envía un objeto JSON con action: "create_lead" y los datos del lead en data. Necesitas una API key de la organización.

Encabezados

Cuerpo

Ejemplo

curl -X POST https://api.yavehome.com/api/v1/webhooks/custom \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YAVE_API_KEY" \
  -H "X-Webhook-Source: sitio-web" \
  -d '{
  "action": "create_lead",
  "data": {
    "name": "Laura Gómez",
    "phone": "+57 300 123 4567",
    "email": "[email protected]",
    "source": "LANDING",
    "sourceId": "form-8812",
    "budget": 350000000,
    "utm_source": "facebook",
    "utm_medium": "paid",
    "utm_campaign": "torre-2-preventa",
    "tags": ["Torre 2", "Preventa"],
    "customFields": {
      "proyecto_interes": "Torre 2",
      "tipologia": "Apartamento 3 alcobas",
      "mensaje": "¿Tienen financiación directa?"
    }
  }
}'

Respuesta

201 Created cuando se crea un lead nuevo:

{
  "status": "success",
  "leadId": "b1f3c6e2-7a0d-4c1e-9d55-2f8e0a4b7c19",
  "assignedTo": "5d0e9a41-…",
  "message": "Lead created and assigned successfully"
}

Si ya existía un lead con el mismo teléfono (ver duplicados), la respuesta es el lead existente, con su identificador en id en lugar de leadId. Para guardar el identificador en tu sistema, lee leadId ?? id.

Qué pasa cuando entra un lead#

1. Normalización: el teléfono se lleva a formato internacional.
2. Deduplicación: si el teléfono ya existe en la organización, no se crea otro lead (ver abajo).
3. Asignación: se asigna un asesor con la estrategia de la organización (rotación equitativa por defecto). Si la organización asigna a mano, el lead queda sin asesor.
4. Embudo: las reglas de enrutamiento de la organización eligen el embudo según source, utm_source y utm_campaign. Sin regla, va al embudo del equipo del asesor asignado.
5. Automatizaciones e IA: se dispara el evento lead creado: notificaciones al asesor, primer contacto por WhatsApp con IA, nutrición y demás flujos que la organización tenga activos.

Duplicados#

YAVE identifica a las personas por teléfono. Si llega un lead cuyo teléfono (en cualquiera de sus variantes: con o sin indicativo) ya existe en la organización:

• No se crea un lead nuevo ni cambia el asesor asignado.
• Si el lead existente no tenía correo, se completa con el que envías. Si su nombre era genérico, se reemplaza por el tuyo.
• Se vuelve a notificar la entrada, para que el asesor sepa que la persona volvió a escribir.

Sin teléfono no hay deduplicación: cada envío crea un lead. Por eso conviene exigir el teléfono en tus formularios.

Reintentos#

Si recibes un 5xx o un 429, o la conexión se corta, reintenta con espera exponencial (por ejemplo 2 s, 8 s, 30 s). Como la deduplicación es por teléfono, un reintento de un lead con teléfono no crea un duplicado. No reintentes los 4xx (salvo 429): el problema está en la petición. Detalles en Errores y límites.

Zapier, Make, n8n y Dapta#

No necesitas escribir código: todas estas herramientas pueden hacer una petición HTTP.

1. Método POST, URL https://api.yavehome.com/api/v1/webhooks/custom.
2. Encabezados: X-API-Key con la clave y Content-Type con application/json.
3. Cuerpo (JSON / raw): el mismo del ejemplo, mapeando los campos de tu disparador (nombre, teléfono, correo…) dentro de data.
4. Prueba el paso y verifica en el CRM que el lead apareció.

Alternativas sin API key#

• Formularios de YAVE: incrustables en cualquier sitio, con validación, consentimiento y atribución incluidos.
• Webhook de automatización: una URL propia de un flujo, útil cuando quieres que un evento externo haga algo más que crear el lead.