Entender las API del CRM

Tu cuenta de HubSpot se fundamenta en un sistema que centraliza tus relaciones y procesos comerciales, conocido como CRM (Customer Relationship Management o gestión de las relaciones con los clientes). Para gestionar estos datos, las cuentas de HubSpot incluyen objetos que representan los tipos de relaciones o procesos. Las instancias individuales de los objetos, llamadas registros, representan cada una de las entidades de cada tipo de objeto (por ejemplo, Juan Pérez es un contacto). Para almacenar los datos en cada registro se utilizan las propiedades (por ejemplo, la propiedad de dirección de correo electrónico), y para representar las relaciones entre entidades individuales se asocian los registros entre sí (por ejemplo, asociar a Juan Pérez con la empresa Pérez y asociados.) Además, los registros del CRM también pueden almacenar información sobre las interacciones a través de las actividades asociadas, como correos electrónicos, llamadas y reuniones. A continuación, obtendrás más información sobre los objetos, registros, propiedades, asociaciones, pipelines y búsquedas en el CRM. Para obtener más información sobre cómo gestionar la base de datos del CRM desde HubSpot, consulta la base de conocimientos de HubSpot.

API de objetos

Las API de objetos permiten el acceso a los registros y las actividades. En el caso de los objetos compatibles, puedes utilizar los endpoints de objetos y sustituir el parámetro {objectTypeId} en la URL de la solicitud por el objeto deseado. Por ejemplo, para crear contactos, deberías hacer una solicitud POST a crm/v3/objects/0-1 y para crear cursos, la solicitud se haría a crm/v3/objects/0-410. Consulta este artículo para obtener más información sobre el uso de los endpoints de objetos.

Nota:

Algunos objetos tienen funciones limitadas de API. Para más detalles, haz clic en el enlace a la documentación de referencia de los endpoints de cada objeto en la tabla que se encuentra más adelante. Si un objeto de la lista no tiene su documento, puedes consultar el documento de la API de objetos y sustituir el parámetro {objectTypeId} de cada endpoint por el objeto que necesitas.

ID de tipos de objeto

Cuando utilices el CRM y otras API, tendrás que utilizar el campo objectTypeId, que es un valor numérico único asignado a cada objeto. Por ejemplo, para obtener registros, deberías hacer una solicitud GET a /crm/v3/objects/{objectTypeId}, o al crear una propiedad para un objeto, deberías hacer una solicitud POST a /crm/v3/properties/{objectTypeId}. Los valores del ID del tipo de objeto se enumeran en la siguiente tabla:

