> ## 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.

# Enviar ocurrencias de eventos (BETA)

> Aprende a enviar datos de ocurrencia de eventos a HubSpot utilizando tus esquemas de tipos de eventos definidos.

Tras [definir un esquema de tipo de evento](en-us/apps/developer-platform/build-apps/features/app-events/create-and-manage-event-types) y [recuperar su fullyQualifiedName](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname), puedes enviar datos de ocurrencia de eventos a través de la API de eventos de la aplicación. Cuando envíes datos de eventos, tendrás que respetar el esquema que creaste anteriormente. Las solicitudes que no coincidan con el esquema fallarán en la validación y no serán capturadas por la aplicación.

## Envío de ocurrencias de eventos

<Tabs>
  <Tab title="Enviar una ocurrencia única">
    Para enviar una ocurrencia de evento única, haz una solicitud de `POST` a `/integrators/timeline/v4/events`.

    En el cuerpo de la solicitud, incluye los datos del evento siguiendo el esquema definido para el tipo de evento junto con el valor `fullyQualifiedName` en un campo `eventTypeName`.

    ```json theme={null}
    {
      "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "objectId": "123456",
      "id": "login-1",
      "properties": {
        "customerName": "Mark S.",
        "loginLocation": "mobileApp"
      }
    },
    ```
  </Tab>

  <Tab title="Enviar un lote de ocurrencias">
    Para enviar un lote de ocurrencias, haz una solicitud de `POST` a `/integrators/timeline/v4/events/batch`.

    En el cuerpo de la solicitud, incluye hasta 500 objetos de ocurrencias de eventos separadas por comas dentro de una matriz `inputs`. Si alguna ocurrencia no se valida, las ocurrencias validadas con éxito seguirán aceptándose y persistiendo.

    ```json theme={null}
    {
      "inputs": [
        {
          "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
          "id": "login_event_100",
          "objectId": "769851",
          "properties": {
            "customerName": "Tim",
            "loginLocation": "mobileApp"
          },
          "extraData": {
            "surveyData": [
              {
                "question": "How was your login experience?",
                "answer": "Fine!"
              },
              {
                "question": "How likely are you to recommend logging in to a co-worker?",
                "answer": "Extremely likely"
              }
            ]
          }
        },
        {
          "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
          "id": "login_event_101",
          "objectId": "769851",
          "properties": {
            "customerName": "Tim",
            "loginLocation": "website"
          },
          "extraData": {}
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<p className="table-key">
  Los campos marcados con <span style={{ color: 'red' }}>\*</span> son obligatorios.
</p>

| Campo                                                | Tipo   | Descripción                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventTypeName`<span style={{color:"red"}}>\*</span> | Cadena | El nombre completo del tipo de evento, que utilizarás para identificarlo a través de la API. Este valor lo establece automáticamente HubSpot y se puede [obtener a través de la API](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname) después de crear el tipo de evento. Este valor no se puede cambiar después de la creación. |
| `objectId`<span style={{color:"red"}}>\*</span>      | Cadena | El ID del registro del CRM a asociar con la ocurrencia del evento. Este campo puede utilizarse para todos los tipos de registros de CRM, y es el identificador recomendado. Más información sobre [la asociación de registros del CRM](#crm-record-association).                                                                                                                                |
| `email`                                              | Cadena | Para la asociación de contactos, puedes proporcionar la dirección de correo electrónico del contacto a asociar. Más información sobre [la asociación de registros del CRM](#crm-record-association).                                                                                                                                                                                            |
| `utk`                                                | Cadena | Para la asociación de contactos, puedes proporcionar la ficha de usuario de un contacto existente para asociarlo. Más información sobre [la asociación de registros del CRM](#crm-record-association).                                                                                                                                                                                          |
| `domain`                                             | Cadena | Incluye este campo además de `objectId` para establecer el valor de la propiedad `domain` de la empresa. Más información sobre [la asociación de registros del CRM](#crm-record-association).                                                                                                                                                                                                   |
| `timestamp`                                          | Cadena | Establece la hora de ocurrencia del evento (formato[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Si no se proporciona, HubSpot utilizará por defecto la marca de tiempo de cuando se envían los datos de ocurrencia del evento.                                                                                                                                                          |
| `properties`                                         | Objeto | Pares clave-valor de nombres y valores de propiedades que has configurado para el tipo de evento. Más información sobre las [propiedades del evento](/apps/developer-platform/add-features/app-events/reference#event-properties).                                                                                                                                                              |
| `extraData`                                          | Objeto | Información adicional que estará disponible para las [plantillas de representación de la cronología](/apps/developer-platform/add-features/app-events/reference#rendering-templates). Debe estar en formato JSON válido.                                                                                                                                                                        |
| `timelineIFrame`                                     | Objeto | Cuando se incluya, la tarjeta de cronología incluirá un hipervínculo que permitirá a los usuarios abrir los contenidos enlazados en un iframe. Más información sobre [el uso de iframes](/apps/developer-platform/add-features/app-events/reference#using-iframes).                                                                                                                             |
| `id`                                                 | Cadena | Un identificador único para la ocurrencia del evento. Debe ser único dentro del tipo de evento. Si no se proporciona, HubSpot generará un UUID aleatorio. Cuando varios eventos tengan el mismo ID, se aceptará el primero y se rechazarán todos los demás.                                                                                                                                     |

## Asociación de registros del CRM

Cada suceso debe estar asociado a un registro del CRM, con el tipo de objeto del CRM definido por el esquema de tipo de evento. La API de eventos de la aplicación incluye múltiples campos para asociar los datos de ocurrencia de eventos con los registros del CRM. Para todos los objetos del CRM compatibles, se recomienda utilizar el campo `objectId`. Sin embargo, hay algunas situaciones en las que puede que quieras utilizar los otros campos.

* `utk`/`email`: si no conoces el ID del contacto, utiliza el campo `utk` y/o `email` para identificarlo. Proporcionar estos dos identificadores también te permite crear y actualizar contactos. Por ejemplo:
  * Si `utk` coincide con un contacto existente pero `email` no coincide, HubSpot actualizará el contacto (mediante `utk`) con la nueva dirección de correo electrónico.
  * Si no se proporciona `objectId`, el evento se asociará a un contacto existente que coincida con `utk`/`email`, o HubSpot creará un nuevo contacto si no se encuentra ninguna coincidencia.
  * Ten en cuenta que `utk` por sí solo no puede crear nuevos contactos. Siempre debes incluir `email` con `utk` para garantizar una asociación adecuada.
* `domain`: para la asociación de empresas, debes proporcionar la dirección `objectId`, pero también puedes incluir `domain` para actualizar la propiedad `domain` de esa empresa.

A continuación se muestra el orden de prioridad de las propiedades de la asociación de registros del CRM, siendo el número más bajo el de mayor prioridad:

| Campo      | Prioridad | Descripción                                                       |
| ---------- | --------- | ----------------------------------------------------------------- |
| `objectId` | 1         | El ID del registro del CRM (recomendado).                         |
| `utk`      | 2         | La ficha de usuario del contacto (solo contactos).                |
| `email`    | 3         | La dirección de correo electrónico del contacto (solo contactos). |
| `domain`   | 4         | Dominio de la empresa (solo empresas).                            |

## Envío de datos adicionales

Además de enviar datos a las [propiedades de los eventos](/apps/developer-platform/add-features/app-events/reference#event-properties) y [actualizar las propiedades de CRM a través de las ocurrencias de los eventos](/apps/developer-platform/add-features/app-events/reference#property-stamping), puedes incluir datos adicionales para la [representación de la cronología](/apps/developer-platform/add-features/app-events/reference#rendering-templates) a través del objeto `extraData`.

<Warning>
  El objeto `extraData` solo puede contener JSON válido. Si el JSON está malformado, la ocurrencia será rechazada y recibirás una respuesta de error.
</Warning>

Se puede acceder a los valores del campo `extraData` del tipo de evento `detailTemplate` utilizando la sintaxis `{{extraData.fieldName}}`. Todos los niveles de atributo de `extraData` están disponibles a través de la notación por puntos, como `{{extraData.person1.preferredName}}`.

Por ejemplo, las plantillas siguientes utilizan los datos de las propiedades `customerName` y `loginLocation`, junto con el campo `surveyData` de `extraData` [enviado a través de la ocurrencia del evento](#event-occurrences).

![Captura de pantalla que muestra el aspecto de la plantilla de representación del ejemplo siguiente en la cronología de contactos.](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/example-timeline-event-rendering-template.png)

<Tabs>
  <Tab title="Datos de la ocurrencia de evento">
    ```json theme={null}
    {
      "eventTemplateId": "5488733",
      "objectId": "769851",
      "tokens": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Configuración de la plantilla de cronología">
    ```json theme={null}
    "headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
    "detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",
    ```
  </Tab>
</Tabs>