Registrar evento
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.
Authorization
ApiKeyAuth Autenticación mediante clave de API. Las claves secretas (sk_*) son obligatorias en todos los endpoints excepto /v1/track. Las claves públicas (pk_*) solo funcionan con el endpoint /v1/track para el seguimiento de eventos desde el cliente. El proyecto se deriva automáticamente de la clave.
In: header
Header Parameters
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.
length <= 255Request Body
application/json
Correo del contacto. El contacto se crea automáticamente si no existe.
emailNombre del evento. No puede coincidir con los patrones reservados ni con los espacios de nombres del sistema anteriores.
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.
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.
Response Body
application/json
application/json
curl -X POST "https://api.bitelio.com/v1/track" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "event": "purchase", "data": { "product": "Premium Plan", "amount": 99 } }'{
"success": true,
"data": {
"contact": "string",
"event": "string",
"timestamp": "2019-08-24T14:15:22Z"
}
}{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "Idempotency-Key \"order-1234-receipt\" has already been used",
"statusCode": 409,
"requestId": "8f14e45f-ceea-467a-9575-1f0f38e0b1c2",
"details": {
"key": "order-1234-receipt",
"originalRequest": "POST /v1/send",
"originalRequestAt": "2025-01-15T10:30:00.000Z",
"originalStatusCode": 200
},
"suggestion": "This Idempotency-Key was already used, so the request was refused rather than performed twice. Generate a new key for a genuinely new request."
},
"timestamp": "2025-01-15T10:31:00.000Z"
}