Objetos personalizados

ResumenObjetosEsquema de objeto
APPLICABLE PRODUCTS
  • Marketing Hub
    • Enterprise
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise
  • Content Hub
    • Enterprise
  • Operations Hub
    • Enterprise

En cada cuenta de HubSpot, están los objetos estándar de CRM: contactos, empresas, negocios y tickets. Para representar y organizar los datos de tu CRM en función de las necesidades de tu negocio, también puedes crear objetos personalizados. Puedes crear un objeto personalizado en HubSpot o usar la API de objetos personalizados para definir objetos personalizados, propiedades y asociaciones a otros objetos de CRM. 

A continuación, aprende a crear y administrar objetos personalizados a través de la API, y ve un tutorial de cómo crear un objeto personalizado de ejemplo.

Para obtener más información sobre la creación de objetos personalizados, consulta las siguientes publicaciones en el blog para desarrolladores de HubSpot:

Nota: los objetos personalizados son específicos de cada cuenta y, dependiendo de tu suscripción, hay límites en el número de objetos personalizados que puedes crear. En el Catálogo de productos y servicios de HubSpot encontrarás más información sobre tus límites.

Métodos de autentificación

Puedes crear, leer y actualizar objetos personalizados utilizando uno de los siguientes métodos de autenticación:

Nota: desde el 30 de noviembre de 2022, las claves de API de HubSpot están obsoletas y ya no son compatibles. El uso continuado de las claves de API de HubSpot es un riesgo de seguridad para tu cuenta y tus datos. Durante esta fase de obsolescencia, HubSpot puede desactivar tu clave en cualquier momento.

En su lugar, debes autentificarte usando un token de acceso de una aplicación privada u OAuth. Más información sobre este cambio y cómo migrar una integración de claves de API para usar una aplicación privada en su lugar.

Crear un objeto personalizado

Para crear un objeto personalizado, primero deberás definir el esquema del objeto. El esquema incluye el nombre del objeto, las propiedades y las asociaciones con otros objetos de CRM. Puedes encontrar los detalles completos de la solicitud de esquema en la pestaña Esquema de objeto en la parte superior de este artículo. También puedes ver una solicitud de ejemplo en el tutorial de ejemplo a continuación.

Para crear el esquema de objeto personalizado, haz una solicitud POST a crm/v3/schemas. En el cuerpo de la solicitud, incluye definiciones para el esquema de objetos, incluidos su nombre, propiedades y asociaciones.

Al asignarle un nombre a tu objeto personalizado, ten en cuenta lo siguiente:

  • Una vez que creas un objeto, su nombre y etiqueta no se pueden cambiar.
  • El nombre solo puede contener letras, números y guiones bajos.
  • El primer carácter del nombre debe ser una letra.
  • Las etiquetas largas pueden estar cortadas en ciertas partes del producto.

A continuación, lee acerca de las definiciones requeridas para las propiedades y asociaciones del objeto. 

Propiedades

Las propiedades que definas en el cuerpo de la solicitud se utilizarán para almacenar información en registros de objetos personalizados individuales.

Nota: puedes tener hasta 10 propiedades de valor únicas para cada objeto personalizado en tu cuenta de HubSpot.

Usarás tus propiedades definidas para completar los siguientes campos basados en propiedades:

  • requiredProperties: las propiedades que se requieren al crear un nuevo registro de objeto personalizado.
  • searchableProperties: las propiedades que se indexan para buscar en HubSpot.
  • primaryDisplayProperty: la propiedad utilizada para asignar nombre a registros de objetos personalizados individuales.
  • secondaryDisplayProperties: las propiedades que aparecen en los registros individuales bajo primaryDisplayProperty.
    custom-object-secondary-display-properties0
    • La primera propiedad que se indica en secondaryDisplayProperties también se agregará como un cuarto filtro en la página de índice de objetos si es uno de los siguientes tipos de propiedad:
      • string
      • number
      • enumeration
      • boolean
      • datetime
        custom-object-dashboard-filter0
    • Para eliminar una propiedad de visualización de la interfaz de usuario, primero deberás eliminar la propiedad y luego volver a crearla.