ID del tipo de objeto	Objeto	Descripción
`0-2`	Empresas	Los registros de empresas almacenan información sobre una empresa u organización. Consulta la API de empresas
`0-1`	Contactos	Almacenan información sobre cada persona. Consulta la API de contactos
`0-3`	Negocios	Representan las oportunidades de ventas y las transacciones que se monitorean a través de las etapas del pipeline. Consulta la API de negocios
`0-5`	Tickets	Representan las solicitudes de asistencia de los clientes y se registran a través de los estados en el pipeline. Consulta la API de tickets
`0-421`	Citas	Representan las interacciones o servicios programados para una persona. Consulta la API de objetos
`0-48`	Llamadas	Tipo de actividad que representa las interacciones de llamadas telefónicas asociadas a los registros. Consulta la API de llamadas
`0-18`	Comunicaciones	Tipo de actividad que representa las interacciones por mensajes de SMS, LinkedIn y WhatsApp asociadas a los registros. Consulta la API de comunicaciones
`0-410`	Cursos	Representa un programa estructurado o una serie de lecciones, sesiones de capacitación o módulos educativos. Consulta la API de objetos
`2-XXX`	Objetos personalizados	Almacena datos que no se pueden almacenar usando los objetos existentes. Para encontrar el parámetro `objectTypeId` de un objeto personalizado, haz una solicitud `GET` a `/crm/v3/schemas`. Consulta la API de objetos
`0-49`	Correos electrónicos	Un tipo de actividad que representa las interacciones individuales por correo electrónico asociadas a los registros. Consulta la API de correo electrónico
`0-19`	Envíos de feedback	Almacena la información enviada mediante una encuesta de feedback. Los envíos de feedback están asociados con los registros de contactos. Consulta la API de envío de feedback
`0-53`	Facturas	Representa las facturas enviadas por transacciones de venta. Las facturas se pueden asociar con contactos, empresas, negocios, elementos de pedido, descuentos, tarifas e impuestos. Consulta la API de facturas
`0-136`	Leads	Representan a los clientes potenciales que han mostrado interés por tus productos o servicios. Consulta la API de leads
`0-8`	Elementos de pedido	Representan cada uno de los productos y servicios vendidos en un negocio. Los elementos de pedido se pueden crear a partir de los productos existentes en tu biblioteca de productos o se pueden crear como elementos de pedido independientes. Consulta la API de elementos de pedido
`0-420`	Fichas	Representan las propiedades o las unidades inmobiliarias que se comprarán, venderán o alquilarán. Consulta la API de objetos
`0-54`	Eventos de marketing	Representan los eventos relacionados con tus iniciativas de marketing, lo que incluye específicamente los eventos de las integraciones conectadas. Puedes especificar si un contacto asistió, se registró o canceló su asistencia a un evento de marketing. Consulta la API de eventos de marketing
`0-47`	Reuniones	Tipo de actividad que representa las reuniones asociadas a los registros. Consulta la API de reuniones
`0-46`	Notas	Tipo de actividad que representa las notas asociadas a los registros. Consulta la API de notas
`0-123`	Pedidos	Representa las compras de comercio electrónico en HubSpot. Consulta la API de pedidos
`0-101`	Pagos	Los pagos hechos por los compradores a través de facturas, enlaces de pago y cotizaciones. Los pagos se pueden asociar con contactos, empresas, negocios, facturas, cotizaciones, elementos de pedido, suscripciones, descuentos, tarifas e impuestos. Consulta la API de pagos
`0-116`	Correo postal	Tipo de actividad que representa las interacciones por correo físico asociadas a los registros. Consulta la API de correo postal
`0-7`	Productos	Representan los bienes o servicios a la venta. Los productos no se pueden asociar con otros objetos del CRM, pero puedes crear elementos de pedido basados en los productos y asociarlos con negocios y cotizaciones. Consulta la API de productos
`0-14`	Cotizaciones	Representan la información sobre los precios que se comparten con los compradores potenciales. Las cotizaciones deben estar asociadas a un negocio, elemento de pedido y plantilla de cotización (`0-64`), pero también pueden estar asociadas a contactos, empresas, descuentos, tasas e impuestos. Consulta la API de cotizaciones
`0-162`	Servicios	Representan los productos intangibles ofrecidos a los clientes. Algunos ejemplos son la incorporación, la consultoría, las reparaciones, el mantenimiento y el cuidado personal. Consulta la API de objetos
`0-69`	Suscripciones	Representan los pagos recurrentes programados a través de enlaces de pago y cotizaciones. Las facturas se pueden asociar con contactos, empresas, negocios, cotizaciones, elementos de pedido, pagos, descuentos, tarifas e impuestos. Consulta la API de suscripciones
`0-27`	Tareas	Tipo de actividad que representa las tareas pendientes asociadas a los registros. Consulta la API de tareas
`0-115`	Usuarios	Representa a los usuarios en tu cuenta de HubSpot. Los usuarios no se pueden asociar con otros objetos, pero se pueden obtener y actualizar a través de la API de usuarios. Consulta la API de detalles de los usuarios

Si bien siempre puedes usar el valor de ID numérico, en algunos casos también puedes usar el nombre del objeto para contactos, empresas, negocios, tickets o notas. Por ejemplo:

Al iniciar una importación con la API de importaciones, el parámetro columnObjectTypeId especifica a qué objeto pertenecen los datos del archivo. Para importar los datos de los contactos, el valor de columnObjectTypeId podría ser contact o 0-1.
Cuando se utiliza la API de asociaciones, los valores de los campos fromObjectType y toObjectType especifican los objetos y la dirección de la asociación. Para ver los tipos de asociación de los contactos y las empresas, la URL de la solicitud GET podría ser crm/v4/associations/contact/company/labels o crm/v4/associations/0-1/0-2/labels.

Identificadores únicos e ID de los registros

