Propiedades

Usa propiedades para almacenar información en registros de CRM. HubSpot proporciona un conjunto de propiedades predeterminadas para cada objeto CRM y también puedes crear y administrar sus propias propiedades personalizadas en HubSpot o mediante la API de propiedades. 

Al crear propiedades, es importante tener en cuenta cómo diseñar tus datos. En muchos casos, la creación de propiedades personalizadas para los objetos estándar de HubSpot es el curso de acción correcto. Sin embargo, puede haber ocasiones en las que debas crear un objeto personalizado independiente con su propio conjunto de propiedades.

Propiedades predeterminadas

Los objetos de CRM se definen por un tipo principal y un conjunto de propiedades. Cada tipo tiene un conjunto único de propiedades estándar, representado por un mapa de pares nombre-valor. 

Más información sobre las propiedades predeterminadas para diferentes objetos:

Grupos de propiedades

Los grupos de propiedades se utilizan para agrupar propiedades relacionadas. Cualquier propiedad agrupada aparecerá junto entre sí en los registros de HubSpot. Si tu integración crea cualquier propiedad personalizada de objeto, un grupo de propiedades personalizadas hará que sea fácil identificar esos datos.

Tipo de propiedad y valores de fieldType

Cuando se crean o actualizan propiedades, se requieren valores de type y fieldType. El valor type determina el tipo de propiedad, es decir, una cadena o un número. La propiedad fieldType determina cómo aparecerá la propiedad en HubSpot o en un formulario, es decir, como un campo de texto sin formato, un menú desplegable o un selector de fechas.

En la siguiente tabla, obtén información sobre propiedad disponible type y los valores de fieldType correspondientes.

Valores válidos para el campo type y valores fieldType compatibles
type Descripción Valores fieldType válidos
bool Un campo que contiene opciones binarias (por ejemplo,  o No, Verdadero o Falso). booleancheckbox,  calculation_equation
enumeration Una cadena que representa un conjunto de opciones, con opciones separadas por un punto y coma booleancheckbox, checkbox, radio, select, calculation_equation
date Un valor con formato ISO 8601 que representa un día, mes y año específicos. Los valores deben representarse en tiempo UTC y pueden formatearse como cadenas ISO 8601 o marcas de tiempo EPOCH en milisegundos (es decir, UTC de medianoche). date
dateTime Un valor con que representa un día, mes y hora específicos del día. La aplicación HubSpot no mostrará la hora del día. Los valores deben representarse en tiempo UTC y pueden formatearse como cadenas ISO 8601 o marcas de tiempo UNIX en milisegundos. date
string Una cadena de texto sin formato, limitada a 65.536 caracteres. file, text, textarea, calculation_equation, html, phonenumber
number Un valor de número que contiene dígitos numéricos y, como máximo, un decimal. number, calculation_equation
object_coordinates Un valor de texto utilizado para hacer referencia a otros objetos de HubSpot, utilizado solo para propiedades internas. Las propiedades de este tipo no se pueden crear ni editar, y no son visibles en HubSpot. text
json Un valor de texto almacenado como JSON formateado, utilizado solo para propiedades internas. Las propiedades de este tipo no se pueden crear ni editar, y no son visibles en HubSpot. text

Los valores válidos para fieldType incluyen:

FieldtypeDescription
booleancheckbox

Una entrada que permitirá a los usuarios seleccionar Sí o No. Cuando se usa en un formulario, se mostrará como una única casilla de comprobación. Descubre cómo agregar un valor a las propiedades de casilla de comprobación única.

calculation_equation

Una ecuación personalizada que puede calcular valores basados en otros valores de propiedad y/o asociaciones. Más información sobre cómo definir propiedades de cálculo.

casilla de comprobación

Una lista de casillas de comprobación que permitirán al usuario seleccionar varias opciones de un conjunto de opciones permitidas para la propiedad. Aprende a dar formato a los valores al actualizar varias propiedades de casilla de comprobación.

date

Un valor de fecha, que se muestra como selector de fechas.

file

Permite subir un archivo en un registro o a través de un formulario. Almacena un ID de archivo.

html

Una cadena, renderizada como html desinfectado, que permite el uso de un editor de texto enriquecido para la propiedad.

number

Una cadena de numerales o números escritos en notación decimal o científica.

phonenumber

Una cadena de texto sin formato, que se muestra como un número de teléfono formateado.

radio

Una entrada que permitirá a los usuarios seleccionar una de un conjunto de opciones permitidas para la propiedad. Cuando se usa en un formulario, se mostrará como un conjunto de botones de radio.

select

Una entrada desplegable que permitirá a los usuarios seleccionar una de un conjunto de opciones permitidas para la propiedad.

text

Una cadena de texto sin formato, que se muestra en una entrada de texto de una sola línea.

