HubSpot

Descripción

Integración con la API de CRM v3 de HubSpot. La familia cubre todo el ciclo de vida de un registro del CRM: crearlo, leerlo por id, actualizar sus propiedades, listar una página de registros, buscarlo con filtros y archivarlo.

Los seis nodos trabajan sobre un objeto genérico del CRM: en lugar de un nodo por entidad, elegís el tipo de objeto (contacts, companies, deals, tickets) en un parámetro y el mismo nodo te sirve para todo el CRM.

La autenticación se resuelve con el módulo de credenciales (proveedor hubspot) mediante un token de Private App enviado como token Bearer. La URL base https://api.hubapi.com ya viene incorporada, así que nunca escribís un endpoint.

Operaciones

Crear objeto Creá un contacto, empresa, negocio o ticket.

Leer objeto Leé un objeto por su id y elegí las propiedades.

Actualizar objeto Cambiá propiedades de un objeto existente.

Listar objetos Listá una página de objetos con cursor.

Buscar objetos Buscá con grupos de filtros, orden y consulta.

Borrar objeto Archivá un objeto (borrado recuperable).

Los nodos de un vistazo

Nodo	Nombre interno	Llamada HTTP
HubSpot: Crear objeto	hubspotCreateObject	POST /crm/v3/objects/{object_type}
HubSpot: Leer objeto	hubspotGetObject	GET /crm/v3/objects/{object_type}/{id}
HubSpot: Actualizar objeto	hubspotUpdateObject	PATCH /crm/v3/objects/{object_type}/{id}
HubSpot: Listar objetos	hubspotListObjects	GET /crm/v3/objects/{object_type}
HubSpot: Buscar objetos	hubspotSearchObjects	POST /crm/v3/objects/{object_type}/search
HubSpot: Borrar objeto	hubspotDeleteObject	DELETE /crm/v3/objects/{object_type}/{id}

Configuración

Todos los nodos de la familia comparten estos dos parámetros; el resto está documentado en la página de cada operación.

Parámetro	Tipo	Obligatorio	Descripción
credentials_id	credentials	Sí	Credencial de HubSpot (proveedor hubspot)
object_type	text	Sí	Tipo de objeto: contacts, companies, deals, tickets. Por defecto contacts

Credenciales

Proveedor: hubspot. Creala en Credenciales → Agregar → HubSpot.

Campo	Descripción
token	Token de la Private App, desde HubSpot → Settings → Integrations → Private Apps. Empieza con pat-. Se enmascara en los logs.
timeout	Opcional. Tiempo máximo de la petición en milisegundos (por defecto 20000).

El token viaja en la cabecera Authorization con el prefijo Bearer. El botón Test de la credencial llama a GET /crm/v3/objects/contacts?limit=1, así que la Private App necesita al menos el scope crm.objects.contacts.read para que la prueba pase, más los scopes de todo lo que quieras automatizar.

Importante: cómo se elige el tipo de objeto

Esta es la parte que más confunde. object_type es un campo de texto libre, no un desplegable. Lo que escribas se codifica y se agrega a /crm/v3/objects/, así que tiene que ser el nombre de API en plural y en minúsculas que usa HubSpot en sus endpoints, no la etiqueta que ves en la interfaz.

Lo que gestionás en HubSpot	object_type
Contactos (personas)	contacts
Empresas	companies
Negocios (oportunidades)	deals
Tickets (servicio)	tickets

Dos consecuencias que conviene tener presentes:

• Si dejás el campo vacío, el nodo usa contacts.
• El valor no se valida antes de la llamada. Un nombre mal escrito (contact, Contacts, company) se envía tal cual a HubSpot y vuelve como un 404.

El campo acepta variables dinámicas, así que {{data.objectType}} funciona cuando el tipo se decide antes en el flujo. Como el valor se pasa sin tocar, cualquier otro tipo de objeto servido en el mismo endpoint —un objeto personalizado referenciado por su object type id— también llega a HubSpot, pero los cuatro tipos de arriba son los que los nodos documentan y toman por defecto.

Importante: las propiedades son un mapa plano

HubSpot representa un registro como un mapa plano de propiedades: sin anidamiento y sin arrays de objetos de campo.

{ "email": "ana@acme.com", "firstname": "Ana", "phone": "+34600111222" }

