> ## 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.
# Definir eventos personalizados
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
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Os eventos personalizados permitem que você defina e rastreie eventos exclusivos da sua empresa, como eventos no seu site ou em um aplicativo. Você pode configurar eventos para armazenar informações nas propriedades, que podem ser usadas nas ferramentas do HubSpot.
Para enviar dados de um [evento personalizado](/api-reference/events-send-event-completions-v3/guide) para o HubSpot, primeiro você precisa definir o evento. Esse processo é semelhante aos objetos personalizados do CRM, onde você primeiro define o objeto personalizado e depois cria registros individuais para esse objeto. Uma definição de evento inclui detalhes como metadados, associações de objetos do CRM e propriedades.
Abaixo, saiba mais sobre como criar e gerenciar definições de eventos usando a API. Para saber como criar definições de eventos sem usar a API, confira a [Central de conhecimento da HubSpot](https://knowledge.hubspot.com/pt/reports/create-custom-events).
## Criar uma definição de evento
Para criar o esquema de evento personalizado, envie uma solicitação `POST` para `events/v3/event-definitions`. No corpo da solicitação, inclua as definições do seu esquema de evento, incluindo rótulo, nome, associações de objetos do CRM e propriedades personalizadas.
O corpo da solicitação abaixo fornece um exemplo básico de uma definição de 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
}
```
Se quiser vincular automaticamente conclusões de eventos a registros de um tipo de Objeto do CRM especificado, você pode incluir um `customMatchingId` em seu pedido `POST`. Neste campo, defina um objeto `primaryObjectRule` com dois campos: a propriedade de objeto exclusiva que você configurou anteriormente como a `targetObjectPropertyName` e uma das propriedades definidas na `propertyDefinitions` da sua definição de evento.
Por exemplo, o seguinte corpo de solicitação especifica um `customMatchingId` que corresponde a um nome de propriedade de Objeto do CRM de `"unique_object_property"` e o nome da propriedade 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"
}
}
}
```
Uma lista completa dos parâmetros disponíveis para o corpo da solicitação é detalhada na tabela abaixo:
| Parâmetro | Tipo | Descrição |
| -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | String | O rótulo legível do evento que será exibido no HubSpot (até 100 caracteres). Rótulos longos podem ser cortados em certas partes da interface do HubSpot. |
| `name` | String | O nome interno exclusivo do evento que você usará para fazer referência ao evento por meio da API. Se nenhum valor for fornecido, a HubSpot gerará automaticamente um com base no rótulo.
Esta propriedade não pode ser alterada após a criação da definição de evento.
Esta propriedade pode conter apenas letras minúsculas, números, sublinhados e hifens (até 50 caracteres).
O primeiro caractere deve ser uma letra.
|
| `description` | String | A descrição do evento que será exibida no HubSpot. |
| `primaryObject` | String | O tipo de objeto do CRM ao qual os dados de evento serão associados. Conclusões de evento aparecerão nos registros de CRM daquele tipo de objeto. Pode ser um de: `"CONTACT"` (padrão), `"COMPANY"`, `"DEAL"`, `"TICKET"`, `""`. Isso não poderá ser alterado depois que a definição do evento for criada. |
| `propertyDefinitions` | Matriz | Além das [Propriedades do evento padrão HubSpot](#hubspot-s-default-event-properties), você pode incluir essa matriz para definir as propriedades do evento personalizado (até 50). Para cada objeto de propriedade, inclua os seguintes campos:
`name`: o nome interno da propriedade, que você usará ao enviar dados de evento por meio da API.
`label`: o rótulo no aplicativo da propriedade.
`type`: o [tipo de propriedade](#event-properties). O padrão é `string`.
`options`: para propriedades de tipo `enumeration`, esta matriz define os valores disponíveis. Deve incluir um `label` e `value` para cada opção.
`description`: texto que descreve a propriedade.
|
| `customMatchingId` | Objeto | Como uma alternativa para incluir as informações do objeto de destino `objectId` nos dados de conclusão do evento, esse campo opcional define uma regra para vincular automaticamente conclusões de evento a registros do tipo de objeto do CRM especificado. Isso é feito através da correspondência do valor de uma propriedade nos dados do evento com o valor de uma propriedade exclusiva no objeto alvo. Este objeto deve incluir um objeto `primaryObjectRule`, que por sua vez deve incluir dois campos:
`targetObjectPropertyName`: uma cadeia de caracteres que especifica o nome da propriedade exclusiva no objeto do CRM de destino a ser usada para correspondência.
`eventPropertyName`: uma cadeia de caracteres que especifica o nome da propriedade nos dados de evento personalizado a serem usados para correspondência.
|
| `includeDefaultProperties` | Booleano | Um campo opcional que especifica se o evento deve incluir o conjunto de [propriedades de evento padrão](#hubspot-s-default-event-properties). Se nenhum valor for fornecido, este campo será automaticamente definido como `true`. |
## Propriedades do evento
As propriedades de evento personalizado são usadas para armazenar informações sobre conclusões de eventos personalizados individuais. Elas devem ser usadas quando apropriado para enviar conclusões de eventos, mas não são obrigatórias para que uma conclusão de evento seja válida. Para cada definição de evento, o HubSpot fornece um conjunto padrão de 32 propriedades. Além disso, você pode criar até 50 propriedades personalizadas por definição de evento.
As propriedades podem ter os seguintes tipos:
* `bool`: uma propriedade que recebe um valor booleano. Os valores devem ser representados como `true` ou `false`.
* `date`: uma propriedade que recebe uma data 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](/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`: Uma propriedade que recebe valores de milissegundos de era ou ISO8601 que representam uma data/hora.
* `enumeration`: Uma propriedade com opções predefinidas. Ao criar esse tipo de propriedade, inclua uma matriz `options` para definir os valores disponíveis.
* `number`: propriedade que recebe valores numéricos com até uma casa decimal.
* `string`: uma propriedade que recebe strings de texto simples. Se o nome da propriedade contiver as palavras `url`, `referrer` ou `link`, o valor da propriedade poderá ter até 1.024 caracteres. Caso contrário, poderá ter até 256 caracteres.
Abaixo, saiba mais sobre as propriedades de evento padrão do HubSpot, como [definir novas propriedades para eventos existentes](#define-new-properties) e como [atualizar propriedades de eventos personalizados existentes](#update-existing-custom-properties).
### Propriedades de evento padrão do 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 novas propriedades
Para definir uma nova propriedade em um evento personalizado existente, envie uma solicitação `POST` para `events/v3/event-definitions/{eventName}/property`. No corpo da solicitação, inclua a definição da sua propriedade.
```json theme={null}
{
"name": "property-name",
"label": "Property name",
"type": "enumeration",
"options": [
{
"label": "label",
"value": "value"
}
]
}
```
Ao nomear sua propriedade, tenha em mente o seguinte:
* Depois de criar uma propriedade, o nome da propriedade não poderá ser alterado.
* O nome somente pode conter letras minúsculas, números, sublinhados e hifens.
* O primeiro caractere do nome da propriedade deve ser uma letra.
* O nome e o rótulo da propriedade podem ter até 50 caracteres cada.
* Se um nome de propriedade não for fornecido, um será gerado automaticamente com base no rótulo da propriedade.
* Rótulos longos podem ser cortados em certas partes da interface do HubSpot.
### Atualizar propriedades personalizadas existentes
Para atualizar uma propriedade existente em um evento personalizado, envie uma solicitação `PATCH` para `events/v3/event-definitions/{eventName}/property`. Os únicos campos que podem ser atualizados em uma propriedade são `label`, `description` e `options` para propriedades de enumeração.
### Observação:
Para alterar o tipo de propriedade, utilize o ponto de extremidade `DELETE` para excluir a propriedade e recriá-la com o tipo correto.
### Excluir uma propriedade
Para excluir uma propriedade existente em um evento personalizado, envie uma solicitação `DELETE` para `events/v3/event-definitions/{eventName}/property/{propertyName}`.
Quando uma propriedade é excluída, ela não pode ser usada em conclusões de eventos futuros. Conclusões anteriores ainda terão os valores das propriedades.
## Atualizar um evento
Para atualizar um esquema de evento personalizado existente, envie uma solicitação `PATCH` para `events/v3/event-definitions/{eventName}`.
Os únicos campos de definição de evento que podem ser atualizados são `label` e `description`.
```json theme={null}
{
"label": "Event label",
"description": "A description of the event"
}
```
## Excluir um evento
Para excluir um evento personalizado, envie uma solicitação `DELETE` para `events/v3/event-definitions/{eventName}`.
A exclusão de um evento personalizado o removerá de qualquer outra ferramenta HubSpot que o faça referência, como fluxos de trabalho e relatórios.
### Observe que ao excluir um evento:
1. Todos os eventos dessa definição de evento serão excluídos e não poderão ser recuperados.
2. `eventName`S excluídos anteriormente não podem ser usados novamente, portanto tenha cuidado ao excluir um evento.
## Obter definições de eventos existentes
Para buscar uma definição de evento único, envie uma solicitação `GET` para `events/v3/event-definitions/{eventName}`.
Para pesquisar definições de eventos por critérios específicos, envie uma solicitação `GET` para `events/v3/event-definitions`. Você pode fornecer os seguintes parâmetros de consulta para refinar sua pesquisa:
* `searchString`: pesquisa eventos que contenham os caracteres especificados no campo `name`. A pesquisa não é flexível, mas sim uma pesquisa simples de *contém*.
* `after`: uma string com hash fornecida nas respostas paginadas para visualização da próxima página de resultados de pesquisa.
* `limit`: o número máximo de resultados a serem retornados.
* `includeProperties`: um valor booleano que especifica se as propriedades do evento devem ser incluídas nos resultados retornados.