Por opción predeterminada, cuando se crean propiedades a través de la solicitud de esquema, el tipo de propiedad se establece en cadena y el fieldType se establece en texto. A continuación se muestran los valores que puedes usar para crear diferentes tipos de propiedades.

Valores válidos para el type
type Descripción Valores fieldType válidos
enumeration Una cadena que representa un conjunto de opciones separadas por un punto y coma  booleancheckbox, checkbox, radio, select
date Un Valor con formato ISO 8601 que representa un día, mes y año específicos. date
dateTime Un Valor con formato ISO 8601 que representa un día, mes y hora específicos del día. La aplicación HubSpot no mostrará la hora del día. date
string Una cadena de texto sin formato, limitada a 65.536 caracteres. file, text, textarea
number Un valor de número que contiene dígitos numéricos y, como máximo, un decimal. number
Valores válidos para fieldType 
fieldType Descripción
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.
checkbox Una lista de casillas de comprobación que permitirán al usuario seleccionar varias opciones de un conjunto de opciones permitidas para la propiedad.
date Un valor de fecha, que se muestra como selector de fechas.
file Permite que un archivo se cargue en un formulario. Almacenar y mostrar como un enlace de URL al archivo.
number Una cadena de numerales o números escritos en notación decimal o científica.
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.

Asociaciones

HubSpot asociará automáticamente un objeto personalizado con los correos electrónicos, reuniones, notas, tareas, llamadas y objetos de conversaciones. Además, puedes asociar tu objeto personalizado con otros objetos de HubSpot estándar u otros objetos personalizados.

Al crear asociaciones a través de la solicitud de creación de esquema, identifica objetos estándar usando su nombre y objetos personalizados usando su valor objectTypeId. Por ejemplo:

// Example associatedObjects array "associatedObjects": [ "CONTACT", "COMPANY", "TICKET", "DEAL", "2-3453932" ]

Recuperar objetos personalizados existentes

Para recuperar todos los objetos personalizados, haz una solicitud GET a/crm/v3/schemas.

Para recuperar un objeto personalizado específico, realiza una solicitud GET a uno de los siguientes puntos de terminación:

  • /crm/v3/schemas/{objectTypeId}
  • /crm/v3/schemas/p_{object_name}
  • /crm/v3/schemas/{fullyQualifiedName}. Puedes encontrar un objeto

    fullyQualifiedName en su esquema, que se deriva de p{portal_id}_{object_name}. Puedes encontrar el ID del portal de tu cuenta utilizando la API de información de la cuenta.

Por ejemplo, para una cuenta con un ID de 1234 y un objeto llamado lender, la URL de solicitud podría parecerse a cualquiera de los siguientes elementos:

Recuperar registros de objetos personalizados

También puedes recuperar los registros de un objeto personalizado.

  • Para recuperar un registro específico por su valor de ID de registro, haz una solicitud GET a crm/v3/objects/{objectType}/{recordId}.

En este punto de terminación, puedes incluir los siguientes parámetros de consulta en la URL de la solicitud: 

Use this table to describe parameters / fields
ParameterDescription
propiedades

Una lista separada por comas de las propiedades que se devolverán en la respuesta. Si el registro de objeto personalizado solicitado no tiene un valor para una propiedad, no aparecerá en la respuesta.

propertiesWithHistory

Una lista separada por comas de las propiedades actuales e históricas que se devolverán en la respuesta. Si el registro de objeto personalizado solicitado no tiene un valor para una propiedad, no aparecerá en la respuesta.

asociaciones

Una lista separada por comas de los objetos de los cuales recuperar los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. Más información sobre la API de asociaciones.
  • Para recuperar varios registros, haz una solicitud POST a crm/v3/objects/{objectType}/batch/read. El punto de terminación por lote no puede recuperar asociaciones. Obtener más información sobre cómo leer asociaciones por lotes con la API de asociaciones.

En tu solicitud, puedes recuperar registros por su ID de registro (hs_object_id) o por una propiedad de identificador único personalizada. Por opción predeterminada, los valores de id en la solicitud se refieren al ID de registro, por lo que no se requiere el parámetro idProperty al recuperar por ID de registro. Para usar una propiedad de valor único personalizada, debes incluir el parámetro idProperty.

