# Enviar eventos desde tu backend

> Registra eventos de espacio de trabajo y personalizados desde tus servidores con la API de eventos, de uno en uno o por lotes, con una clave de API Events Only.

Envía eventos desde tus servidores para todo lo que no deba depender del navegador del visitante, como pedidos, pagos, cambios de suscripción o eventos de un back office. Esta página muestra cómo enviar un evento, cómo enviar muchos y cómo gestionar los errores.

## Antes de empezar

- Enviar eventos está incluido en los planes Pro, Business y Custom. Un espacio de trabajo Pro puede usar 100 tipos de eventos, y uno Business, 1000. Consulta [Límites](/es/docs/events/#limits).
- Crea una clave de API con el permiso **Events Only** en **Email API → API Keys**. Puede enviar eventos y nada más: no puede leer tus datos, gestionar las definiciones de eventos ni enviar emails. Una clave **Full Access** también sirve. Consulta [Claves de API](/es/docs/developers/api-keys/#scopes).
- Para enviar eventos de espacio de trabajo, primero [defínelos](/es/docs/events/workspace-events/). Los eventos personalizados no necesitan configuración.

## Enviar un evento

Llama a [Enviar un evento](/es/docs/api-reference/events/send/) con el `type` del evento, sus `properties` y la persona a la que se refiere:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'
```

- `email` vincula el evento al contacto que tiene esa dirección. Si ya conoces el ID del contacto, envía `contact_id` en su lugar.
- `occurred_at` es cuándo ocurrió, por ejemplo si envías eventos desde una cola. Omítelo para usar la hora actual.
- La respuesta es `201` con el evento guardado y su ID `evt_`. Con una clave Events Only, el evento se devuelve sin `data`.

## Enviar muchos eventos a la vez

[Enviar eventos por lotes](/es/docs/api-reference/events/batch/) acepta hasta 100 eventos en una petición, lo que va bien para importaciones y sincronizaciones programadas:

```bash
curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } }
    ]
  }'
```

Un lote es todo o nada: si un evento no es válido, no se guarda ninguno. La respuesta `422` muestra cada problema en `events.<index>`, así que puedes corregir o quitar esos eventos y volver a enviar el lote.

## Gestionar los errores

| Estado | Significado | Qué hacer |
| --- | --- | --- |
| `201` | Guardado. | Nada. |
| `400` | El cuerpo no es un objeto JSON, o el lote está vacío o tiene más de 100 eventos. | Corrige la petición. |
| `401` | Falta la clave de API o es incorrecta. | Comprueba la clave. |
| `403` | El permiso de la clave no permite enviar eventos, o el espacio de trabajo está en Pay as you go (`"error": "plan_required"`). | Usa una clave Events Only o Full Access, o cambia a Pro o Business. |
| `422` | Un evento no es válido: un evento `w:` que no está definido, una propiedad del tipo incorrecto, un `contact_id` desconocido, una fecha más de 24 horas en el futuro o un tipo de evento nuevo cuando el espacio de trabajo ya usa el número de tipos de su plan. `errors` indica cada campo. | Corrige el evento, o cambia a un plan superior para tener más tipos de eventos. Si lo reintentas sin cambios, vuelve a fallar. |
| `5xx` | Un problema temporal por parte de Emailit. | Reintenta con espera exponencial. |

Los eventos no tienen clave de idempotencia, así que reintentar una petición que ya se procesó guarda el evento dos veces. Pon tu propio ID en las propiedades, como `order_id`, para que quien lea los eventos pueda reconocer los duplicados.

## Comprobar que llegan los eventos

Abre **Email API → Events**. La pestaña **Log** muestra los eventos nuevos arriba; en **Scope**, elige **Custom** o **Workspace** para ocultar los eventos de sistema. Selecciona un evento para ver sus propiedades, el contacto al que pertenece y de dónde vino. Los eventos vinculados a un contacto también aparecen en el **Activity log** del contacto.

## Ver también

  - [Seguimiento de eventos](/es/docs/events/): Ámbitos, nombres y adónde van los eventos.
  - [Script de seguimiento](/es/docs/events/tracking-script/): Envía eventos desde tu web.
  - [Enviar un evento](/es/docs/api-reference/events/send/): Todos los parámetros y respuestas.
  - [Claves de API](/es/docs/developers/api-keys/): Crea una clave Events Only.

---
Fuente: https://emailit.com/es/docs/events/send-events/