> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Rastrear eventos personalizados > Defina eventos de negocio y envíe la actividad de los clientes a YCloud. ## Qué es Los eventos personalizados representan la actividad de su aplicación, sitio web, tienda o sistema backend. Defina el esquema del evento una vez y luego envíe ocurrencias que puedan ser utilizadas por los flujos de trabajo de clientes de YCloud. ## Antes de comenzar * Elija un nombre de evento estable que no cambie con los textos de la interfaz. * Identifique el contacto asociado con cada evento. * Defina las propiedades del evento y sus tipos de datos. * Decida qué marca de tiempo del sistema representa cuándo ocurrió la actividad. ## Cómo funciona 1. Cree una definición de evento. 2. Agregue o actualice definiciones de propiedades a medida que el esquema evolucione. 3. Envíe ocurrencias de eventos utilizando el nombre exacto de la definición. 4. Asocie cada ocurrencia con un ID de contacto, número de teléfono o nombre de usuario de Meta. 5. Monitoree eventos rechazados y discrepancias en el esquema. Las definiciones de eventos son contratos. Cambiar una etiqueta o descripción es más seguro que cambiar el significado de un nombre o propiedad existente. ## Solicitud ### Crear una definición de evento `POST /event/definitions` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/definitions \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "order_completed", "label": "Order completed", "description": "A customer completed an order.", "objectType": "CONTACT", "properties": [ { "name": "order_value", "label": "Order value", "type": "NUMBER" } ] }' ``` ### Elegir un identificador de contacto Para un evento definido con `objectType: CONTACT`, proporcione uno de estos identificadores: | Campo | Cómo identifica YCloud el contacto | | - | - | | `objectId` | Utiliza el ID numérico de un contacto existente en su cuenta. Si el contacto no existe, la solicitud falla. | | `contactPhoneNumber` | Busca un número de teléfono en formato E.164 en su cuenta y crea un contacto si no existe ninguna coincidencia. | | `contactUsername` | Coincide con el nombre de usuario de Meta guardado de un contacto existente en su cuenta. Si no existe ninguna coincidencia, la solicitud falla sin crear un contacto. | Solo se utiliza un identificador para cada evento. Si proporciona varios identificadores, un `objectId` numérico tiene prioridad, seguido de un `contactPhoneNumber` no vacío, y luego `contactUsername`. Si no se encuentra un ID de contacto numérico, YCloud rechaza la solicitud sin probar el número de teléfono ni el nombre de usuario. Utilice el nombre de usuario de Meta guardado en el contacto, sin el `@` inicial. `contactUsername` es un campo de solicitud de nivel superior, independiente de `properties`. No es necesario agregarlo a las definiciones de propiedades del evento. ### Enviar un evento por número de teléfono `POST /event/events` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/events \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "eventName": "order_completed", "occurTime": "2026-07-16T12:00:00.000Z", "contactPhoneNumber": "+16315551111", "properties": { "order_value": 99.9 } }' ``` ### Enviar un evento por nombre de usuario Si conoce el nombre de usuario de Meta del contacto, puede enviar el mismo evento sin un número de teléfono ni un ID de contacto. En este ejemplo, `customer_demo` ya debe estar guardado en un contacto de su cuenta. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/events \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "eventName": "order_completed", "occurTime": "2026-07-16T12:00:00.000Z", "contactUsername": "customer_demo", "properties": { "order_value": 99.9 } }' ``` ## Respuesta Crear una definición devuelve la definición guardada. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "order_completed", "label": "Order completed", "objectType": "CONTACT", "properties": [ { "name": "order_value", "label": "Order value", "type": "NUMBER" } ] } ``` Una ocurrencia de evento aceptada con éxito devuelve HTTP `200` con un objeto JSON vacío. ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK Content-Type: application/json {} ``` ## Evolución del esquema * Agregue nuevas propiedades opcionales siempre que sea posible. * No reutilice el nombre de una propiedad existente para un significado diferente. * Valide los tipos antes de enviar eventos. * Mantenga estables los nombres de eventos y de propiedades entre entornos. * Cree una nueva versión del nombre del evento cuando un cambio semántico incompatible sea inevitable. ## Límites y solución de problemas * La definición del evento debe existir antes de que se envíe una ocurrencia. * Los nombres y valores de las propiedades deben coincidir con la definición. * Utilice RFC 3339 para `occurTime`. * Asegúrese de que el identificador de contacto se resuelva en el cliente deseado en su cuenta. * Para `contactUsername`, verifique que el contacto ya exista y que el nombre de usuario coincida con el valor guardado sin un `@` inicial. * Omita los identificadores que no desee que YCloud utilice. Un número de teléfono proporcionado tiene prioridad sobre un nombre de usuario. * Una respuesta `200` confirma la aceptación, no que una automatización posterior haya finalizado. Inspeccionar esquemas de definición y propiedades. Inspeccionar el contrato de solicitud de ocurrencia. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.