textarea

Una cadena de texto sin formato, que se muestra como entrada de texto de varias líneas.

Crear una propiedad

Para crear una propiedad, haz una solicitud POST a /crm/v3/properties/{objectType}. En el cuerpo de tu solicitud, incluye los siguientes campos obligatorios:

  • groupName: el grupo de propiedades en el que estará la propiedad.
  • name: el nombre interno de la propiedad (p. ej., favorite_food).
  • label: el nombre de la propiedad tal como aparece en HubSpot (por ejemplo, Comida favorita).
  • type: el tipo de propiedad.
  • fieldType: el tipo de campo de la propiedad.

Por ejemplo, para crear una propiedad de contacto llamada Comida favorita, tu solicitud se vería así:

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

Crear propiedades de identificador único

Cuando se crea un registro en HubSpot, se genera automáticamente un ID de registro (hs_object_id) único que debe ser tratado como una cadena de texto. Estos ID solo son únicos dentro de ese objeto, por lo que puede haber un contacto y una empresa con el mismo ID. Para los contactos y las empresas, hay identificadores únicos adicionales, incluida la dirección de correo electrónico de un contacto (email) y el nombre de dominio de una empresa (domain).

En algunos casos, es posible que quieras crear tu propia propiedad de identificador único para que no puedas introducir el mismo valor para varios registros. Puedes tener hasta diez propiedades de ID únicas por objeto. Para crear una propiedad que requiera valores únicos a través de la API:

  • Haz una solicitud POST a /crm/v3/properties/{objectType}.
  • En el cuerpo de la solicitud, para el campo hasUniqueValue, establece el valor como true.
/// Example request body { "groupName": "dealinformation", "name":"system_a_unique", "label": "Unique ID for System A", "hasUniqueValue": true, "type": "string", "fieldType": "text" }

Una vez que hayas creado tu propiedad de ID único, puedes usarlo en una llamada a la API para recuperar registros específicos. La URL de la solicitud podría verse de la siguiente manera: GET https://api.hubapi.com/crm/v3/objects/deals/abc?idProperty=system_a_unique. Esto devolverá el negocio con el valor de abc en el campo system_a_unique.

Luego puedes usar este valor de propiedad de identificador único para identificar y actualizar registros específicos de la misma manera que podrías usar hs_object_id, email (contactos) o domain (empresas).

Crear propiedades de cálculo

Las propiedades de cálculo definen un valor de propiedad basado en otras propiedades dentro del mismo registro de objeto. Se definen utilizando una fórmula, que puede incluir operaciones como min, max, count, sum o average. Puedes usar la API de propiedades para leer o crear propiedades de cálculo en tu cuenta de HubSpot, usando un tipo de campo calculation_equation y un tipo de number, bool, string o enumeration.

Puedes definir la fórmula de cálculo de la propiedad con el campo calculationFormula.

Nota: las propiedades de cálculo creadas mediante API no se pueden editar en HubSpot. Solo puedes editar estas propiedades a través de la API de propiedades.

Sintaxis de propiedad de cálculo

Usando calculationFormula, puedes escribir tu fórmula con operadores aritméticos, operadores de comparación, operadores lógicos, sentencias condicionales y otras funciones.

Sintaxis literal

  • Cadena literal: las cadenas constantes se pueden representar con comillas simples ('constant') o comillas dobles ("constant").
  • Número literal: los números constantes pueden ser cualquier número real y pueden incluir notación de puntos. 1005 y 1.5589 son números constantes válidos.
  • Literal booleano: los booleanos constantes pueden ser true o false.

Sintaxis de propiedad

  • Variables de propiedad de cadena: para que una cadena de identificador se interprete como una propiedad de cadena, debe estar envuelta en la función string. Por ejemplo, string(var1) se interpretará como el valor de la propiedad string var1.
  • Variables de propiedad de número: todos los identificadores se interpretarán como variables de propiedad de número.  Por ejemplo, var1 se interpretará como el valor de la propiedad de número var1.
  • Variables de propiedad booleana: para que un identificador se interprete como una propiedad bool, debe estar envuelto en la función bool. Por ejemplo, el identificador bool(var1) se interpretará como el valor de la propiedad booleana var1.

Nota: el lenguaje utilizado distingue entre mayúsculas y minúsculas para todos los tipos, excepto las cadenas. Por ejemplo, si A ThEn B es exactamente igual que si a, entonces b pero 'a' no es igual que 'A'. Se utilizarán espacios, pestañas y nuevas líneas para la tokenización, pero se ignorarán.

Operadores

Los operadores se pueden usar con valores literales y de propiedad. Para los operadores aritméticos, puedes usar notación de prefijo para multiplicar, y se pueden usar paréntesis para especificar el orden de las operaciones.

