> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Envoyer des occurrences d'événements (BÊTA)

> Découvrez comment envoyer des données d'occurrence d'événement dans HubSpot à l'aide des schémas de type d'événement que vous avez définis.

Après [avoir défini un schéma de type d'événement](en-us/apps/developer-platform/build-apps/features/app-events/create-and-manage-event-types) et [récupéré son fullyQualifiedName](/docs/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname), vous pouvez envoyer des données d'occurrence d'événement via l'API d'événements de l'application. Lors de l'envoi de données d'événement, vous devrez respecter le schéma que vous avez créé précédemment. Les requêtes qui ne correspondent pas au schéma échoueront à être validées et ne seront pas capturées par l'application.

## Envoi d'occurrence d'événements

<Tabs>
  <Tab title="Envoyer une occurrence unique">
    Pour envoyer une occurrence d'événement unique, effectuez une requête `POST` à `/integrators/timeline/v4/events`.

    Dans le corps de la requête, incluez les données d'événements suivant le schéma défini pour le type d'événement ainsi que la valeur `fullyQualifiedName` dans un champ `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="Envoyer un lot d'occurrences">
    Pour envoyer un lot d'occurrences d'événements, effectuez une demande `POST` à `/integrators/timeline/v4/events/batch`.

    Dans le corps de la requête, incluez jusqu'à 500 objets d'occurrence d'événement séparés par des virgules dans un tableau `inputs`. Si certaines occurrences ne sont pas validées, les occurrences validées avec succès seront toujours acceptées et persistées.

    ```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">
  Les champs marqués par <span style={{ color: 'red' }}>\*</span> sont requis.
</p>

| Champ                                                | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `eventTypeName`<span style={{color:"red"}}>\*</span> | Chaîne | le nom entièrement qualifié du type d'événement, que vous utiliserez pour identifier l'événement via l'API. Cette valeur est automatiquement définie par HubSpot et peut être [obtenue via l'API](/docs/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname) après la création du type d'événement. Cette valeur ne peut pas être modifiée après la création. |
| `objectId`<span style={{color:"red"}}>\*</span>      | Chaîne | l'ID de la fiche d'informations de CRM à associer à l'événement. Ce champ peut être utilisé pour tous les types de fiches d'informations de CRM et constitue l'identifiant recommandé. Découvrez-en davantage sur [l'association des fiches d'informations CRM](#crm-record-association).                                                                                                                          |
| `email`                                              | Chaîne | pour l'association de contact, vous pouvez fournir l'adresse e-mail du contact à associer. Découvrez-en davantage sur [l'association des fiches d'informations CRM](#crm-record-association).                                                                                                                                                                                                                      |
| `utk`                                                | Chaîne | pour l'association de contacts, vous pouvez fournir le jeton utilisateur d'un contact existant à associer. Découvrez-en davantage sur [l'association des fiches d'informations CRM](#crm-record-association).                                                                                                                                                                                                      |
| `domain`                                             | Chaîne | incluez ce champ en plus de `objectId` pour définir la valeur de propriété de l'entreprise `domain`. Découvrez-en davantage sur [l'association des fiches d'informations CRM](#crm-record-association).                                                                                                                                                                                                            |
| `timestamp`                                          | Chaîne | définit l'heure de l'occurrence de l'événement (format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Si ce champ n'est pas renseigné, HubSpot utilisera par défaut l'horodatage de l'envoi des données d'occurrence d'événement.                                                                                                                                                                            |
| `properties`                                         | Objet  | paires clé-valeur des noms et valeurs des propriétés que vous avez configuré pour le type d'événement. Découvrez-en davantage sur les [propriétés d'événement](/docs/apps/developer-platform/add-features/app-events/reference#event-properties).                                                                                                                                                                       |
| `extraData`                                          | Objet  | des informations supplémentaires qui seront disponibles pour les [modèles de rendu de chronologie](/docs/apps/developer-platform/add-features/app-events/reference#rendering-templates). Doit être au format JSON valide.                                                                                                                                                                                               |
| `timelineIFrame`                                     | Objet  | une fois incluse, la carte de chronologie comprendra un lien hypertexte qui permet aux utilisateurs d'ouvrir le contenu lié dans un iframe. Découvrez-en davantage sur [l'utilisation des iframes](/docs/apps/developer-platform/add-features/app-events/reference#using-iframes).                                                                                                                                      |
| `id`                                                 | Chaîne | un identifiant unique pour l'occurrence de l'événement. Doit être unique dans le type d'événement. Si ce champ n'est pas renseigné, HubSpot générera un GUID aléatoire. Lorsque plusieurs événements ont le même ID, le premier sera accepté et tous les autres seront rejetés.                                                                                                                                    |

## Association des fiches d'informations CRM

Chaque événement doit être associé à une fiche d'informations CRM, le type d'objet CRM étant défini par le schéma de type d'événement. L'API des événements de l'application comprend plusieurs champs pour associer les données d'occurrence d'événement aux fiches d'informations CRM. Pour tous les objets CRM pris en charge, il est recommandé d'utiliser le champ `objectId`. Cependant, dans certaines situations, vous souhaiterez peut-être utiliser les autres champs.

* `utk`/`email` : si vous ne connaissez pas l'ID du contact, utilisez le champ `utk` et/ou `email` pour l'identification. Fournir ces deux identifiants vous permet également de créer et de mettre à jour des contacts. Par exemple :
  * Si `utk` correspond à un contact existant, mais que l'`email` ne correspond pas, HubSpot mettra à jour le contact (par `utk`) avec la nouvelle adresse e-mail.
  * Si aucun `objectId` n'est fourni, l'occurrence de l'événement sera associée à un contact existant correspondant à `utk`/`email`, ou HubSpot créera un nouveau contact si aucune correspondance n'est trouvée.
  * Notez que le `utk` seul ne peut pas créer de nouveaux contacts. Vous devez toujours inclure l'`email` avec `utk` pour garantir une bonne association.
* `domain` : pour l'association d'entreprises, vous devez fournir l'`objectId`, mais vous pouvez également l'inclure le `domain` pour mettre à jour la propriété de `domain` de cette entreprise.

Voici l'ordre de priorité des propriétés d'association des fiches d'informations CRM, le nombre le plus bas étant la priorité la plus élevée :

| Champ      | Priorité | Description                                              |
| ---------- | -------- | -------------------------------------------------------- |
| `objectId` | 1        | L'ID de fiche d'informations CRM (recommandé).           |
| `utk`      | 2        | Le jeton d'utilisateur du contact (contacts uniquement). |
| `email`    | 3        | L'adresse e-mail du contact (contacts uniquement).       |
| `domain`   | 4        | Le domaine de l'entreprise (entreprises uniquement).     |

## Envoi de données supplémentaires

Au-delà de l'envoi de données aux [propriétés d'événement](/docs/apps/developer-platform/add-features/app-events/reference#event-properties) et [de la mise à jour des propriétés CRM via les occurrences d'événement](/docs/apps/developer-platform/add-features/app-events/reference#property-stamping), vous pouvez inclure des données supplémentaires pour le [rendu de la chronologie](/docs/apps/developer-platform/add-features/app-events/reference#rendering-templates) via l'objet `extraData`.

<Warning>
  L'objet `extraData` peut seulement contenir un JSON valide. Si le JSON est erroné, l'occurrence sera rejetée et vous recevrez une réponse d'erreur.
</Warning>

Les valeurs des champs `extraData` sont accessibles selon le type d'événement `detailTemplate` utilisant la syntaxe `{{extraData.fieldName}}`. Tous les niveaux d'attribut de `extraData` sont disponibles par le biais de la notation par points, comme `{{extraData.person1.preferredName}}`.

Par exemple, les modèles ci-dessous utilisent les données de propriété `customerName` et `loginLocation`, ainsi que le champ `surveyData` de `extraData` [envoyé via l'occurrence d'événement](#event-occurrences).

![Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact.](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/example-timeline-event-rendering-template.png)

<Tabs>
  <Tab title="Données sur l'occurrence d'événements">
    ```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="Configuration du modèle de chronologie">
    ```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>