# Enviar un evento

Usa POST /v1/events/send de la API de Pristo para iniciar una distribución basada en eventos para un contacto, con ejemplos de solicitud y respuesta.

`POST https://api.pristo.io/v1/events/send` informa a Pristo CX sobre un evento de un contacto, como una compra. Pristo CX agrega o actualiza el contacto en la población del programa de la clave API, y las distribuciones basadas en eventos activas que seleccionan este tipo de evento envían su cuestionario por SMS o por correo electrónico.

## Antes de empezar

- Clave API: una clave del programa. Consulta [Autenticarse con una clave API](https://docs.pristo.io/es/cx/api/authentication).
- Plan: el acceso a la API requiere el plan Estándar o Pro. La aplicación muestra **Distribuciones**, donde se configuran las distribuciones basadas en eventos, solo en el plan Pro.
- Población: el programa tiene una población. Si **Población** muestra **Este programa aún no tiene población**, la API devuelve `404`. Consulta [Introducción a las poblaciones](https://docs.pristo.io/es/cx/populations/overview).
- Tipo de evento: en **Población**, abre **Acciones** > **Atributos de eventos** > **Tipos de eventos**. El **Identificador único** del tipo de evento es el valor que envías en `type`.
- Distribución: una distribución basada en eventos activa selecciona ese tipo de evento. Consulta [Enviar encuestas después de un evento](https://docs.pristo.io/es/cx/distributions/event-based).

## Pasos

1. Crea el cuerpo JSON con `type` y `contact.id`. Agrega `contact.email` o `contact.phone` para que el contacto pueda recibir la encuesta.

2. Envía el cuerpo a `https://api.pristo.io/v1/events/send` con los encabezados `X-API-Key` y `Content-Type: application/json`.

3. Guarda el `eventId` de la respuesta.

4. Comprueba el evento en la aplicación: abre el contacto en **Población**. El evento aparece en **Eventos** con su estado.

```bash
curl -X POST "https://api.pristo.io/v1/events/send" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase",
    "contact": {
      "id": "CUST-1042",
      "email": "dana@example.com",
      "phone": "+972501234567",
      "name": "Dana",
      "lastName": "Example",
      "language": "en",
      "customFields": { "tier": "gold" }
    },
    "customFields": { "branch": "example_branch", "amount": "120" }
  }'
```

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
| `type` | string | Sí | El **Identificador único** del tipo de evento. De 1 a 50 caracteres |
| `contact` | object | Sí | El contacto al que le ocurrió el evento |
| `contact.id` | string | Sí | Tu propio ID del contacto, de 1 a 50 caracteres. Pristo CX busca un contacto existente con este ID, sin distinguir mayúsculas de minúsculas, o crea uno nuevo |
| `contact.email` | string | No | La dirección de correo electrónico del contacto. Una dirección no válida se ignora |
| `contact.phone` | string | No | Un número de celular israelí, como `+972501234567` o `0501234567`. Los demás números se guardan, pero no pueden recibir SMS |
| `contact.name`, `contact.lastName` | string | No | El nombre y el apellido. Los valores más largos se recortan a 50 caracteres |
| `contact.language` | string | No | Un código de dos letras, como `he` o `en`. Si no lo incluyes, el contacto recibe el idioma predeterminado de la población |
| `contact.customFields` | object | No | Valores de atributos del contacto, con el **Identificador único** de cada atributo de **Atributos de contacto** como clave. Las claves desconocidas y los valores que no se ajustan al atributo se ignoran |
| `customFields` | object | No | Valores de atributos del evento, con el **Identificador único** de cada atributo de evento de la pestaña **Atributos** como clave. Los filtros de las distribuciones leen cada valor según el tipo del atributo de evento, y un valor que no se puede leer así no coincide |

Salvo `contact.language`, los campos que no incluyas conservan los valores que el contacto ya tiene guardados. La API ignora los campos que no conoce, como `occurredAt`: la hora del evento es la hora en que Pristo CX lo recibe.

## Resultado

La API responde `200 OK` con el ID del evento:

```json
{
  "eventId": "AbCdEfGhIjKlMnOpQrStUv"
}
```

`200` significa que Pristo CX guardó el evento. Luego, Pristo CX actualiza el contacto y programa la encuesta, así que ambos aparecen poco después de que termina la llamada, no mientras se ejecuta.

La ruta anterior `POST /v1/events/send/{popId}` sigue funcionando y hace lo mismo. Su `popId` se ignora: la población siempre sale del programa de la clave API. Usa `/v1/events/send` en el código nuevo.

## Límites

- El cuerpo de la solicitud puede tener como máximo 10 000 bytes. Solo cuentan para el límite los campos que la API conoce, y cada carácter que no es ASCII, como una letra hebrea, cuenta como 6 bytes.
- `type` y `contact.id`: de 1 a 50 caracteres cada uno.
- Las reglas de espaciado de la distribución deciden con qué frecuencia un contacto puede recibir la encuesta. Un espaciado de 0 días mantiene de todos modos al menos 10 minutos entre dos encuestas al mismo contacto, contando las encuestas programadas que aún no se enviaron.

## Solución de problemas

**La API devolvió 200, pero no se envió ninguna encuesta.** Comprueba que `type` coincida con un tipo de evento que selecciona una distribución basada en eventos activa, y que el contacto tenga una dirección de correo electrónico para una distribución por correo electrónico o un número de celular israelí para SMS. Un contacto que se dio de baja, o que no cumple los filtros de la distribución, no recibe nada. El tiempo de espera y las franjas de envío de la distribución también pueden retrasar el envío.

**La API devolvió 404 con `no population is associated with this api key`.** El programa de la clave API no tiene población. Crea primero la población o usa una clave de un programa que tenga una.

**El idioma del contacto cambió.** Cuando falta `contact.language`, Pristo CX asigna al contacto el idioma predeterminado de la población. Envía `contact.language` con cada evento.

**La API devolvió 400 o 401.** En la mayoría de los errores 400, el cuerpo indica el problema en texto sin formato. Un 401 significa que falta la clave API o que no está activa. Consulta [Errores de la API](https://docs.pristo.io/es/cx/api/errors).

## Temas relacionados

- [Enviar encuestas después de un evento](https://docs.pristo.io/es/cx/distributions/event-based)
- [Introducción a las poblaciones](https://docs.pristo.io/es/cx/populations/overview)
- [Importar actividades](https://docs.pristo.io/es/cx/populations/import-activities)
- [Autenticarse con una clave API](https://docs.pristo.io/es/cx/api/authentication)
- [Errores de la API](https://docs.pristo.io/es/cx/api/errors)
- [Referencia de la API: Enviar un evento (en inglés)](https://docs.pristo.io/cx/api/reference/operations/sendevent)