> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt > Use this file to discover all available pages before exploring further. # Definir eventos personalizados export const ScopesList = ({scopes = [], description = "Esta API requiere uno de los siguientes ámbitos:"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; Los eventos personalizados te permiten definir y hacer un seguimiento de eventos exclusivos de tu empresa, como eventos en tu sitio web o en una aplicación. Puedes configurar eventos para almacenar información dentro de las propiedades, que luego podrás utilizar en todas las herramientas de HubSpot. Para enviar los datos del [evento personalizado](/api-reference/events-send-event-completions-v3/guide) a HubSpot, primero tienes que definir el evento. Esto es similar a los objetos personalizados del CRM, donde primero tienes que definir el objeto personalizado antes de poder crear registros individuales para ese objeto. La definición de un evento incluye detalles como sus metadatos, asociaciones de objetos del CRM y propiedades. A continuación, obtén más información sobre cómo crear y gestionar definiciones de eventos utilizando la API. Para aprender a crear definiciones de eventos sin utilizar la API, consulta la [base de conocimientos de HubSpot](https://knowledge.hubspot.com/es/reports/create-custom-events). ## Crear una definición de evento Para crear el esquema de evento personalizado, haz una solicitud `POST` a `events/v3/event-definitions`. En el cuerpo de la solicitud, incluye definiciones para tu esquema de eventos, incluyendo su etiqueta, nombre, asociaciones de objetos del CRM y propiedades personalizadas. El cuerpo de la solicitud que aparece a continuación proporciona un ejemplo básico de definición de un evento: ```json theme={null} { "label": "My event label", "name": "unique_event_name", "description": "An event description that helps users understand what the event tracks.", "primaryObject": "COMPANY", "propertyDefinitions": [ { "name": "choice-property", "label": "Choice property", "type": "enumeration", "options": [ { "label": "Option 1", "value": "1" }, { "label": "Option 2", "value": "2" } ] }, { "name": "string-property", "label": "String property", "type": "string" } ], "includeDefaultProperties": true } ``` Si quieres vincular automáticamente las finalizaciones de eventos a registros de un tipo de objeto del CRM específico, puedes incluir un `customMatchingId` en tu solicitud `POST`. Dentro de este campo, define un objeto `primaryObjectRule` con dos campos: la propiedad única del objeto que has configurado previamente como `targetObjectPropertyName` y una de las propiedades que has definido en `propertyDefinitions` a partir de la definición de tu evento. Por ejemplo, el siguiente cuerpo de solicitud especifica un `customMatchingId` que coincide con un nombre de propiedad de objeto del CRM de `"unique_object_property"` y el nombre de propiedad de evento de `"string_property"`: ```json theme={null} { "label": "My event label", "name": "unique_event_name", "description": "An event description that helps users understand what the event tracks.", "primaryObject": "COMPANY", "propertyDefinitions": [ { "name": "string-property", "label": "String property", "type": "string" } ], "customMatchingId": { "primaryObjectRule": { "targetObjectPropertyName": "unique_object_property", "eventPropertyName": "event_property" } } } ``` La lista completa de parámetros disponibles para el cuerpo de la solicitud se detalla en la tabla siguiente: | Parámetro | Tipo | Descripción | | -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | Cadena | La etiqueta legible del evento, que se mostrará en HubSpot (hasta 100 caracteres). Las etiquetas largas pueden aparecer cortadas en algunas partes de la interfaz de usuario de HubSpot. | | `name` | Cadena | El nombre interno y único del evento, que utilizarás para hacer referencia al evento a través de la API. Si no se proporciona ningún valor, HubSpot generará uno automáticamente basándose en la etiqueta. | | `description` | Cadena | La descripción del evento, que se mostrará en HubSpot. | | `primaryObject` | Cadena | El tipo de objeto del CRM al que se asociarán los datos del evento. Las finalizaciones de eventos aparecerán en los registros del CRM de ese tipo de objeto. Puede ser uno de los siguientes: `"CONTACT"` (predeterminado), `"COMPANY"`, `"DEAL"`, `"TICKET"`, `""`. Este no se puede modificar después de crear la definición del evento. | | `propertyDefinitions` | Matriz | Además de las [propiedades de evento predeterminadas de HubSpot](#hubspot-s-default-event-properties), puedes incluir esta matriz para definir propiedades de evento personalizadas (hasta 50). Para cada objeto propiedad, incluye los siguientes campos:
  • `name`: el nombre interno de la propiedad, que utilizarás cuando envíes datos de eventos a través de la API.
  • `label`: la etiqueta en la aplicación de la propiedad.
  • `type`: el [tipo de propiedad](#event-properties). De forma predeterminada es `string`.
  • `options`: para las propiedades de tipo `enumeration`, esta matriz define los valores disponibles. Debe incluir un `label` y un `value` para cada opción.
  • `description`: texto que describe la propiedad.
| | `customMatchingId` | Objeto | Como alternativa a incluir el `objectId` del objeto de destino en los datos de finalización del evento, este campo opcional define una regla para vincular automáticamente las finalizaciones de eventos a registros del tipo de objeto del CRM especificado. Esto se hace haciendo coincidir el valor de una propiedad de los datos del evento con el valor de una propiedad única del objeto de destino. Este objeto debe incluir un objeto anidado `primaryObjectRule`, que a su vez debe incluir dos campos:
  • `targetObjectPropertyName`: una cadena que especifica el nombre de la propiedad única en el objeto del CRM de destino que se utilizará para la asignación.
  • `eventPropertyName`: una cadena que especifica el nombre de la propiedad en los datos del evento personalizado que se utilizará para la asignacicón.
| | `includeDefaultProperties` | Booleano | Campo opcional que especifica si el evento debe incluir el conjunto de [propiedades predeterminadas del evento](#hubspot-s-default-event-properties). Si no se proporciona ningún valor, este campo se establecerá automáticamente como `true`. | ## Propiedades de eventos Las propiedades de evento personalizado se utilizan para almacenar información sobre la finalización de eventos personalizados individuales. Estas propiedades deben utilizarse cuando sea apropiado para enviar finalizaciones de eventos, pero no son necesarias para que una finalización de evento sea válida. Para cada definición de evento, HubSpot proporciona un conjunto predeterminado de 32 propiedades. Además, puedes crear hasta 50 propiedades personalizadas por definición de evento. Las propiedades pueden ser de los siguientes tipos: * `bool`: propiedad que recibe un valor booleano. Los valores deben representarse como `true` o `false`. * `date`: propiedad que recibe una fecha que representa un día, un mes y un año específicos. Los valores deben estar en la zona horaria UTC y el formato puede ser [una cadena en notación ISO 8601](/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties) o una marca de tiempo EPOCH en milisegundos (es decir, la media noche en la zona horaria UTC). * `datetime`: Propiedad que recibe valores en milisegundos de epoch o ISO8601 que representan una marca de tiempo. * `enumeration`: Una propiedad con opciones predefinidas. Al crear este tipo de propiedad, incluye una matriz `options` para establecer los valores disponibles. * `number`: propiedad que recibe valores numéricos con hasta un decimal. * `string`: una propiedad que recibe cadenas de texto sin formato. Si el nombre de la propiedad contiene las palabras `url`, `referrer`, o `link`, el valor de propiedad puede tener hasta 1024 caracteres. De lo contrario, los valores de propiedad pueden tener hasta 256 caracteres. A continuación, obtén información sobre las propiedades del evento predeterminadas de HubSpot, sobre cómo [definir nuevas propiedades para eventos existentes](#define-new-properties), y sobre cómo [actualizar las propiedades personalizadas del evento existentes](#update-existing-custom-properties). ### Propiedades del evento predeterminadas de HubSpot * `hs_asset_description` * `hs_asset_type` * `hs_browser` * `hs_campaign_id` * `hs_city` * `hs_country` * `hs_device_name` * `hs_device_type` * `hs_element_class` * `hs_element_id` * `hs_element_text` * `hs_language` * `hs_link_href` * `hs_operating_system` * `hs_operating_version` * `hs_page_content_type` * `hs_page_id` * `hs_page_title` * `hs_page_url` * `hs_parent_module_id` * `hs_referrer` * `hs_region` * `hs_screen_height` * `hs_screen_width` * `hs_touchpoint_source` * `hs_tracking_name` * `hs_user_agent` * `hs_utm_campaign` * `hs_utm_content` * `hs_utm_medium` * `hs_utm_source` * `hs_utm_term` ### Definir nuevas propiedades Para definir una nueva propiedad en un evento personalizado existente, haz una solicitud `POST` a `events/v3/event-definitions/{eventName}/property`. En el cuerpo de la solicitud, incluye la definición de tu propiedad. ```json theme={null} { "name": "property-name", "label": "Property name", "type": "enumeration", "options": [ { "label": "label", "value": "value" } ] } ``` Cuando pongas nombre a tu propiedad, ten en cuenta lo siguiente: * Una vez que creas una propiedad, su nombre no se puede cambiar. * El nombre solo puede contener letras minúsculas, números, guiones bajos y guiones. * El primer carácter del nombre de propiedad debe ser una letra. * El nombre de propiedad y la etiqueta pueden tener hasta 50 caracteres cada uno. * Si no se proporciona un nombre de propiedad, se autogenerará uno utilizando la etiqueta de la propiedad. * Las etiquetas largas pueden quedar cortadas en algunas partes de la interfaz de HubSpot. ### Actualizar propiedades personalizadas existentes Para actualizar una propiedad existente en un evento personalizado, haz una solicitud `PATCH` a `events/v3/event-definitions/{eventName}/property`. Los únicos campos que se pueden actualizar en una propiedad son los de `label`, `description`, y `options` para las propiedades de enumeración. ### Nota: Para cambiar el tipo de propiedad, utiliza el interruptor `DELETE` para eliminar la propiedad y volver a crearla con el tipo correcto. ### Eliminar una propiedad Para eliminar una propiedad existente en un evento personalizado, haz una solicitud `DELETE` a `events/v3/event-definitions/{eventName}/property/{propertyName}`. Cuando se elimina una propiedad, ya no estará disponible para su uso en futuras finalizaciones de eventos. Las finalizaciones anteriores seguirán teniendo los valores de propiedad. ## Actualizar un evento Para actualizar un esquema de evento personalizado existente, haz una solicitud `PATCH` a `events/v3/event-definitions/{eventName}`. Los únicos campos de definición de eventos que se pueden actualizar son `label` y `description`. ```json theme={null} { "label": "Event label", "description": "A description of the event" } ``` ## Eliminar un evento Para eliminar un evento personalizado, haz una solicitud `DELETE` a `events/v3/event-definitions/{eventName}`. Al eliminar un evento personalizado, se eliminará de cualquier otra herramienta de HubSpot que haga referencia a él, como workflows e informes. ### Ten en cuenta que cuando elimines un evento: 1. Todos los eventos de esa definición de evento se eliminarán y serán irrecuperables. 2. Los `eventName` borrados previamente no se pueden volver a utilizar, así que ten cuidado al borrar un evento. ## Obtener definiciones de eventos existentes Para obtener una única definición de evento, haz una solicitud `GET` a `events/v3/event-definitions/{eventName}`. Para buscar definiciones de eventos por criterios específicos, haz una solicitud `GET` a `events/v3/event-definitions`. Puedes proporcionar los siguientes parámetros de consulta para ajustar tu búsqueda: * `searchString`: busca eventos que contengan los caracteres especificados en el campo `name`. La búsqueda no es difusa, sino que se trata de una búsqueda simple que *verifica* si el término está contenido. * `after`: una cadena con hash proporcionada en las respuestas paginadas para visualizar la siguiente página de los resultados de la búsqueda. * `limit`: el número máximo de resultados a devolver. * `includeProperties`: un valor booleano que especifica si se incluyen propiedades del evento en los resultados devueltos.