Por ejemplo, para recuperar un lote de registros de objetos personalizados, tu solicitud podría tener uno de los siguientes aspectos:

///Example request body for record ID { "properties": [ "petname" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }
///Example request body for unique value property { "properties": [ "petname" ], "idProperty": "uniquepropertyexample", "inputs": [ { "id": "abc" }, { "id": "def" } ] }
Para recuperar registros de objetos personalizados con valores actuales e históricos para una propiedad, tu solicitud podría verse así:
///Example request body for record ID (current and historical values) { "propertiesWithHistory": [ "pet_owner" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

Actualizar objetos personalizados existentes

Para actualizar el esquema de un objeto, realiza una solicitud PATCH en https://api.hubapi.com/crm/v3/schemas/{objectTypeId}.

Una vez que tu objeto personalizado esté definido:

  • El nombre y las etiquetas del objeto (singular y plural) no se pueden cambiar.
  • Las propiedades requiredProperties, searchableProperties, primaryDisplayProperty y secondaryDisplayProperties se pueden cambiar actualizando el esquema del objeto. Para establecer una nueva propiedad como requerida, de búsqueda o de visualización, debes crear la propiedad antes de actualizar el esquema.
  • Puedes crear y editar propiedades de objetos personalizados en HubSpot o a través de la API de propiedades. 

Actualizar asociaciones

Para agregar otras asociaciones de objetos a tu objeto personalizado, haz una solicitud POST a/crm/v3/schemas/{objectTypeId}/associations.

Solo puedes asociar tu objeto personalizado con objetos de HubSpot estándar (por ejemplo, contacto, empresa, negocio o ticket) u otros objetos personalizados. En el campo toObjectTypeId, identifica los objetos personalizados por su valor objectTypeId y los objetos estándar por su nombre. Por ejemplo, puedes hacer lo siguiente:

// Example association request body { "fromObjectTypeId": "2-3444025", "toObjectTypeId": "ticket", "name": "cat_to_ticket" }

Eliminar un objeto personalizado

Solo puedes eliminar un objeto personalizado después de eliminar todas las instancias de objetos de ese tipo. Para eliminar un objeto personalizado, haz una solicitud DELETE en/crm/v3/schemas/{objectType}.

Si necesitas crear un nuevo objeto personalizado con el mismo nombre que el objeto eliminado, debes eliminar el esquema haciendo una solicitud DELETE a /crm/v3/schemas/{objectType}?archived=true. Solo puedes eliminar un tipo de objeto personalizado después de eliminar todas las instancias de objeto de ese tipo, asociaciones y propiedades de objeto personalizadas.

Ejemplo de objeto personalizado

Lo siguiente es un tutorial para crear un objeto personalizado de ejemplo. Para obtener detalles completos de las solicitudes que se muestran, consulta la pestaña Definición de objeto en la parte superior del artículo.

Este tutorial cubre:

  1. La creación de un esquema de objeto personalizado.
  2. La creación de un registro de objeto personalizado.
  3. La asociación de un registro de objeto personalizado con un contacto de HubSpot.
  4. La creación de una nueva definición de asociación entre el objeto personalizado y el ticket de HubSpot.
  5. La creación de una nueva definición de propiedad.
  6. La actualización del esquema de objetos (es decir, secondaryDisplayProperties) con la nueva propiedad.

Objetivo: un concesionario de automóviles llamado CarSpot quiere almacenar su inventario en HubSpot usando un objeto personalizado. Para hacer seguimiento de la propiedad del vehículo y las compras, asociarán los autos con registros de contactos. A lo largo del camino, también harán seguimiento del mantenimiento del vehículo utilizando tickets de HubSpot y propiedades personalizadas.

Creación del esquema de objeto

CarSpot necesita crear un esquema de objeto que pueda representar los siguientes atributos como propiedades: 

  1. Condición (nueva o usada): enumeración
  2. Fecha de recepción en el concesionario: fecha
  3. Fecha: número
  4. Marca: cadena
  5. Modelo: cadena
  6. VIN: cadena (valor único)
  7. Color: cadena
  8. Kilometraje: número
  9. Precio: número
  10. Notas: cadena

