Módulo 6: CRM con HubSpot

Troubleshooting de HubSpot

Siguiente →

Descripción de la cápsula

Tus workflows de HubSpot funcionan en la prueba. En producción aparecen los problemas que no son de lógica: una propiedad que "no existe" cuando jurarías que sí, un ID de etapa que el nodo rechaza, duplicados que se cuelan a pesar de tus cuidados, un error de límite cuando procesas muchos leads.

Este es el manual de diagnóstico del módulo. Y tiene una particularidad: la mayoría de los problemas de HubSpot vienen de que el CRM es un sistema rico y estructurado — muchas propiedades, valores internos que difieren de las etiquetas visibles, IDs por todas partes. No son fallos misteriosos: son consecuencia de no tener clara la diferencia entre lo que ves y lo que la API espera.

Los cuatro problemas que verás: propiedades (nombres internos vs etiquetas), IDs de etapas y pipelines, duplicados, y límites de la API. No hay operación nueva — hay reconocimiento de síntomas.

Lo que vas a aprender

Al terminar esta cápsula serás capaz de:

  • ✅ Diagnosticar errores de propiedades — nombre interno vs etiqueta visible
  • ✅ Resolver problemas con IDs de etapas y pipelines de deals
  • ✅ Entender por qué se cuelan duplicados y cómo cerrarles la puerta
  • ✅ Manejar los límites de la API de HubSpot
  • ✅ Leer los errores de HubSpot y clasificarlos rápido
  • ✅ Reconocer cuándo el problema es "lo que ves" vs "lo que la API espera"

Problema 1: Propiedades — nombre interno vs etiqueta visible

El síntoma

  • property does not exist / propiedad no encontrada para una propiedad que claramente existe en HubSpot
  • Mapeas un valor y la propiedad queda vacía, sin error
  • Una propiedad de desplegable rechaza un valor que es exactamente la opción que ves en pantalla

Por qué pasa

Esta es la confusión de HubSpot. Cada propiedad tiene dos identidades:

Lo que vesLo que la API usa
NombreLa etiqueta: "Estado del lead"El nombre interno: hs_lead_status
Valor de un desplegableLa etiqueta: "Cliente potencial"El valor interno: lead

Tú ves etiquetas legibles. La API trabaja con nombres y valores internos, que a menudo no coinciden con las etiquetas (están en inglés, sin espacios, abreviados). Cuando mapeas usando la etiqueta visible en vez del nombre interno, la API no la reconoce.

Las soluciones

1. Usa el nombre interno de la propiedad. En HubSpot, en la configuración de propiedades, cada propiedad muestra su nombre interno además de su etiqueta. Ese nombre interno es el que va en tu mapeo.

2. Para desplegables, usa el valor interno. Una propiedad de opciones tiene, por cada opción, una etiqueta visible y un valor interno. Manda el valor interno.

3. El selector del nodo ayuda — úsalo. El nodo de n8n a menudo ofrece selectores que muestran las etiquetas legibles y resuelven los nombres/valores internos por detrás. Cuando esté disponible, es la forma más segura.

4. Mira el output de una lectura. Lee un registro existente y observa cómo se llaman realmente las propiedades en la respuesta. Eso te da los nombres internos exactos — no los adivines.

El principio del módulo de troubleshooting: casi todo se reduce a la diferencia entre lo que ves y lo que la API espera. Cuando algo de HubSpot no cuadra, esa es la primera hipótesis.

Problema 2: IDs de etapas y pipelines

El síntoma

  • Un Create o Update de deal falla al definir dealstage o pipeline
  • El deal se crea pero "en ningún lado" o en una etapa equivocada
  • Funciona con un pipeline y falla con otro

Por qué pasa

Es el Problema 1 aplicado a deals — y por eso lo separamos, porque es el más común con deals. Recuerda la cápsula 04: pipelines y etapas se identifican con IDs internos, no con sus nombres visibles. "Propuesta enviada" es una etiqueta; la API espera el ID de esa etapa. Y las etapas pertenecen a un pipeline específico — el ID de "Negociación" del pipeline A no sirve para el pipeline B.

Las soluciones

1. Usa los selectores del nodo para pipeline y etapa siempre que estén disponibles — resuelven los IDs por ti.

