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

# Enviar ocorrências de evento (BETA)

> Saiba como enviar dados de ocorrência de evento para o HubSpot usando os esquemas de tipo de evento que você definiu.

Após [definir um esquema de tipo de evento](en-us/apps/developer-platform/build-apps/features/app-events/create-and-manage-event-types) e [recuperar seu fullyQualifiedName](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname), você pode enviar dados de ocorrência do evento por meio da API de eventos do aplicativo. Ao enviar dados de eventos, você precisa seguir o esquema já criado. As solicitações que não corresponderem ao esquema não passarão na validação e não serão capturadas pelo aplicativo.

## Envio de ocorrências de evento

<Tabs>
  <Tab title="Enviar uma única ocorrência">
    Para enviar uma única ocorrência de evento, faça uma solicitação de `POST` para `/integrators/timeline/v4/events`.

    No corpo da solicitação, inclua dados de evento seguindo o esquema definido do tipo de evento juntamente com o valor `fullyQualifiedName` em um 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 um lote de ocorrências">
    Para enviar um lote de ocorrências de evento, faça uma solicitação de `POST` para `/integrators/timeline/v4/events/batch`.

    No corpo da solicitação, inclua até 500 objetos de ocorrência de evento separados por vírgula em uma matriz `inputs`. Mesmo que alguma ocorrência não seja validada, as ocorrências validadas serão aceitas e mantidas.

    ```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">
  Campos marcados com <span style={{ color: 'red' }}>\*</span> são obrigatórios.
</p>

| Campo                                                | Tipo   | Descrição                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventTypeName`<span style={{color:"red"}}>\*</span> | String | O nome totalmente qualificado do tipo de evento, usado para identificar o evento via API. Esse valor é automaticamente definido pelo HubSpot e pode ser [obtido através da API](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname) depois da criação do tipo de evento. Este valor não pode ser alterado após a criação. |
| `objectId`<span style={{color:"red"}}>\*</span>      | String | O ID do registro de CRM para associar à ocorrência do evento. Este campo pode ser usado para todos os tipos de registros de CRM e é o identificador recomendado. Saiba mais sobre [associação de registro de CRM](#crm-record-association).                                                                                                                                           |
| `email`                                              | String | Para associações de contato, você pode fornecer o endereço de e-mail do contato a ser associado. Saiba mais sobre [associação de registro de CRM](#crm-record-association).                                                                                                                                                                                                           |
| `utk`                                                | String | Para associações de contato, você pode fornecer o token de usuário de um contato existente para associar. Saiba mais sobre [associação de registro de CRM](#crm-record-association).                                                                                                                                                                                                  |
| `domain`                                             | String | Inclua este campo além de `objectId` para definir o valor da propriedade de `domain` da empresa. Saiba mais sobre [associação de registro de CRM](#crm-record-association).                                                                                                                                                                                                           |
| `timestamp`                                          | String | Define a hora da ocorrência do evento (formato [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Se não for fornecida, o HubSpot usará como padrão o carimbo de data/hora do envio de dados de ocorrência de evento.                                                                                                                                                               |
| `properties`                                         | Objeto | Pares chave-valor de nomes de propriedades e valores de propriedades que você configurou para o tipo de evento. Saiba mais sobre [propriedades de evento](/apps/developer-platform/add-features/app-events/reference#event-properties).                                                                                                                                               |
| `extraData`                                          | Objeto | Informações adicionais disponíveis para [modelos de renderização de linhas do tempo](/apps/developer-platform/add-features/app-events/reference#rendering-templates). Deve estar em um formato JSON válido.                                                                                                                                                                           |
| `timelineIFrame`                                     | Objeto | Quando incluído, o cartão de linha do tempo conterá um hiperlink que permite que os usuários abram o conteúdo vinculado em um iframe. Saiba mais sobre [como usar iframes](/apps/developer-platform/add-features/app-events/reference#using-iframes).                                                                                                                                 |
| `id`                                                 | String | Um identificador exclusivo para a ocorrência do evento. Deve ser exclusivo dentro do tipo de evento. Se não for fornecido, o HubSpot gerará um UUID aleatório. Quando houver vários eventos com o mesmo ID, o primeiro será aceito e todos os outros serão rejeitados.                                                                                                                |

## Associação de registro de CRM

Cada ocorrência de evento deve ser associada a um registro de CRM, com o tipo de objeto de CRM definido pelo esquema de tipo de evento. A API de eventos de aplicativo inclui vários campos para associar dados de ocorrência de evento com registros de CRM. Para todos os objetos de CRM compatíveis, recomendamos usar o campo `objectId`. No entanto, há algumas situações em que outros campos devem ser usados.

* `utk`/`email`: se você não souber o ID do contato, use o campo `utk` e/ou `email` para identificação. Fornecer esses dois identificadores também permite criar e atualizar contatos. Por exemplo:
  * Se `utk` corresponde a um contato existente, mas `email` não corresponde, o HubSpot atualizará o contato (por `utk`) com o novo endereço de e-mail.
  * Se nenhum `objectId` for fornecido, a ocorrência do evento será associada a um contato existente que corresponda ao `utk`/`email`, ou HubSpot criará um contato se nenhuma correspondência for encontrada.
  * Observe que o `utk` sozinho não pode criar novos contatos. Você deve sempre incluir `email` com `utk` para que associação seja adequada.
* `domain`: para associações de empresa, você deve fornecer o `objectId`, mas você também pode incluir `domain` para atualizar a propriedade de `domain` daquela empresa.

Veja abaixo a ordem de prioridade das propriedades de associação de registros de CRM, em que o menor número tem a maior prioridade:

| Campo      | Prioridade | Descrição                                           |
| ---------- | ---------- | --------------------------------------------------- |
| `objectId` | 1          | O ID do registro de CRM (recomendado).              |
| `utk`      | 2          | O token de usuário do contato (somente contatos).   |
| `email`    | 3          | O endereço de e-mail do contato (somente contatos). |
| `domain`   | 4          | O domínio de empresas (apenas empresas).            |

## Enviar dados adicionais

Além de enviar dados para [propriedades do evento](/apps/developer-platform/add-features/app-events/reference#event-properties) e [atualização de propriedades de CRM via ocorrências de evento](/apps/developer-platform/add-features/app-events/reference#property-stamping), você pode incluir dados adicionais para [renderização de linha do tempo](/apps/developer-platform/add-features/app-events/reference#rendering-templates) através do objeto `extraData`.

<Warning>
  O objeto `extraData` só pode conter JSON válido. Se o JSON estiver malformado, a ocorrência será rejeitada e você receberá uma resposta de erro.
</Warning>

Valores de campo `extraData` podem ser acessados pelo tipo de evento `detailTemplate` usando a sintaxe `{{extraData.fieldName}}`. Todos os níveis de atributo de `extraData` estão disponíveis por meio de notação de ponto, como `{{extraData.person1.preferredName}}`.

Por exemplo, os modelos abaixo usam os dados de propriedade `customerName` e `loginLocation` com o campo `surveyData` de `extraData` [enviado através da ocorrência do evento](#event-occurrences).

![Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato.](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/example-timeline-event-rendering-template.png)

<Tabs>
  <Tab title="Dados de ocorrência do 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="Configuração do modelo de linha do tempo">
    ```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>