Las claves son los nombres internos de las propiedades de HubSpot, que no son las etiquetas que ves en la interfaz. Los encontrás en HubSpot → Settings → Properties. Las más habituales:

Objeto	Propiedades frecuentes
contacts	email, firstname, lastname, phone, company, lifecyclestage
companies	name, domain, industry, phone, city
deals	dealname, amount, dealstage, pipeline, closedate
tickets	subject, content, hs_pipeline, hs_pipeline_stage

Los nodos de crear, actualizar y buscar reciben ese JSON como parámetro. Las variables dinámicas se resuelven dentro del texto del JSON antes de parsearlo, así que {"email":"{{data.email}}"} funciona.

Salida

Crear, leer y actualizar devuelven el objeto de HubSpot en data, más un _meta con la versión del módulo y los tiempos:

{
  "data": {
    "id": "701",
    "properties": {
      "email": "ana@acme.com",
      "firstname": "Ana",
      "createdate": "2026-08-05T10:00:00.000Z"
    },
    "createdAt": "2026-08-05T10:00:00.000Z",
    "updatedAt": "2026-08-05T10:00:00.000Z",
    "archived": false
  },
  "_meta": { "moduleVersion": "1.0.0", "success": true, "id": "701", "objectType": "contacts", "totalMs": 240 }
}

Listar y buscar devuelven el array results directamente en data (no el sobre), listo para recorrer. Borrar devuelve un objeto pequeño de confirmación.

Si algo falla, el nodo corta la rama y devuelve un objeto error en lugar de los datos:

{
  "data": {},
  "error": { "message": "Property \"emai\" does not exist", "type": "validation", "status": 400 }
}

API utilizada

• HubSpot CRM API v3 — https://developers.hubspot.com/docs/api/crm/understanding-the-crm

Notas

• Las variables dinámicas tipo {{data.email}} se resuelven en todos los parámetros de texto (object_type, object_id, properties, limit, after) y también dentro de los parámetros JSON, porque el JSON se resuelve como texto y se parsea después. Si el resultado no es JSON válido, el nodo falla con un error de validación en vez de enviar un payload incompleto: cuidado con los valores que contienen comillas dobles.
• Los reintentos son automáticos, con un tope de 3 intentos y espera exponencial, para errores de red, timeouts, 429 (respetando Retry-After) y 5xx. Los errores de validación (400/409), 404 y de autenticación no se reintentan.
• El tiempo máximo por petición es de 20 segundos; podés subirlo con el campo timeout de la credencial.
• El token nunca se escribe completo en los logs: solo una forma enmascarada del estilo pat-…wxyz.
• Borrar archiva: el registro se puede restaurar desde HubSpot.

Gestión de errores

Situación	¿Se reintenta?	Qué hacer
Validación (400/409)	No	HubSpot explica el motivo en message (propiedad inexistente, contacto duplicado…). Corregí los datos.
No encontrado (404)	No	El objeto o el tipo de objeto no existe. Revisá el id y object_type.
Autenticación (401/403)	No	Token inválido o faltan scopes en la Private App. Revisá la credencial.
Límite de tasa (429)	Sí	Se respeta Retry-After y se reintenta la llamada.
Servidor (5xx)	Sí	Error temporal de HubSpot; se reintenta solo.
Red / Timeout	Sí	Problema transitorio; se reintenta solo.

Los errores de validación no se reintentan

Un dato mal formado no se reintenta: mandar el mismo payload otra vez solo repetiría el fallo. Corregí la entrada y volvé a ejecutar el flujo. Los reintentos automáticos se ven en el panel de Cola de reintentos (DLQ).

Ver también

• Salesforce — la otra familia de CRM, basada en SOQL y sObjects.
• Monday — gestión del trabajo con un modelo de tableros parecido a un CRM.
• Integraciones de CRM — casos de uso completos entre CRMs.
• Variables dinámicas — cómo se resuelve {{data.campo}}.
• Nodo HTTP — para los endpoints de HubSpot que estos nodos no cubren (asociaciones, pipelines, propiedades…).

Automatizá HubSpot con Floogos

Construí esto sin código y ponelo en producción en minutos.

Ver la integración de HubSpot Empezar gratis Solicitar demo