2. Si necesitas los IDs explícitos, HubSpot los expone en la configuración de pipelines, y también puedes obtenerlos leyendo la estructura vía el nodo (con el scope de schemas).

3. Verifica que la etapa pertenece al pipeline correcto. Si cambiaste de pipeline, los IDs de etapa cambian.

Problema 3: Duplicados que se cuelan

El síntoma

A pesar de tus cuidados, aparecen contactos o empresas duplicados en el CRM.

Por qué pasa

Recuerda la cápsula 03: HubSpot deduplica contactos por email y empresas por dominio. Los duplicados se cuelan cuando esa clave no es consistente:

  • Email sin normalizar: ANA@correo.com, ana@correo.com, ana@correo.com — para HubSpot pueden ser tres personas si el dato llega así de sucio
  • Usar Create en vez de Create or Update: Create no deduplica — crea sin preguntar
  • Email ausente: un contacto creado sin email no tiene clave de deduplicación — el siguiente "mismo" contacto se crea como nuevo
  • Empresas sin dominio: mismo problema, con el dominio

Las soluciones

1. Normaliza la clave antes de usarla. Email y dominio: minúsculas, sin espacios. Siempre. Es el diseño defensivo del Módulo 1, y aquí es crítico.

2. Usa Create or Update, no Create. Para captura de leads, casi siempre.

3. Exige la clave. Si un contacto puede llegar sin email, decide qué hacer antes de crearlo — no lo crees "a ciegas" sin clave de deduplicación.

4. HubSpot tiene herramientas de gestión de duplicados en su interfaz, para limpiar los que ya se colaron. Pero la prevención (clave normalizada + Create or Update) es mejor que la limpieza.

Problema 4: Límites de la API

El síntoma

Errores de límite / 429 al procesar muchos registros, o cuando varios workflows golpean HubSpot a la vez.

Por qué pasa

HubSpot, como toda API, limita las llamadas por unidad de tiempo. Los límites dependen del tipo de cuenta. Un workflow que hace una operación por item sobre cientos de leads choca con el límite — el mismo patrón que viste en Sheets, Slack, Airtable y Notion.

Las soluciones

1. Operaciones en lote (batch). La API de HubSpot soporta crear/actualizar varios registros en una llamada. Úsalo en vez de procesar uno por uno.

2. Espaciar. Un nodo Wait entre operaciones si tienes que procesar individualmente.

3. Reintentar. Configura Retry On Fail — un límite es temporal.

4. Reducir frecuencia. Si un Schedule corre muy seguido con muchas operaciones, baja el ritmo.

El principio, una vez más (lo viste en Sheets, Slack, Airtable/Notion): trata cada llamada como cara. Es transversal a toda integración — no hay una sola herramienta de esta guía donde no aplique.

Cómo leer un error de HubSpot

El error menciona...Es un problema de...Ve a...
property does not exist, unknown propertyNombre interno de propiedadProblema 1
invalid option, valor de un desplegableValor interno de una opciónProblema 1
dealstage, pipeline, invalid stageIDs de etapa/pipelineProblema 2
(duplicados en el CRM, sin error)Clave de deduplicación inconsistenteProblema 3
rate limit, 429, too many requestsLímite de la APIProblema 4
401, invalid token, unauthorizedToken inválido o revocadoRecrea la credencial
403, missing scopeFalta un scope en la app privadaEdita la app privada (cápsula 02)

El caso más engañoso, como en otros módulos, es el que no da error: los duplicados. El workflow dice "éxito" porque el contacto sí se creó — el problema es que se creó de más. Cuando "todo funciona" pero el CRM se ensucia, piensa en el Problema 3.

Trampas comunes

Trampa 1: Mapear con la etiqueta visible en vez del nombre interno

Qué pasa: Usas "Estado del lead" o "Cliente potencial" — etiquetas — y la API no las reconoce.

Cómo evitar: Usa nombres y valores internos. Apóyate en los selectores del nodo y en el output de una lectura real.

Trampa 2: Usar el nombre de la etapa para mover un deal

Qué pasa: dealstage = "Negociación" falla — la API espera el ID.

Cómo evitar: Selectores del nodo, o los IDs internos de las etapas. Y verifica que la etapa sea del pipeline correcto.