OperadorDescripciónExamples
+
Add numbers or strings.

property1 + 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
Equivale 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'
or
Checks if either or two values are true. a > b or b <= c
and
Checks if both values are true.bool(a) and bool(c)
not
Checks if none of the values are true.not (bool(a) and bool(c))

Funciones

Las siguientes son funciones compatibles:

Use this table to describe parameters / fields
FunciónDescripciónExamples
max
Will have between 2 and 100 input numbers, and will return the maximum number out of all the inputs.max(a, b, c, 100) o max(a, b)
min
Will have between 2 and 100 input numbers, and will return the minimum number of out all the inputs.

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

is_present
Evaluates whether an expression can be evaluated.

is_present(bool(a))= true si la propiedad es booleana, pero is_present(bool(a)) = false si la propiedad está vacía o no es booleana.

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

contains('hello', 'ello') = true mientras que 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))

También hay dos funciones de análisis:

  • number_to_string: intenta convertir la expresión del número de entrada en una cadena.
  • string_to_number: intenta convertir la expresión de la cadena de entrada en un número.

Por ejemplo, "Number of cars: " + num_cars es una propiedad válida porque no puedes agregar una cadena con un número, pero "Number of cars: " + number_to_string(num_cars) sí lo es.

Declaraciones condicionales

También puedes escribir tu fórmula con sentencias condicionales usando if, elseif, endif y else.

Por ejemplo, una sentencia condicional podría parecerse a: if boolean_expression then statement [elseif expression then statement]* [else statement | endif] donde los corchetes [a] representan que a es opcional, a|b representa que a o b funcionarán, y * significa 0 o más. endif se puede usar para terminar una sentencia condicional prematuramente, asegurando que el analizador sintáctico pueda identificar a qué if pertenece el siguiente elseif

Fórmulas de ejemplo

Los siguientes son ejemplos que puedes usar para ayudar a definir tus propias fórmulas de cálculo:

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

Un ejemplo más avanzado con condicionales:

//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 propiedades

Puedes recuperar información de propiedades individuales o de todas las propiedades dentro de un objeto.

  • Para recuperar una propiedad individual, haz una solicitud GET en /crm/v3/objects/companies/{companyId}. Por ejemplo, para recuperar la propiedad Comida favorita, la URL de tu solicitud sería https://
    api.hubspot.com/crm/v3/properties/contacts/favorite_food.
  • Para recuperar todas las propiedades de un objeto, haz una solicitud GET a/crm/v3/properties/{objectType}.

Actualizar o borrar los valores de una propiedad

Para actualizar el valor de una propiedad para un registro, realiza una solicitud PATCH a crm/v3/objects/{objectType}/{recordId}. En el cuerpo de tu solicitud, incluye las propiedades y sus valores en una matriz. Más información sobre la actualización de registros a través de las API de objetos.

Agregar valores a propiedades de tipo de casilla de comprobación

Al actualizar los valores para las propiedades de tipo de casilla de comprobación de un registro, formatea los valores de las siguientes maneras:

  • Propiedad de casilla de verificación booleana: para que se muestre como , o marcado en HubSpot, el valor debe ser verdadero. Para que aparezca como No o sin marcar en HubSpot, tu valor debe ser falso.
  • Propiedad de casillas de verificación de selección múltiple: para agregar o adjuntar valores a una propiedad de varias casillas de comprobación, agrega un punto y coma antes del primer valor e incluye un punto y coma entre cada valor. Si la propiedad tiene un valor existente, el punto y coma inicial agregará los valores en lugar de sobrescribir el valor. Por ejemplo, un contacto tiene el valor DECISION_MAKER existente para la propiedad hs_buying_role. Para agregar valores adicionales sin reemplazar el valor existente, tu solicitud se vería como lo siguiente:
///Example body for PATCH request to /crm/v3/objects/contacts/{contactId} { "properties": { "hs_buying_role": ";BUDGET_HOLDER;END_USER" }}

Asignar propietarios de registros con propiedades de usuario

Al asignar usuarios a registros de CRM a través de la API, tu valor debe ser el ID de propietario del usuario, que puedes encontrar en la configuración de tu propiedad o a través de la API de propietarios. Por ejemplo, para asignar un usuario como propietario de un contacto, envía una solicitud PATCH a crm/v3/objects/contacts/{contactId},  con el cuerpo { "properties":{ "hubspot_owner_id": "41629779"}}.

Borrar un valor de propiedad

Puedes borrar un valor de propiedad de objeto a través de la API configurando el valor de propiedad en una cadena vacía.

Por ejemplo, para borrar el firstname de un objeto de contacto, envía una solicitud PATCH a https://api.hubapi.com/crm/v3/objects/contacts/{contactId} con el cuerpo { "properties": { "firstname": ""} }.


¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.