Eventos de contacto

Los eventos permiten decirle a Nexus que algo ocurrió en relación con un contacto. Conectan acciones que suceden fuera del CRM, como una compra, una reserva o una visita relevante, con el historial y las automatizaciones de Nexus.

Algunos ejemplos de claves de evento:

demo_solicitada
compra_realizada
turno_agendado
carrito_abandonado
plan_actualizado
whatsapp_iniciado

Definición y ocurrencia

Crear un evento en Configuración → Eventos genera una definición reutilizable con nombre, clave y descripción. La definición por sí sola no ejecuta ninguna acción.

Cada vez que un sistema registra ese evento para un contacto se crea una ocurrencia con fecha, origen y datos adicionales. Esa ocurrencia puede:

aparecer en el historial del contacto;
iniciar un workflow con el trigger Evento registrado;
reanudar un nodo Esperar evento;
incluir o excluir al contacto de una audiencia dinámica;
aportar contexto a campañas e informes.

Registrar un evento no modifica automáticamente campos, etiquetas, lifecycle ni deals. Para producir esos cambios, configurá un workflow que reaccione al evento.

Crear una definición

Abrí Configuración → Eventos.
Seleccioná Nuevo evento.
Escribí un nombre claro para el equipo.
Definí una clave estable, por ejemplo turno_agendado.
Agregá una descripción que indique exactamente cuándo debe registrarse.
Mantenelo activo y guardá.

La clave forma parte del contrato con el sistema externo. Evitá cambiarla una vez que la integración esté en producción.

Autenticación desde un sistema externo

Creá una clave en Configuración → Claves de API y guardala en el servidor que realizará la integración. Nunca expongas la clave en un frontend, repositorio, URL o documento público.

Nexus acepta cualquiera de estos encabezados:

X-API-Key: TU_API_KEY

Authorization: Bearer TU_API_KEY

Registrar un evento por email

Enviá una solicitud POST a /v1/crm/contact-events/ingest:

curl --request POST "https://TU_API_NEXUS/v1/crm/contact-events/ingest" \
  --header "X-API-Key: TU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventKey": "demo_solicitada",
    "email": "cliente@empresa.com",
    "source": "sitio_web",
    "occurredAt": "2026-09-17T14:30:00.000Z",
    "payload": {
      "producto": "Agente comercial",
      "pagina": "/agentes-complejos",
      "utmCampaign": "ventas-septiembre"
    }
  }'

Identificar al contacto

La ingestión acepta uno de estos identificadores:

Campo	Cuándo usarlo
`contactId`	Cuando el sistema externo ya conserva el UUID del contacto en Nexus. Es la opción más precisa.
`email`	Para formularios, ecommerce, reservas y otros sistemas cuyo identificador principal es el correo.
`phone`	Para WhatsApp, SMS, voz u operaciones centradas en el número telefónico.

Si enviás contactId, Nexus lo usa como identificación prioritaria. El contacto debe existir previamente. Si no se encuentra, la API responde 404 Contact not found y no crea uno automáticamente.

Ejemplo por teléfono:

{
  "eventKey": "whatsapp_iniciado",
  "phone": "+5493515555555",
  "source": "whatsapp",
  "payload": {
    "campana": "reactivacion"
  }
}

Ejemplo por ID:

{
  "eventKey": "compra_realizada",
  "contactId": "UUID-DEL-CONTACTO",
  "source": "ecommerce",
  "payload": {
    "orderId": "ORD-1052",
    "amount": 150000,
    "currency": "ARS"
  }
}

Registrar sobre un contacto conocido

Si ya conocés el UUID, también podés usar el endpoint específico:

POST /v1/crm/contacts/{contactId}/events

{
  "eventKey": "turno_agendado",
  "source": "sistema_turnos",
  "payload": {
    "especialidad": "Cardiología",
    "fecha": "2026-09-22T15:00:00.000Z"
  }
}

Campos del evento

Campo	Requerido	Descripción
`eventKey`	Sí, salvo que uses `definitionId`	Clave de una definición activa del mismo workspace.
`contactId`, `email` o `phone`	Sí en ingest	Identifica al contacto que recibirá el evento.
`source`	No	Sistema o canal que originó el dato, como `ecommerce`, `whatsapp` o `sitio_web`.
`occurredAt`	No	Fecha ISO 8601 del hecho. Si se omite, Nexus usa el momento de recepción.
`payload`	No	Objeto JSON con datos propios del caso de uso.

Usá payload para información que describe la ocurrencia, como importe, producto, campaña, sucursal o identificador externo. No incluyas secretos ni datos personales que no sean necesarios.

Usarlo en automatizaciones

Creá o editá un workflow.
Elegí el trigger Cuando se registra un evento de contacto.
Seleccioná la definición concreta. Si no elegís una, el workflow escuchará todos los eventos de contacto.
Agregá las acciones necesarias.
Probá el flujo con un contacto controlado antes de activarlo.

Ejemplo operativo:

demo_solicitada → asignar vendedor → crear actividad → enviar email → actualizar la oportunidad.

También podés usar Esperar evento en un workflow ya iniciado. El flujo queda pausado hasta que el contacto reciba la señal esperada o se alcance el tiempo máximo configurado.

Buenas prácticas

Elegí claves en minúsculas y con guion bajo.
Usá una definición para un hecho de negocio concreto.
Conservá la misma clave entre ambientes cuando represente el mismo hecho.
Enviá occurredAt cuando el hecho pueda llegar con demora.
Documentá los campos esperados dentro de payload.
Evitá que los reintentos del sistema externo generen acciones duplicadas.
Probá contacto, evento y workflow dentro del mismo workspace.
Desactivá una definición antes de retirar una integración.

Diagnóstico rápido

Respuesta o síntoma	Qué revisar
`401 Missing authorization`	Falta la API key o el encabezado es incorrecto.
`404 Contact not found`	El ID, email o teléfono no coincide con un contacto existente.
`400 Debes indicar un evento válido del tenant`	La clave no existe en ese workspace o no se envió `eventKey`.
El evento se registra pero no hay acciones	El workflow no está activo, escucha otra definición o sus filtros no coinciden.
El evento está inactivo	Reactivá la definición o actualizá la integración para usar otra clave.

Checklist antes de producción

La definición existe y está activa.
La API key pertenece al workspace correcto.
El contacto se resuelve con un identificador estable.
El origen y el payload están documentados.
El workflow fue probado con un contacto controlado.
Los reintentos no provocan acciones comerciales duplicadas.