Trampa 3: Confiar en la deduplicación con datos sucios

Qué pasa: Usas Create or Update pero el email llega sin normalizar — la deduplicación falla y se cuela un duplicado.

Cómo evitar: Normaliza la clave (email/dominio) antes. Create or Update solo dedup­lica bien si la clave es consistente.

Trampa 4: Procesar leads uno por uno en volumen

Qué pasa: 500 leads → 500 llamadas → rate limit.

Cómo evitar: Operaciones en lote.

Trampa 5: Asumir que "lo que ves" es "lo que la API usa"

Qué pasa: Pierdes tiempo porque mapeaste todo con las etiquetas visibles.

Cómo evitar: Es el principio del módulo: lo que ves ≠ lo que la API espera. Nombres internos, valores internos, IDs. Cuando dudes, mira el output de una lectura real.

Ejercicio: diagnostica cinco situaciones

Objetivo: practicar la clasificación rápida.

Tu tarea

Para cada situación, di (1) qué problema es y (2) el primer paso:

  1. Un Update de contacto falla con property "Estado del lead" does not exist.
  2. Un Create de deal falla al definir la etapa; pusiste dealstage = "Propuesta enviada".
  3. El CRM tiene tres contactos "Ana López" con emails ANA@x.com, ana@x.com y ana@x.com (con espacio).
  4. Un workflow que importa 800 contactos empieza a fallar con 429 a la mitad.
  5. Un workflow usa Create para captura de leads y el CRM se llena de duplicados.
Ver respuestas
  1. Nombre interno de propiedad (Problema 1). Primer paso: usar el nombre interno (hs_lead_status), no la etiqueta visible.
  2. ID de etapa (Problema 2). Primer paso: usar el selector del nodo o el ID interno de la etapa, no su nombre.
  3. Email sin normalizar (Problema 3). Primer paso: normalizar el email (minúsculas, sin espacios) antes de usarlo como clave; limpiar los duplicados existentes con las herramientas de HubSpot.
  4. Límite de la API (Problema 4). Primer paso: cambiar a operaciones en lote (batch) en vez de uno por uno.
  5. Create en vez de Create or Update (Problema 3). Primer paso: cambiar la operación a Create or Update para que HubSpot deduplique por email.

Resumen y siguiente paso

  • El principio del módulo: la mayoría de los problemas de HubSpot vienen de la diferencia entre lo que ves (etiquetas) y lo que la API espera (nombres/valores internos, IDs)
  • Propiedades: usa nombres internos, no etiquetas; para desplegables, valores internos; apóyate en los selectores del nodo y en el output de una lectura real
  • IDs de etapas/pipelines: el Problema 1 aplicado a deals — usa selectores o IDs internos; las etapas pertenecen a un pipeline específico
  • Duplicados: se cuelan cuando la clave (email/dominio) es inconsistente — normaliza la clave + usa Create or Update; es el problema que no da error
  • Límites: operaciones en lote — el principio transversal de toda integración de la guía
  • 5 trampas: etiqueta en vez de nombre interno, nombre de etapa en vez de ID, deduplicar con datos sucios, procesar uno por uno, asumir que "lo que ves" es lo que la API usa

Antes de avanzar deberías poder:

  • Distinguir el nombre interno de una propiedad de su etiqueta visible
  • Diagnosticar un error de dealstage
  • Explicar por qué se cuelan duplicados y cómo prevenirlos

Lo que sigue (cápsula 08):

Tienes el modelo completo de HubSpot y sabes diagnosticarlo. El mini-proyecto junta todo en el flujo que es el corazón de la automatización de ventas: lead → contacto → deal — capturar una oportunidad y dejarla lista, asociada y con seguimiento, en el CRM.

Recursos adicionales

  1. HubSpot: nombres internos de propiedades - Dónde ver el nombre interno de cada propiedad.
  2. HubSpot API: límites de uso - Los límites oficiales de la API.
  3. HubSpot: gestión de duplicados - Herramientas para limpiar duplicados existentes.

Creado: Mayo 14, 2026 Versión: 1.0

← AnteriorActividades y TareasSiguiente →Mini-Proyecto: El Flujo Lead → Contacto → Deal