También agregarán una descripción para proporcionar contexto sobre cómo utilizar el objeto y definirán una asociación entre su objeto personalizado y el objeto de contactos estándar para que puedan conectar autos a compradores potenciales. 

Con su modelo de datos finalizado, crearán el esquema de objeto haciendo una solicitud POST a /crm/v3/schemas con el siguiente cuerpo de solicitud:all

// Example POST request to https://api.hubspot.com/crm/v3/schemas { "name": "cars", "description": "Cars keeps track of cars currently or previously held in our inventory.", "labels": { "singular": "Car", "plural": "Cars" }, "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "make" ], "searchableProperties": [ "year", "make", "vin", "model" ], "requiredProperties": [ "year", "make", "vin", "model" ], "properties": [ { "name": "condition", "label": "Condition", "type": "enumeration", "fieldType": "select", "options": [ { "label": "New", "value": "new" }, { "label": "Used", "value": "used" } ] }, { "name": "date_received", "label": "Date received", "type": "date", "fieldType": "date" }, { "name": "year", "label": "Year", "type": "number", "fieldType": "number" }, { "name": "make", "label": "Make", "type": "string", "fieldType": "text" }, { "name": "model", "label": "Model", "type": "string", "fieldType": "text" }, { "name": "vin", "label": "VIN", "type": "string", "hasUniqueValue": true, "fieldType": "text" }, { "name": "color", "label": "Color", "type": "string", "fieldType": "text" }, { "name": "mileage", "label": "Mileage", "type": "number", "fieldType": "number" }, { "name": "price", "label": "Price", "type": "number", "fieldType": "number" }, { "name": "notes", "label": "Notes", "type": "string", "fieldType": "text" } ], "associatedObjects": [ "CONTACT" ] }

Después de crear el esquema del objeto, CarSpot se asegura de anotar el campo {objectTypeId} del nuevo objeto, ya que lo usará para obtener y actualizar el objeto más adelante. También pueden usar el valor {fullyQualifiedName}, si lo prefieren.

Creación de un registro de objeto personalizado

Con el objeto personalizado creado, CarSpot ahora puede crear registros en el objeto para cada auto en su inventario.

Crearán su primer auto haciendo una solicitud POST a/crm/v3/objects/2-3465404 con el siguiente cuerpo de solicitud:

// Example POST request to https://api.hubspot.com/crm/v3/objects/2-3465404 { "properties": { "condition": "used", "date_received": "1582416000000", "year": "2014", "make": "Nissan", "model": "Frontier", "vin": "4Y1SL65848Z411439", "color": "White", "mileage": "80000", "price": "12000", "notes": "Excellent condition. No accidents." } }

La respuesta para esta llamada de API se vería similar a:Copy all

// Example response body { "id": "181308", "properties": { "color": "White", "condition": "used", "make": "Nissan", "mileage": "80000", "model": "Frontier", "vin": "4Y1SL65848Z411439", "notes": "Excellent condition. No accidents.", "price": "12000", "year": "2014", "date_received": "1582416000000" }, "createdAt": "2020-02-23T01:44:11.035Z", "updatedAt": "2020-02-23T01:44:11.035Z", "archived": false }

Con el registro creado, pueden utilizar el valor de identificación para asociar más tarde el auto con un contacto existente.

Si luego quisieran recuperar este registro junto con propiedades específicas, podrían hacer una solicitud GET a https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model

Asociación del registro de objeto personalizado a otro registro

Puedes usar el ID del nuevo registro de automóvil (181308) y el ID de otro registro para asociar un registro de objeto personalizado con un registro de otro objeto.

Para crear una asociación, haz una solicitud PUT a /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}. Si la relación de objeto ya está definida, para determinar el valor associationType, haz una solicitud GET a crm/v3/schemas/{objectType}.

Por ejemplo, con el ID de contacto 51 y el tipo de asociación 75, CarSpot puede asociar el registro del automóvil con un contacto. Usando los ID anteriores, la URL de solicitud se construirá de la siguiente manera:

https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75

