> ## 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. # API do CRM | Propriedades > **[Run in Postman](https://app.getpostman.com/run-collection/33493e154afc38038092)** > **Requisitos de escopo** 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](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties) 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](https://br.developers.hubspot.com/docs/api-reference/crm-custom-objects-v3/guide.md) separado com seu próprio conjunto de propriedades. ## Propriedades padrão Os objetos de CRM são definidos por um `type` primário e um conjunto de `properties`. 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: * [Contatos](https://knowledge.hubspot.com/pt/properties/hubspots-default-contact-properties) * [Empresas](https://knowledge.hubspot.com/pt/properties/hubspot-crm-default-company-properties) * [Negócios](https://knowledge.hubspot.com/pt/properties/hubspots-default-deal-properties) * [Tickets](https://knowledge.hubspot.com/pt/properties/hubspots-default-ticket-properties) * [Atividades](https://knowledge.hubspot.com/pt/properties/hubspots-default-activity-properties) (Chamadas, e-mails, reuniões, notas, tarefas) * [Leads](https://knowledge.hubspot.com/pt/properties/hubspots-default-lead-properties)(***Sales Hub*** *Professional* e *Enterprise*) ## Grupos de propriedades Os [grupos](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties#create-and-edit-property-groups) 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. | `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](#add-values-to-date-and-datetime-properties) (ou seja, meia-noite UTC). | `date` | | `datetime` | Um valor que representa um dia, mês, ano e horário 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](#add-values-to-date-and-datetime-properties). | `date` | | `string` | Uma string de texto simples, com no máximo 65.536 caracteres. | `file`, `text`, `textarea`, `calculation_equation`, `html`, `phonenumber` | | `number` | 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: | Tipo de campo | Descrição | | - | - | | `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](#add-values-to-checkbox-type-properties). | | `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](#create-calculation-properties). | | `checkbox` | 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](#add-values-to-checkbox-type-properties). | | `date` | 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 | | `number` | 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. | | `radio` | 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](https://knowledge.hubspot.com/pt/properties/organize-and-export-properties) 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](#property-type-and-fieldtype-values) de propriedade. * `fieldType`: o [tipo de campo](#property-type-and-fieldtype-values) da propriedade. Por exemplo, para criar uma propriedade de contato chamada *Favorite Food*, a solicitação seria semelhante à seguinte: **JSON** ```json theme={null} { "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 (`hs_object_id`) exclusivo é 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 (`email`) de um contato e o nome de domínio (`domain`) de uma empresa. 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`. **JSON** ```json theme={null} { "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. Por exemplo, para recuperar um negócio com um valor de `abc` para a propriedade `system_a_unique`, sua URL de solicitação seria: `/crm/v3/objects/deals/abc?idProperty=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 `calculation_equation` e um tipo `number`, `bool`, `string` ou `enumeration`. Você pode definir a fórmula de cálculo da propriedade com o campo `calculationFormula`. > [!WARNING] > > ### 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 de constante válidos. * **Literal de booleano**: booleanos de 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, `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. > [!WARNING] > > ### 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 | Exemplos | | - | - | - | | `+` | Some números ou strings. | `property1 + 100` | | `-` | Subtraia números. | `property1 + 100 - property2` | | `*` | Multiplique números. | `10property1` = `10 * property1` | | `/` | Divida números. | `property1 * (100 - property2/(50 - property3))` | | `<` | Verifica se um valor é menor que outro. Compatível com propriedades numéricas ou constantes. | `a < 100` | | `>` | Verifica se um valor é maior que outro. Compatível com propriedades numéricas ou constantes. | `a > 50` | | `<=` | Verifica se um valor é menor ou igual a outro. Compatível com propriedades numéricas ou constantes. | `a <= b` | | `>=` | Verifica se um valor é maior ou igual a outro. Compatível com propriedades numéricas ou constantes. | `b>= c` | | `=` | Verifica se um valor é igual a outro. Compatível com números e strings. | `(a + b - 100c * 150.652) = 150-230b` | | `equals` | Verifica se um valor é igual a outro. Compatível com números e strings. | `a + b - 100.2c * 150 equals 150 - 230` | | `!=` | Verifica se um valor não é igual a outro. Compatível com números e strings. | `string(property1) != 'test_string'` | | `or` | Verifica se dois valores são verdadeiros. | `a > b or b <= c` | | `and` | Verifica se os valores são verdadeiros. | `bool(a) and bool(c)` | | `not` | Verifica se nenhum dos valores é verdadeiro. | `not (bool(a) and bool(c))` | #### Funções As funções a seguir são compatíveis: | Função | Descrição | Exemplos | | - | - | - | | `max` | Terá entre 2 e 100 números de entrada e retornará o número máximo de todas as entradas. | `max(a, b, c, 100)` ou `max(a, b)` | | `min` | Terá entre 2 e 100 números de entrada e retornará o número mínimo de todas as entradas. | `min(a, b, c, 100)` ou `min(a, b)` | | `is_present` | Avalia se uma expressão pode ser avaliada. | `is_present(bool(a))`= true se a propriedade for booleana, mas `is_present(bool(a))` = false se a propriedade estiver vazia ou não for booleana. | | `contains` | Tem duas strings como entradas e retornará true se a primeira entrada contiver a segunda. | `contains('hello', 'ello')` = `true` enquanto `contains('ello', 'hello')` = false. | | `concatenate` | Ingressa em uma lista de strings. A lista de entradas pode ir de 2 a 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. A string válida seria `"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, `a|b` representa que a ou b funcionará e `*` significa 0 ou mais. `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: ```json theme={null} "calculationFormula": "closed - started" ``` Um exemplo mais avançado com condicionais: ```json theme={null} "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 recuperar a propriedade `favorite_food`, seu URL de solicitação seria `/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}`. > [!WARNING] > > ### Observação: > > Ao recuperar todas as propriedades, por padrão, somente propriedades não confidenciais são retornadas. Para recuperar propriedades de dados confidenciais, inclua o parâmetro de consulta `dataSensitivity` com o valor `sensitive`. Saiba mais sobre como [gerenciar dados confidenciais via API](https://br.developers.hubspot.com/docs/reference/api/crm/sensitive-data#manage-sensitive-data) (BETA, somente *Enterprise*). ## 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](https://br.developers.hubspot.com/docs/guides/crm/understanding-the-crm). ### Adicionar valores às propriedades data e hora Os valores de hora são representados no formato ISO 8601 nas respostas, mas as APIs da HubSpot aceitarão um dos dois formatos para valores de data e hora: * **Strings com formatação ISO 8601**: dependendo do tipo de dados, elas terão um destes dois formatos: * Para valores que representam uma data específica, o formato de data completo será usado: YYYY-MM-DD (por exemplo, `2020-02-29`) * Para valores que representam uma data e hora específicas, será usado o formato de data completa mais horas, minutos, segundos e uma fração decimal de segundo: AAAA-MM-DDThh:mm:ss.sTZD (por exemplo `2020-02-29T03:30:17.000Z`). Todos os horários serão representados em UTC, então os valores sempre usarão o designador de UTC "Z." * **Data/hora em formato UNIX em milissegundos**: valores de data/hora em milissegundos, que são representados em UTC. Por exemplo, o valor de data/hora `1427997766000` é traduzido como *2 de abril de 2015, 18:02:46 UTC* ou *2 Abr 2015, 2:02:46 PM EDT* (Horário de Verão do Leste). Existem dois tipos de propriedades para armazenar datas (`date` e `datetime` ) que também afetam como você formata valores: * `date` propriedades armazenam a data, não o tempo. As propriedades `date` exibem a data em que foram definidas, independentemente da configuração de fuso horário da conta ou do usuário. Para valores de propriedade `date`, recomenda-se usar o formato de data completo ISO 8601. Se você usar o formato de data/hora UNIX, deverá usar uma data/hora em milissegundos de Era (ou seja, o valor deve ser definido como meia-noite UTC para a data). Por exemplo, para representar 1° de maio de 2015 em qualquer formato: * **IOS 8601**: 2015-05-01 * **UNIX millisecond timestamp**: 1430438400000 * `datetime` As propriedades `datetime` armazenam a data e a hora. Qualquer formato de data/hora será aceito. No HubSpot, as propriedades `datetime` são exibidas com base no fuso horário do usuário que vê o registro; portanto, o valor será convertido para o fuso horário local do usuário. ### 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: **JSON** ```json theme={null} { "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](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties) ou por meio da [API de proprietários](https://br.developers.hubspot.com/docs/api-reference/crm-crm-owners-v3/guide.md). 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 limpar o `firstname` de um objeto de contato, envie uma solicitação `PATCH` para `/crm/v3/objects/contacts/{contactId}`, com o corpo `{ "properties": { "firstname": ""}}`.