> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos personalizados y objetivos

> Registra el comportamiento de los usuarios y sus objetivos de conversión para crear segmentos RFM y completar la cronología de los contactos.

## Descripción general

Los eventos personalizados registran acciones de los usuarios que vienen de sistemas externos (comercio electrónico, CRM, analítica). Aparecen en la cronología del contacto, y sus objetivos te permiten crear segmentos RFM (Recencia, Frecuencia, Monetario).

## Cronología del contacto

Cada evento personalizado crea una entrada en la cronología del contacto, así que ves el historial completo de sus interacciones:

![Cronología de un contacto con eventos personalizados](https://www.notifuse.com/docs/assets/screenshots/custom_event_timeline.png)

Cada evento muestra su `event_name` como tipo de la entrada en la cronología (por ejemplo, "order.completed", "subscription.started"). El campo `properties` guarda contexto adicional, visible en los detalles de la entrada.

## Tipos de objetivo

Los segmentos se basan en los objetivos. Cada evento puede registrar un objetivo:

| Tipo           | Caso de uso                                   | goal_value  |
| -------------- | --------------------------------------------- | ----------- |
| `purchase`     | Pedidos de comercio electrónico, pagos únicos | Obligatorio |
| `subscription` | Suscripciones SaaS, membresías                | Obligatorio |
| `lead`         | Formularios de contacto, solicitudes de demo  | Opcional    |
| `signup`       | Registros de cuentas                          | Opcional    |
| `booking`      | Citas, consultas                              | Opcional    |
| `trial`        | Activaciones de pruebas gratuitas             | Opcional    |
| `other`        | Eventos de conversión personalizados          | Opcional    |

## Crear segmentos RFM

El análisis RFM (Recencia, Frecuencia, Monetario) encuentra a tus mejores clientes. Usa el editor de segmentos con condiciones de **Objetivo**:

![Editor de segmentos con un objetivo de eventos personalizados](https://www.notifuse.com/docs/assets/screenshots/segment_goals.png)

### Monetario: gasto total

Selecciona el tipo de objetivo **Compra** y el agregado **total**, y luego indica un valor mínimo para encontrar a los clientes que más gastan.

### Frecuencia: número de compras

Selecciona el tipo de objetivo **Compra** y el agregado **número**, y luego indica una cantidad mínima para encontrar a los compradores recurrentes.

### Recencia: actividad reciente

Usa el filtro de periodo "en los últimos X días" para encontrar a los clientes con compras recientes.

### Ejemplos de segmentos RFM

- **Clientes VIP**: gasto de 1000 $ o más Y 5 pedidos o más Y compra en los últimos 60 días
- **Alto valor en riesgo**: gasto de 500 $ o más Y ninguna compra en 90 días
- **Nuevos con alto potencial**: primera compra de más de 200 $ en los últimos 30 días

### Opciones de agregado

| Opción   | Descripción                                              |
| -------- | -------------------------------------------------------- |
| Total    | Suma de todos los valores del objetivo (gasto acumulado) |
| Número   | Cantidad de eventos (número de pedidos)                  |
| Promedio | Valor medio del objetivo (valor medio del pedido)        |
| Mínimo   | Valor del objetivo más bajo                              |
| Máximo   | Valor del objetivo más alto                              |

### Opciones de periodo

| Opción                | Descripción              |
| --------------------- | ------------------------ |
| En cualquier momento  | Todo el historial        |
| En los últimos X días | Ventana móvil            |
| En rango de fechas    | Un periodo concreto      |
| Antes de la fecha     | Corte histórico          |
| Después de la fecha   | Desde una fecha concreta |

## Registrar eventos

### Evento único

```bash
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "email": "customer@example.com",
    "event_name": "order.completed",
    "external_id": "order_12345",
    "properties": {
      "items": ["Product A", "Product B"],
      "currency": "USD"
    },
    "goal_type": "purchase",
    "goal_value": 149.99
  }'
```

### Importación por lotes

Importa hasta 50 eventos a la vez:

```bash
curl -X POST "https://your-instance.com/api/customEvents.import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "events": [
      {
        "email": "user1@example.com",
        "event_name": "order.completed",
        "external_id": "order_001",
        "goal_type": "purchase",
        "goal_value": 99.99
      },
      {
        "email": "user2@example.com",
        "event_name": "order.completed",
        "external_id": "order_002",
        "goal_type": "purchase",
        "goal_value": 249.99
      }
    ]
  }'
```

## Formato del nombre del evento

Los nombres de eventos deben ir en minúsculas y usar letras, números, puntos, guiones bajos, guiones o barras:

- `order.completed`
- `subscription/started`
- `form_submit`
- `user-signup`

> [!NOTE]
>
> Los objetivos registrados por [Analíticas web](https://www.notifuse.com/es/docs/web-analytics/goals.md) llegan a la cronología del contacto con una regla más estricta: solo letras ASCII, números, puntos y barras, y todo lo demás (guiones y caracteres acentuados incluidos) se sustituye por un guion bajo. Un objetivo web llamado `user-signup` llega como `user_signup`. Si envías el mismo evento por las dos vías, elige un nombre que sobreviva a ambas.

## Gestionar reembolsos

Usa un `goal_value` negativo para los reembolsos, así los cálculos de LTV siguen siendo correctos:

```json
{
  "email": "customer@example.com",
  "event_name": "order.refunded",
  "external_id": "refund_12345",
  "goal_type": "purchase",
  "goal_value": -50.00
}
```

## Permisos

Los eventos personalizados no tienen permiso propio: dependen de **Contactos**. Registrar o importar un evento requiere el nivel **Escribir** de Contactos, y leerlo requiere el nivel **Leído**. Por eso, conceder lectura en Contactos también abre los eventos registrados en tus contactos y la cronología que alimentan. Consulta [Administradores y claves API](https://www.notifuse.com/es/docs/features/admins-api-keys.md).

## Notas

- `customEvents.upsert` crea el contacto cuando no existe ninguno con ese correo. `customEvents.import` no crea ningún contacto
- Los eventos solo se actualizan si `occurred_at` es más reciente que el existente
- Para un borrado lógico, define `deleted_at` (ponlo a `null` para restaurar)
- Solo un evento nuevo (un `external_id` nuevo) inicia las automatizaciones que se disparan con su nombre; desde la 44.0, una actualización, un borrado lógico o una restauración no lo hacen
- Consulta la [referencia de la API](https://www.notifuse.com/docs/api-reference/import-custom-events.md) para la documentación completa del endpoint