Definición de una nueva asociación

CarSpot ahora quiere comenzar a hacer seguimiento de los servicios postventa para sus automóviles. Para ello, usaremos tickets de HubSpot para registrar cualquier mantenimiento realizado.

Para permitir asociaciones entre automóviles y tickets, crearán una nueva asociación haciendo una solicitud POST a /crm/v3/schemas/2-3465404/associations con el siguiente cuerpo de solicitud:

// Example POST request to https://api.hubspot.com/crm/v3/schemas/2-3465494/associations { "fromObjectTypeId": "2-3465404", "toObjectTypeId": "ticket", "name": "car_to_ticket" }

La respuesta para esta llamada de API se vería similar a:Copy all

// Example response { "id": "121", "createdAt": "2020-02-23T01:52:12.893826Z", "updatedAt": "2020-02-23T01:52:12.893826Z", "fromObjectTypeId": "2-3465404", "toObjectTypeId": "0-5", "name": "car_to_ticket" }

Al crear una nueva asociación entre dos objetos personalizados, especifica los objetos personalizados por su objectTypeId en el campo toObjectTypeId. En el caso de los objetos estándar, puedes identificarlos por su nombre o utilizar los siguientes valores: 

  • Contacto: 0-1
  • Empresa: 0-2
  • Negocio: 0-3
  • Ticket: 0-5

Definición de una nueva propiedad

A medida que continúan rastreando el mantenimiento, CarSpot ve una oportunidad para agrupar los servicios de mantenimiento en paquetes. Para hacer seguimiento de estos paquetes de mantenimiento en los registros individuales del vehículo, crearán una nueva propiedad de enumeración que contiene los paquetes disponibles.

Para definir una nueva propiedad, realizarán una solicitud POST a /crm/v3/properties/2-3465404 con el siguiente cuerpo de solicitud:

// Example POST request to https://api.hubspot.com/crm/v3/properties/2-3465404 { "groupName": "car_information", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "options": [ { "label": "Basic", "value": "basic" }, { "label": "Oil change only", "value": "oil_change_only" }, { "label": "Scheduled", "value": "scheduled" } ] }

La respuesta para esta llamada de API se vería similar a:Copy all

// Example response { "updatedAt": "2020-02-23T02:08:20.055Z", "createdAt": "2020-02-23T02:08:20.055Z", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "groupName": "car_information", "options": [ { "label": "Basic", "value": "basic", "displayOrder": -1, "hidden": false }, { "label": "Oil change only", "value": "oil_change_only", "displayOrder": -1, "hidden": false }, { "label": "Scheduled", "value": "scheduled", "displayOrder": -1, "hidden": false } ], "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }

Ahora que se creó la propiedad, quieren que aparezca en la barra lateral de cada registro de automóvil para que la información esté fácilmente disponible para sus representantes de ventas y técnicos. Para ello, agregarán la propiedad a secondaryDisplayProperties haciendo una solicitud PATCH a /crm/v3/schemas/2-3465404 con el siguiente cuerpo de solicitud: 

// Example PATCH request to https://api.hubspot.com/crm/v3/schemas/2-3465404 { "secondaryDisplayProperties": [ "maintenance_package" ] }

La respuesta para esta llamada de API se vería similar a:Copy all

// Example response { "id": "3465404", "createdAt": "2020-02-23T01:24:54.537Z", "updatedAt": "2020-02-23T02:12:24.175874Z", "labels": { "singular": "Car", "plural": "Cars" }, "requiredProperties": [ "year", "model", "vin", "make" ], "searchableProperties": [ "year", "model", "vin", "make" ], "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "maintenance_package" ], "portalId": 1234567, "name": "car" }

Ahora, cuando un técnico abre un registro de contacto que tiene un automóvil asociado, la propiedad se mostrará en la tarjeta de objeto personalizada en la barra lateral:

Screen Shot 2020-03-06 at 11.08.41 AM

A medida que CarSpot continúe usando HubSpot, es probable que encuentren formas de refinar y expandir este objeto personalizado y más usando la API de HubSpot. Incluso podrían decidir crear páginas dinámicas usando sus datos de objetos personalizados.

¿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.