Un identificador único es un valor que diferencia a un registro en el CRM de otro, incluso si la información es idéntica. Por ejemplo, el sistema podría tener registros para dos personas llamadas Juan Pérez. Para evitar enviar dinero accidentalmente al Juan Pérez equivocado, a cada registro se le asigna un número como su ID de registro. Cuando se crea un registro en HubSpot, se genera automáticamente un ID de registro (hs_object_id) que debe ser tratado como una cadena de texto. Estos ID solo son únicos en ese objeto, por lo que puede haber un contacto y una empresa con el mismo ID. En el caso de los contactos y las empresas, hay identificadores únicos adicionales, entre ellos, el email de un contacto y el domain de una empresa. También puedes crear propiedades de identificador único personalizadas. En las API del CRM, utilizarás valores de identificadores únicos para identificar y gestionar registros en específico. Siempre puedes utilizar el valor hs_object_id de un registro, pero también puedes utilizar las propiedades de identificador único personalizadas para ciertos endpoints, especificadas mediante el parámetro idProperty. Por ejemplo, para editar un contacto, podrías hacer una solicitud PATCH a /crm/v3/objects/0-1/{contactId} o /crm/v3/objects/0-1/{contactEmail}?idProperty=email. Encuentra más información sobre cómo se gestiona la desduplicación con HubSpot en la base de conocimientos.

API de asociaciones

En HubSpot, puedes ver cómo se relacionan los objetos entre sí asociando los registros. Por ejemplo, puedes asociar múltiples contactos con una empresa y luego asociar la empresa y los contactos relevantes con un negocio. Cuando utilices los endpoints de la API de asociaciones, puedes sustituir objetos por {toObjectTypeId} y {fromObjectTypeId} en las URL de la solicitud y en los cuerpos de la solicitud. Antes de asociar los registros entre objetos, para saber qué objetos se pueden asociar entre sí, puedes obtener los tipos de asociación. Por ejemplo, los contactos se pueden asociar a la mayoría de objetos, mientras que las facturas se pueden asociar con contactos, empresas, negocios, elementos de pedido, descuentos, tarifas e impuestos. Según tu suscripción, puedes describir los tipos de relación específica entre los registros usando etiquetas de asociación, y tu cuenta puede tener objetos personalizados adicionales, que pueden asociarse con los otros objetos estándar. Puedes ver más información acerca de las relaciones de objetos y la gestión de asociaciones utilizando los endpoints de las asociaciones aquí. Si tienes acceso a una cuenta de HubSpot, puedes revisar las relaciones de objetos únicas de tu cuenta en la herramienta del modelo de datos.

API de propiedades

La información sobre los registros se almacena en campos llamados propiedades, que luego se organizan en grupos. HubSpot proporciona un conjunto de propiedades predeterminadas para cada objeto. Además de las propiedades predeterminadas de cada objeto, puedes almacenar datos únicos creando propiedades personalizadas. Al utilizar la API de propiedades, puedes sustituir objetos en los endpoints para crear y gestionar las propiedades de un objeto. Por ejemplo, /crm/v3/properties/0-1 para las propiedades de contacto o /crm/v3/properties/0-5 para las propiedades de ticket. Consulta más información sobre el uso de la API de propiedades en este artículo.

API de búsquedas

Para filtrar y ordenar registros y actividades en función de sus propiedades y asociaciones, puedes utilizar la API de búsquedas. Cuando utilices los endpoints de búsqueda, sustituye el valor {objectTypeId} por el objeto en el que quieres buscar. Por ejemplo, para buscar llamadas, harías una solicitud POST a /crm/v3/objects/0-48/search. Aprende más sobre cómo utilizar la API de búsqueda de CRM en este artículo.

API de pipelines

En HubSpot, puedes utilizar pipelines para hacer seguimiento a los registros a través de las etapas de los procesos. Por ejemplo, puedes monitorizar los negocios a lo largo de los procesos de venta o los tickets en cada estado del servicio de asistencia. Con la API de pipelines puedes crear, obtener, editar y eliminar pipelines y etapas de pipelines. Encuentra más información sobre qué objetos tienen pipelines y cómo utilizar la API de pipelines en este artículo.

​API de objetos

​Nota:

​ID de tipos de objeto

​Identificadores únicos e ID de los registros

​API de asociaciones

​API de propiedades

​API de búsquedas

​API de pipelines