Propriedades

Use propriedades para armazenar informações em registros do CRM. A HubSpot fornece um conjunto de propriedades padrão para cada objeto do CRM e você também pode criar e gerenciar suas próprias propriedades personalizadas no HubSpot ou usando a API de propriedades. 

Ao criar propriedades, é importante considerar como organizar seus dados. Em muitos casos, a estratégia correta é a criação de propriedades personalizadas para os objetos padrão da HubSpot. No entanto, em alguns casos, talvez você precise criar um objeto personalizado separado com seu próprio conjunto de propriedades.

Propriedades padrão

Os objetos de CRM são definidos por um tipo principal e um conjunto de propriedades. Cada tipo tem um conjunto exclusivo de propriedades padrão, representado por um mapeamento de pares nome-valor. 

Saiba mais sobre propriedades padrão para diferentes objetos:

Grupos de propriedades

Os grupos de propriedades são usados para agrupar propriedades relacionadas. Todas as propriedades agrupadas aparecerão lado a lado nos registros do HubSpot. Se sua integração criar quaisquer propriedades de objeto personalizadas, um grupo de propriedades personalizadas facilitará a identificação desses dados.

Tipo de propriedade e valores fieldType

Ao criar ou atualizar propriedades, os valores type e fieldType são obrigatórios. O valor type determina o tipo da propriedade, ou seja, uma string ou um número. A propriedade fieldType determina como a propriedade aparecerá no HubSpot ou em um formulário, ou seja, como um campo de texto simples, um menu suspenso ou um seletor de data.

Na tabela abaixo, saiba mais sobre o type de propriedade disponível e os valores fieldType correspondentes.

Valores válidos para type e valores fieldType compatíveis
type Descrição Valores fieldType válidos
bool Um campo que contém opções binárias (por exemplo, Yes ou No, True ou False). booleancheckbox, calculation_equation
enumeration Uma string que representa um conjunto de opções separadas por ponto e vírgula. booleancheckbox, checkbox, radio, select, calculation_equation
date Um valor que representa um dia, mês e ano 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 EPOCH em milissegundos (ou seja, meia-noite UTC). date
dateTime Um valor que representa um dia, mês, ano e horário do dia específicos. O aplicativo HubSpot não exibirá o horário do dia. 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. date
string Uma string de texto simples, com no máximo 65.536 caracteres. file, text, textarea, calculation_equation, html, phonenumber
number Um valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal. number, calculation_equation
object_coordinates Um valor de texto usado para referenciar outros objetos do HubSpot, usado apenas para Propriedades internas. As propriedades deste tipo não podem ser criadas ou editadas e não são visíveis no HubSpot. text
json Um valor de texto armazenado como JSON formatado, utilizado apenas para propriedades internas. As propriedades deste tipo não podem ser criadas ou editadas e não são visíveis no HubSpot. text

Os valores válidos para fieldType incluem:

FieldtypeDescription
booleancheckbox

Uma entrada que permite que os usuários selecionem Sim ou Não. Quando usada em um formulário, essa entrada aparecerá como uma única caixa de seleção. Saiba como adicionar um valor a propriedades de caixa de seleção única.

calculation_equation

Uma equação personalizada que pode calcular valores com base em outros valores de propriedades e/ou associações. Saiba como definir propriedades de cálculo.

caixa de seleção .

Uma lista de caixas de seleção que permite que um usuário selecione várias opções em um conjunto de opções válidas para a propriedade. Saiba como formatar valores ao atualizar propriedades de várias caixas de seleção.

data

Um valor de data, que é exibido como um seletor de data.

file

Permite que um arquivo seja carregado em um registro ou por meio de um formulário. Armazena um ID de arquivo.

html

Uma string, renderizada como html corrigido, que permite o uso de um editor de rich text para a propriedade.

número

Uma string de numerais ou números escritos em formato decimal ou em notação científica.

phonenumber

Uma string de texto simples, exibida como um número de telefone formatado.

botão de opções

Uma entrada que permite que os usuários selecionem um conjunto de opções válidas para a propriedade. Quando usada em um formulário, essa entrada é exibida como um conjunto de botões de opção.

select

Uma entrada suspensa que permite que os usuários selecionem um conjunto de opções válidas para a propriedade.

text

Uma string de texto simples, que é exibida em uma entrada de texto com uma única linha.

textarea

Uma string de texto simples, que é exibida como uma entrada de texto com várias linhas.

Criar uma propriedade

Para criar uma propriedade, faça uma solicitação POST para /crm/v3/properties/{objectType}. No corpo da solicitação, inclua os seguintes campos obrigatórios:

  • groupName: o grupo de propriedades em que a propriedade estará inserida.
  • name: o nome interno da propriedade (por exemplo, favorite_food).
  • label: o nome da propriedade tal como aparece no HubSpot (por exemplo, Favorite Food).
  • type: o tipo da propriedade.
  • fieldType: o tipo de campo da propriedade.

Por exemplo, para criar uma propriedade de contato chamada Favorite Food, a solicitação seria semelhante à seguinte:

/// Example request body POST crm/v3/properties/contacts { "groupName": "contactinformation", "name":"favorite_food", "label": "Favorite Food", "type": "string", "fieldType": "text" }

Criar propriedades de identificador exclusivo

Quando um registro é criado no HubSpot, um ID de registro exclusivo (hs_object_id) é gerado automaticamente e deve ser tratado como uma string. Esses IDs são exclusivos apenas dentro do tipo de objeto; pode haver um contato e uma empresa com o mesmo ID. Para contatos e empresas, existem identificadores exclusivos adicionais, incluindo o endereço de e-mail de um contato (email) e o nome de domínio de uma empresa (domain).

Em alguns casos, você deseja criar sua própria propriedade de identificador exclusivo para que não seja possível inserir o mesmo valor para vários registros. Você pode ter até dez propriedades de ID exclusivas por objeto. Para criar uma propriedade que requer valores exclusivos via API:

  • Faça uma solicitação POST para /crm/v3/properties/{objectType}.
  • No corpo da solicitação, para o campo hasUniqueValue, defina o valor como true.
/// Example request body { "groupName": "dealinformation", "name":"system_a_unique", "label": "Unique ID for System A", "hasUniqueValue": true, "type": "string", "fieldType": "text" }

Depois de criar sua propriedade de ID exclusivo, você poderá usá-la em uma chamada de API para recuperar registros específicos. O URL de solicitação pode ser semelhante ao seguinte: GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_unique. Essa chamada retornará o negócio com o valor abc no campo system_a_unique.

Você pode usar esse valor de propriedade de identificador exclusivo para identificar e atualizar registros específicos da mesma forma que usaria hs_object_id, email (contatos) ou domain (empresas).

Criar propriedades de cálculo

As propriedades de cálculo definem um valor de propriedade com base em outras propriedades dentro do mesmo registro de objeto. Elas são definidas usando uma fórmula, que pode incluir operações como mín., máx., contagem, soma ou média. Você pode usar a API de propriedades para ler ou criar propriedades de cálculo na sua conta da HubSpot, usando um tipo de campo de calculation_equation e um tipo de number, bool, string ou enumeration.

Você pode definir a fórmula de cálculo da propriedade com o campo calculationFormula

Observação: as propriedades de cálculo criadas por meio da API não podem ser editadas no HubSpot. Elas somente podem ser editadas por meio da API de propriedades.

Sintaxe da propriedade de cálculo

Com a calculationFormula, você pode escrever sua fórmula com operadores aritméticos, operadores de comparação, operadores lógicos, instruções condicionais e outras funções.

Sintaxe literal

  • Literal de string: strings constantes podem ser representadas com aspas simples ('constant') ou aspas duplas ("constant").
  • Literal de número: os números constantes podem ser quaisquer números reais e podem incluir notação de pontos. 1005 e 1.5589 são números constantes válidos.
  • Literal de booleano: booleanos constantes podem ser true ou false.

Sintaxe de propriedade

  • Variáveis de propriedade de string: para uma string de identificador ser interpretada como uma propriedade de string, ela deve ser vinculada à função string. Por exemplo, a string(var1)será interpretada como o valor var1 da propriedade de string.
  • Variáveis de propriedade numérica: todos os identificadores serão interpretados como variáveis de propriedade numérica.  Por exemplo, var1 será interpretado como o valor var1 da propriedade numérica.
  • Variáveis de propriedade booleana: para um identificador ser interpretado como uma propriedade bool, ele deve ser vinculado à função bool. Por exemplo, o identificador bool(var1) será interpretado como o valor var1 da propriedade booleana.

Observação: o texto usado diferencia maiúsculas de minúsculas para todos os tipos, exceto para strings. Por exemplo, If A ThEn B é exatamente o mesmo que if a then b, mas 'a' não é o mesmo que 'A'. Espaços, tabulações e novas linhas serão usados para tokenização, mas serão ignorados.

Operadores

Os operadores podem ser usados com valores literais e de propriedade. Para operadores aritméticos, você pode usar a notação de prefixo para multiplicar; e parênteses podem ser usados para especificar a ordem das operações.

OperadorDescriçãoExamples
+
Add numbers or strings.

propriedade1 + 100

-
Subtract numbers.property1 + 100 - property2
*
Multiply numbers. 10property1 = 10 * property1
-
Divide numbers.property1 * (100 - property2/(50 - property3))
<
Checks if a value is less than another. Supported by number properties or constants.a < 100
&gt;
Checks if a value is greater than another. Supported by number properties or constants.a > 50
&lt;=
Checks if a value is less than or equal to another. Supported by number properties or constants.a <= b
&gt;=
Checks if a value is greater than or equal to another. Supported by number properties or constants.

b>= c

=
Checks if a value is equal to another. Supported by both numbers and strings.(a + b - 100c * 150.652) = 150-230b
é igual a
Checks if a value is equal to another. Supported by both numbers and strings.a + b - 100.2c * 150 equals 150 - 230
!=
Checks if a value is not equal to another. Supported by both numbers and strings.string(property1) != 'test_string'
ou
Checks if either or two values are true. a > b or b <= c
e
Checks if both values are true.bool(a) and bool(c)
não
Checks if none of the values are true.not (bool(a) and bool(c))

