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.
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.
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.
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 |
Os valores válidos para fieldType
incluem:
Fieldtype | Description |
---|---|
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 formulário. Armazenado e exibido como link de URL para o 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. |
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 comotrue
.
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).
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
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
e1.5589
são números constantes válidos. - Literal de booleano: booleanos constantes podem ser
true
oufalse
.
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, astring(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 identificadorbool(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.
Operador | Descrição | Examples |
---|---|---|
+
| Add numbers or strings. |
|
-
| 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 |
>
| Checks if a value is greater than another. Supported by number properties or constants. | a > 50 |
<=
| Checks if a value is less than or equal to another. Supported by number properties or constants. | a <= b |
>=
| Checks if a value is greater than or equal to another. Supported by number properties or constants. |
|
=
| 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:
Função | Descrição | Examples |
---|---|---|
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. |
|
is_present
| Evaluates whether an expression can be evaluated. |
|
contém
| Has two strings as inputs and will return true if the first input contains the second. |
|
concatenate
| Joins a list of strings. The list of inputs can go from 2 up to 100. |
|
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|b
representa 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:
Um exemplo mais avançado com condicionais:
Depois de definir as propriedades, você pode atualizar os valores para seus registros por meio das APIs de objeto.Abaixo, saiba como formatar valores para tipos de campo de propriedade específicos e como limpar valores de propriedade.
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 serfalse
. - 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 propriedadehs_buying_role
. Para adicionar valores sem substituir o valor existente, sua solicitação seria assim:
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"}}
.
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": ""}}
.
Agradecemos pelos seus comentários. Eles são muito importantes para nós.