> ## 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 conclusões de eventos personalizados

export const SupportedProducts = ({marketing, sales, service, cms, marketingLevel, salesLevel, serviceLevel, cmsLevel}) => {
  const translations = {
    header: "Produtos suportados",
    description: "Requer um dos seguintes produtos ou superior.",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub"
    },
    tiers: {
      free: "Grátis",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
    alt: "Content Hub"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

export const ScopesList = ({scopes = [], description = "Esta API requer um dos seguintes escopos:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<AccordionGroup>
  <Accordion title="Produtos suportados" defaultOpen="true" icon="cubes">
    <SupportedProducts marketing={true} marketingLevel="enterprise" sales={true} salesLevel="enterprise" service={true} serviceLevel="enterprise" cms={true} cmsLevel="enterprise" />
  </Accordion>

  <Accordion title="Requisitos de escopo">
    <ScopesList
      scopes={[
  'analytics.behavioral_events.send'
]}
    />
  </Accordion>
</AccordionGroup>

<RelatedApiLink />

Eventos personalizados são eventos definidos por conta que armazenam detalhes de eventos em propriedades de eventos. Além de [personalizar seu código de rastreamento](/docs/api-reference/legacy/tracking-code-v1/overview) para enviar dados de eventos à HubSpot, você também pode enviar dados de conclusão de eventos por meio desta API.

Abaixo, aprenda como usar a API para criar eventos personalizados e enviar/recuperar dados de eventos personalizados.

## Definir o evento

Para enviar dados de conclusão de evento para o HubSpot, primeiro você precisa definir o evento, incluindo seus metadados, associações de objetos do CRM e propriedades. Você pode definir eventos usando a [API de definição de evento personalizado](/docs/api-reference/events-manage-event-definitions-v3/guide) ou, se você tiver uma assinatura do ***Marketing Hub** Enterprise*, poderá [criar o evento no HubSpot](https://knowledge.hubspot.com/pt/analytics-tools/create-codeless-custom-behavioral-events). Ao criar o evento, a HubSpot fornecerá a opção de incluir um conjunto de [propriedades de eventos padrão](/docs/api-reference/events-manage-event-definitions-v3/guide#hubspot-s-default-event-properties) que você pode usar para armazenar dados de eventos. Você também pode [criar propriedades adicionais](/docs/api-reference/events-manage-event-definitions-v3/guide#define-new-properties) para o evento. Essas propriedades podem ser criadas ou editadas a qualquer momento.

Depois de configurar seu evento, você pode enviar dados para ele por meio da API ou por [personalizar seu código de rastreamento da HubSpot](/docs/api-reference/legacy/tracking-code-v1/overview).

## Enviar dados de evento

Para enviar dados de evento ao HubSpot, faça uma solicitação `POST` para `https://api.hubspot.com/events/v3/send` com os dados do evento no corpo da solicitação. Antes de enviar dados de evento, revise os limites abaixo, pois exceder esses limites resultará em erro.

```json theme={null}
{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}
```

| Parâmetro    | Tipo   | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventName`  | String | O nome interno do evento. Você pode encontrar isso [consultando suas definições de evento existentes](/docs/api-reference/events-manage-event-definitions-v3/guide#get-existing-event-definitions) ou [no aplicativo HubSpot](https://knowledge.hubspot.com/pt/reports/create-custom-events#find-internal-name).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `objectId`   | String | O ID do registro do CRM com o qual o evento será associado. Para contatos, você pode alternativamente usar o campo `email` ou `utk` para identificar o contato pelo endereço de e-mail ou pelo [Token de Usuário da HubSpot](/docs/api-reference/legacy/tracking-code-v1/overview). Todos os outros tipos de objetos requerem `objectId`, a menos que um ID correspondente personalizado seja definido para o evento. Se um `customMatchingId` é definido para o evento, a HubSpot definirá ou substituirá automaticamente o `objectId` com base no mapeamento configurado. Saiba mais no [guia de definições de eventos personalizados](/docs/api-reference/events-manage-event-definitions-v3/guide#create-an-event-definition).                                                                                                                                                                                                                                                                                                                                 |
| `occurredAt` | String | Por padrão, o HubSpot definirá a data/hora de conclusão do evento para a hora em que a solicitação foi enviada. Para especificar a hora de conclusão do evento, inclua um carimbo de data/hora em um campo `occurredAt` no corpo da solicitação `POST` ([Formato ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Isso pode ser especialmente útil para datar retroativamente dados de eventos para refletir com mais precisão a conclusão de eventos reais.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `properties` | Objeto | As propriedades de evento às quais enviar dados. Isso pode incluir [propriedades de evento padrão do HubSpot](/docs/api-reference/events-manage-event-definitions-v3/guide#hubspot-s-default-event-properties) ou qualquer [propriedades personalizadas](/docs/api-reference/events-manage-event-definitions-v3/guide#define-new-properties) você definiu para o evento. A maioria das propriedades de evento padrão são propriedades de string, mas você pode revisar todas as propriedades de evento [consultando a definição do evento](/docs/api-reference/events-manage-event-definitions-v3/guide#get-existing-event-definitions) ou navegando até o evento no HubSpot. Se um ID de correspondência personalizado for [preparado para o evento](/docs/api-reference/events-manage-event-definitions-v3/guide#create-an-event-definition), você pode omitir o `objectId`. A HubSpot tentará vincular o evento a um objeto CRM definindo o `objectId` no evento com base no mapeamento configurado. Saiba mais sobre [propriedades de evento](#event-properties) abaixo. |

<Warning>
  ### Observação:

  Exceder qualquer um dos limites a seguir resultará em falha na solicitação:

  * O rótulo da propriedade e o nome interno são limitados a 50 caracteres.
  * Propriedades de URL e de referência podem ter até 1.024 caracteres, enquanto todas as outras propriedades podem ter até 256 caracteres.
  * Cada conclusão de evento pode conter dados para até 50 propriedades.
  * Os nomes internos da propriedade devem começar com uma letra e conter apenas letras minúsculas de a-z, números de 0-9 e sublinhados.
  * As propriedades com o mesmo nome interno após minúsculas serão consideradas duplicatas e apenas uma delas será usada na conclusão. O HubSpot classificará em ordem lexicográfica ascendente e manterá as últimas propriedades vistas entre as primeiras 50 propriedades.
  * Há um limite de 500 definições de eventos exclusivos por conta.
  * Há um limite de 30 milhões de finalizações de eventos por mês.
</Warning>

## Recuperar dados de evento

Para [recuperar dados de eventos](/docs/api-reference/events-manage-event-definitions-v3/guide#get-%2Fevents%2Fv3%2Fevents%2F), faça uma `GET` solicitação para `/events/v3/events`.

* Para retornar todas as conclusões de eventos para um evento específico, inclua o parâmetro `eventType` junto com o nome do evento interno (por exemplo, `pe123456_custom_event`). Você pode recuperar todos os tipos de eventos usando a [API de análise de eventos](/docs/api-reference/events-manage-event-definitions-v3/guide#get-%2Fevents%2Fv3%2Fevents%2Fevent-types).
* Para retornar conclusões de eventos para um objeto específico, inclua o parâmetro `objectType` junto com os parâmetros `objectId` ou `objectProperty.<property>`. O `objectType` deve especificar o tipo de objeto CRM (por exemplo, `contact`), enquanto os outros parâmetros especificam o valor do identificador exclusivo para o objeto (ID do registro ou um valor de propriedade do identificador exclusivo). Para contatos, você pode usar `email` como uma propriedade de identificador exclusivo.

Por exemplo, para recuperar todos os eventos concluídos por um contato específico, sua URL de solicitação poderia ser:

`/events/v3/events?objectType=contact&objectId=111111`.

Alternativamente, você pode usar o endereço de e-mail do contato:

`/events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com`

Para filtrar os resultados por conclusões de eventos com um valor de propriedade de evento específico, você pode incluir o parâmetro `property.<propertyName>`. Por exemplo, para recuperar eventos de visita à página inicial, o URL da solicitação pode ser:

`/events/v3/events?eventType=e_visited_page&property.hs_page_title=home`

<Info>
  Para valores de propriedade com espaços, substitua os espaços por `%20` ou
  `+`. Por exemplo, `property.hs_page_title=home+page`.
</Info>

Saiba mais sobre os parâmetros disponíveis na [documentação de referência](/docs/api-reference/events-manage-event-definitions-v3/guide#get-%2Fevents%2Fv3%2Fevents%2F).

## Propriedades do evento

Os dados de conclusão do evento são armazenados nas propriedades do evento, no conjunto de [propriedades de eventos padrão](/docs/api-reference/events-manage-event-definitions-v3/guide#hubspot-s-default-event-properties) ou em [propriedades definidas pelo usuário](/docs/api-reference/events-manage-event-definitions-v3/guide#define-new-properties). Ao enviar dados de eventos, inclua um objeto `properties` com pares chave-valor para as propriedades que você deseja atualizar, juntamente com os valores das propriedades a serem armazenados.

```json theme={null}
"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }
```

Os valores que você envia dependerão do tipo de propriedade de evento. A maioria das propriedades de evento padrão é texto de linha única (string). Entretanto, você pode criar propriedades personalizadas de qualquer tipo para cada evento. Revise a tabela abaixo ao formatar os valores de propriedade.

| Propriedade Tipo | Descrição                                                                                                                                                                                                                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bool`           | Um valor booleano `true` ou `false`.                                                                                                                                                                                                                                                                                      |
| `enumeration`    | Uma string que representa um conjunto de opções. Ao enviar vários valores, separe-os com um ponto e vírgula. No HubSpot, esse tipo corresponde a propriedades de seleção suspensa, botão de opções e várias caixas de seleção.                                                                                            |
| `date`           | Um valor que representa um dia, mês e ano específicos. Os valores devem ser representados na hora UTC e podem ser formatados como [Strings ISO 8601](/docs/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties) ou carimbos de data/hora EPOCH em milissegundos (ou seja, meia-noite UTC).        |
| `datetime`       | Um carimbo de data/hora que representa um dia, mês, ano e hora do dia específicos. Os valores devem ser representados em hora UTC e podem ser formatados como [strings de ISO 8601 ou registros de data e hora UNIX em milissegundos](/docs/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties). |
| `number`         | Um valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal. No HubSpot, este tipo corresponde às propriedades de número e cálculo.                                                                                                                                                         |
| `string`         | Uma string de texto simples, com no máximo 65.536 caracteres. No HubSpot, esse tipo corresponde a propriedades de texto de linha única e de várias linhas.                                                                                                                                                                |

Para exibir as propriedades disponíveis de um evento:

* Na sua conta HubSpot, acesse **Gestão de Dados** > **Eventos personalizados**.
* Na tabela, clique no **nome** do evento.
* Na parte superior, clique na aba **Propriedades**.
* Na tabela de propriedades, veja o tipo sob o nome da propriedade.

<Frame>
  <img src="https://br.hubspot.com/hubfs/Knowledge_Base_2021/Developer/custom-event-properties-table.png" alt="custom-event-properties-table" />
</Frame>

## Relatórios de atribuição

Eventos JavaScript, como [elemento clicado](https://knowledge.hubspot.com/pt/analytics-tools/create-codeless-custom-behavioral-events) e [URL visitada](https://knowledge.hubspot.com/pt/analytics-tools/create-codeless-custom-behavioral-events), são preenchidos automaticamente com o tipo de ativo e os dados de interação para os relatórios de atribuição. Para incluir os mesmos dados para eventos rastreados manualmente, você precisará incluir manualmente os dados no corpo da solicitação usando as propriedades do evento. Saiba mais sobre [análises de eventos personalizados](https://knowledge.hubspot.com/pt/analytics-tools/analyze-custom-behavioral-events).

Abaixo, conheça os valores disponíveis para tipos de ativos e origens de interação, juntamente com solicitações de exemplo.

### Tipo de ativo

Para atribuir um tipo de ativo específico a uma solicitação de evento comportamental personalizado, inclua a propriedade `hs_page_content_type` no corpo da solicitação. Por exemplo:

```json theme={null}
{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}
```

<Info>
  Você também pode usar a propriedade `hs_asset_type`. Se ambos `hs_page_content_type` e `hs_asset_type` estiverem incluídos em uma única solicitação, `hs_page_content_type` substituirá o valor `hs_asset_type`.
</Info>

Os tipos de conteúdo padrão do HubSpot, como landing pages e posts de blog, podem ser representados com os seguintes valores:

| Valor               | Descrição                                               |
| ------------------- | ------------------------------------------------------- |
| `STANDARD_PAGE`     | Uma interação com uma página do site.                   |
| `LANDING_PAGE`      | Uma interação com uma landing page.                     |
| `BLOG_POST`         | Uma interação com uma postagem de blog.                 |
| `KNOWLEDGE_ARTICLE` | Uma interação com um artigo da central de conhecimento. |

Para todos os outros tipos de ativos, use os seguintes valores:

| Valor                          | Descrição                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
| `AD`                           | Uma interação com um anúncio, como um anúncio do Facebook ou do Google.                          |
| `CALL`                         | Uma interação com uma chamada.                                                                   |
| `CONTACT_IMPORT`               | Uma interação através de uma importação de contato.                                              |
| `CONVERSATION`                 | Uma interação relacionada a uma conversa HubSpot.                                                |
| `CUSTOM_BEHAVIORAL_EVENT_NAME` | O nome interno de um evento personalizado, como`pe123456_manually_tracked_event`.                |
| `EMAIL`                        | Uma interação com um e-mail.                                                                     |
| `EXTERNAL_PAGE`                | Uma interação com uma página externa.                                                            |
| `INTEGRATIONS`                 | Uma interação via integração.                                                                    |
| `MARKETING_EVENT`              | Uma interação com um [evento de marketing](/docs/api-reference/marketing-marketing-events-v3/guide) . |
| `MEDIA_BRIDGE`                 | Uma interação via [media bridge](/docs/api-reference/cms-media-bridge-v1/guide).                      |
| `MEETING`                      | Uma interação com uma reunião.                                                                   |
| `SALES_EMAIL`                  | Uma interação com um e-mail de vendas individual.                                                |
| `SEQUENCE`                     | Uma interação com uma sequência.                                                                 |
| `SOCIAL_POST`                  | Uma interação com um post de mídia social.                                                       |
| `OTHER`                        | Uma interação com um ativo que não está em uma das categorias acima.                             |

### Título de ativo

Para atribuir um evento personalizado a um ativo, inclua a propriedade `hs_page_title` ou `hs_asset_title` em sua solicitação com o nome do ativo formatado como uma string. Por exemplo:

`hs_page_title:`

```json theme={null}
{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}
```

### Fontes de interação

Para atribuir um evento comportamental personalizado a uma fonte específica, inclua a propriedade `hs_touchpoint_source` em sua solicitação com um dos seguintes valores:

| Valor             | Descrição                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `CONVERSATION`    | A fonte da interação é uma conversa.                                                                 |
| `DIRECT_TRAFFIC`  | A fonte da interação é tráfego direto.                                                               |
| `EMAIL_MARKETING` | A fonte da interação é um e-mail de marketing.                                                       |
| `HUBSPOT_CRM`     | A fonte da interação é o CRM da HubSpot.                                                             |
| `INTEGRATION`     | A fonte da interação é uma integração.                                                               |
| `MARKETING_EVENT` | A fonte da interação é um [evento de marketing](/docs/api-reference/marketing-marketing-events-v3/guide). |
| `OFFLINE`         | A fonte da interação é offline.                                                                      |
| `ORGANIC_SEARCH`  | A fonte de interação é a busca orgânica.                                                             |
| `OTHER_CAMPAIGNS` | A fonte da interação é uma campanha não categorizada.                                                |
| `PAID_SEARCH`     | A fonte da interação é um anúncio de pesquisa pago.                                                  |
| `PAID_SOCIAL`     | A fonte da interação é um anúncio de redes sociais pago.                                             |
| `REFERRALS`       | A fonte da interação é uma referência.                                                               |
| `SALES`           | A fonte da interação é vendas.                                                                       |
| `SOCIAL_MEDIA`    | A fonte da interação é mídias sociais (não um anúncio de redes sociais pago).                        |