# Registrar evento (/es/api-reference/public-api/trackEvent)

`POST /v1/track`

Base URL: `https://api.bitelio.com`

Registra un evento para un contacto. Crea o hace upsert del contacto automáticamente y luego registra el evento. Los eventos registrados pueden usarse como disparadores de workflows, filtros de segmento y filtros de audiencia.

**Nombres de evento reservados** (rechazados con `VALIDATION_ERROR` y código `reserved_event`): cualquiera que coincida con `email.*`, `contact.subscribed`, `contact.unsubscribed`, `segment.<slug>.entry`, `segment.<slug>.exit`. Estos los emite el propio Bitelio.

**Espacios de nombres del sistema** (rechazados con `VALIDATION_ERROR` y código `system_sourced_event`): cualquiera que empiece por `pixel.` o `shopify.`. Los escribe el propio Bitelio — `pixel.*` desde el Web Pixel de la tienda vía `POST /v1/pixel`, `shopify.*` desde los webhooks firmados de Shopify — y los flujos predefinidos renderizan sus campos dentro del cuerpo y los enlaces de los correos. Este endpoint acepta una clave **pública**, así que no puede escribirlos: envía los eventos de la tienda a `POST /v1/pixel` y elige para los tuyos cualquier nombre fuera de esos dos prefijos.

**Idempotencia**: volver a registrar el mismo evento crea un nuevo registro de evento. Envía un encabezado `Idempotency-Key` para que una solicitud repetida se rechace con `409` en su lugar.

## Header parameters

- `Idempotency-Key`: string — Clave opcional que garantiza que esta solicitud se ejecute como máximo una vez. Si la clave ya fue usada por tu proyecto, la solicitud se rechaza con `409` en lugar de ejecutarse una segunda vez. Las claves están limitadas a tu proyecto, expiran a las 24 horas y deben tener entre 1 y 255 caracteres ASCII imprimibles.

## Request body

- `email`: string (email) (required) — Correo del contacto. El contacto se crea automáticamente si no existe.
- `event`: string (required) — Nombre del evento. No puede coincidir con los patrones reservados ni con los espacios de nombres del sistema anteriores.
- `subscribed`: boolean — Estado de suscripción a aplicar al contacto. Los contactos **nuevos** quedan suscritos (`true`) por defecto. Los contactos **existentes** conservan su estado actual salvo que pases aquí un valor explícito. Pasa `false` para registrar un evento sin volver a suscribir a un contacto que se había dado de baja.
- `data`: object — Datos del contacto y variables de evento puntuales. Los valores persistentes (primitivos, objetos simples) se guardan en el contacto y quedan disponibles como variables de plantilla. Pasa `{ value, persistent: false }` para variables de un solo uso que no deben guardarse en el contacto (p. ej., IDs de pedido, detalles de transacción). `null` elimina un campo. Los strings vacíos se ignoran. Las claves reservadas se filtran — consulta la página de conceptos de contactos.

Example:

```json
{
  "email": "user@example.com",
  "event": "string"
}
```

## Responses

### `200` — Evento registrado correctamente

- `success`: boolean
- `data`: object
  - `contact`: string — ID del contacto
  - `event`: string — ID del evento
  - `timestamp`: string (date-time)

```json
{
  "success": false,
  "data": {
    "contact": "string",
    "event": "string",
    "timestamp": "2026-10-13T07:11:40.117Z"
  }
}
```

### `409` — La Idempotency-Key ya fue usada. La solicitud fue rechazada, no ejecutada.

- `code`: integer
- `error`: string
- `message`: string
- `time`: integer

```json
{
  "code": 0,
  "error": "string",
  "message": "string",
  "time": 0
}
```

## Example request

```bash
curl -X POST 'https://api.bitelio.com/v1/track' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","event":"string"}'
```