Funções

As funções a seguir são compatíveis:

Use this table to describe parameters / fields
FunçãoDescriçãoExamples
máx.
Will have between 2 and 100 input numbers, and will return the maximum number out of all the inputs.max(a, b, c, 100) ou max(a, b)
mín.
Will have between 2 and 100 input numbers, and will return the minimum number of out all the inputs.

min(a, b, c, 100) ou min(a, b)

is_present
Evaluates whether an expression can be evaluated.

is_present(bool(a))= verdadeiro se a propriedade for booleana, mas is_present(bool(a)) = falso se a propriedade estiver vazia ou não for booleana.

contém
Has two strings as inputs and will return true if the first input contains the second.

contains('hello', 'ello') = true enquanto contains('ello', 'hello') = false.

concatenate
Joins a list of strings. The list of inputs can go from 2 up to 100.

concatenate('a', 'b', string(a), string(b))

Há também duas funções de análise:

  • number_to_string: tenta converter a expressão do número de entrada em uma string.
  • string_to_number: tenta converter a expressão da string de entrada em um número.

Por exemplo, "Number of cars: " + num_cars não é uma propriedade válida, pois você não pode adicionar uma string com um número, mas "Number of cars: " + number_to_string(num_cars) é.

Declarações condicionais

Você também pode escrever sua fórmula com declarações condicionais, usando if, elseif, endif e else.

Por exemplo, uma declaração condicional pode ser semelhante a seguinte: if boolean_expression then statement [elseif expression then statement]* [else statement | endif], onde os colchetes [a] representam que a é opcional, o a|brepresenta que a ou b funcionará e * significa 0 ou mais. O endif pode ser usado para terminar uma declaração condicional prematuramente, garantindo que o analisador possa identificar de qual if o próximo elseif pertence. 

Exemplos de fórmulas

Veja os seguintes exemplos que podem ser usados para ajudar a definir suas próprias fórmulas de cálculo:

//Example formula "calculationFormula": "closed - started"

Um exemplo mais avançado com condicionais:

//Example formula "calculationFormula": "if is_present(hs_latest_sequence_enrolled_date) then if is_present(hs_sequences_actively_enrolled_count) an hs_sequences_actively_enrolled_count >= 1 then true else false else ''"

Recuperar propriedades

É possível obter informações sobre propriedades individuais ou todas as propriedades de um objeto.

  • Para recuperar uma propriedade individual, faça uma solicitação GET para crm/v3/properties/{object}/{propertyName}. Por exemplo, para obter a propriedade Favorite Food, o URL da solicitação seria https://
    api.hubspot.com/crm/v3/properties/contacts/favorite_food.
  • Para obter todas as propriedades de um objeto, faça uma solicitação GET para /crm/v3/properties/{objectType}.

Atualizar ou limpar o valor de uma propriedade

Para atualizar um valor de propriedade para um registro, faça uma solicitação PATCH para crm/v3/objects/{objectType}/{recordId}. No corpo da solicitação, inclua as propriedades e os respectivos valores em uma matriz. Saiba mais sobre como atualizar registros através das APIs de objeto.

Adicionar valores às propriedades de tipo de caixa de seleção

Ao atualizar valores para propriedades de tipo de caixa de seleção de um registro, formate os valores da seguinte maneira:

  • Propriedade de caixa de seleção Booleano: para ser exibido como Sim ou aparecer como selecionado no HubSpot, seu valor deve ser true. Para ser exibido como Não ou aparecer como não marcado no HubSpot, seu valor deve ser false.
  • Propriedade de várias caixas de seleção: para adicionar ou anexar valores a uma propriedade de várias caixas de seleção, adicione um ponto e vírgula antes do primeiro valor e inclua um ponto e vírgula entre cada valor. Se a propriedade tiver um valor existente, o ponto e vírgula inicial adicionará os valores em vez de sobrescrevê-los. Por exemplo, um contato tem o valor existente DECISION_MAKER para a propriedade hs_buying_role. Para adicionar valores sem substituir o valor existente, sua solicitação seria assim:
///Example body for PATCH request to /crm/v3/objects/contacts/{contactId} { "properties": { "hs_buying_role": ";BUDGET_HOLDER;END_USER" }}

Atribuir proprietários de registos usando propriedades do usuário

Ao atribuir usuários a registros do CRM via API, o valor deve ser o id de proprietário do usuário, que você pode encontrar nas configurações da propriedade ou por meio da API de proprietários. Por exemplo, para atribuir um usuário como proprietário de um contato, envie uma solicitação PATCH para crm/v3/objects/contacts/{contactId}, com o corpo { "properties":{ "hubspot_owner_id": "41629779"}}.

Limpar um valor de propriedade

Você pode apagar o valor da propriedade de um objeto por meio da API configurando o valor da propriedade como uma string vazia.

Por exemplo, para apagar firstname de um objeto de contato, envie uma solicitação PATCH para https://api.hubapi.com/crm/v3/objects/contacts/{contactId} com o corpo { "properties": { "firstname": ""}}.


Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..