HubSpot retiró sus claves de API clásicas en 2022. La forma moderna de otorgar a una aplicación de terceros acceso a tus datos de HubSpot es una Aplicación Privada: creas la aplicación dentro de tu propia cuenta, marcas exactamente qué alcances puede usar y HubSpot emite un token de acceso de larga duración para pegarlo en Anexus.
HubSpot organiza tus datos en cuatro objetos de CRM: Contactos, Empresas, Negocios y Tickets. Esta integración solo solicita alcances de Contacto, por lo que el token que nos entrega físicamente no puede leer ni escribir tus negocios ni tus tickets.
Quién puede crear el token y en qué cuenta
- Las Aplicaciones Privadas son una función de Súper Administrador en HubSpot. Un usuario estándar, aunque pueda editar todos los contactos, no verá el menú. Si no eres Súper Administrador, pide a quien gestione la cuenta que haga el Paso 1 y te envíe el token.
- Funciona con todas las suscripciones de HubSpot, incluido el CRM gratuito. Las Aplicaciones Privadas no son una función de pago.
- Un token queda vinculado a la única cuenta que lo creó. No se puede mover a otra cuenta de HubSpot, y un token creado en un entorno de pruebas solo escribirá en ese entorno.
Comprueba primero tu Hub ID
Si alguna vez te han añadido a una cuenta de cliente, a una cuenta de partner o a un entorno de pruebas, probablemente tengas más de una cuenta de HubSpot. Tu Hub ID es el número que aparece en la barra de direcciones — app.hubspot.com/contacts/12345678/… — y también se muestra en el menú de la cuenta, arriba a la derecha. Anótalo antes de empezar: si más tarde parece que los contactos no llegan «a ninguna parte», casi siempre están tranquilamente en otro Hub ID.
Crear la Aplicación Privada y copiar su token de acceso
En HubSpot, haz clic en el ícono de engranaje (arriba a la derecha) para abrir la configuración y ve a Integraciones → Aplicaciones Privadas.
Haz clic en Crear una aplicación privada.
En la pestaña Información Básica:
- Nombre: Anexus Connect
- Logo: opcional
- Descripción: "Sincroniza automáticamente con HubSpot los contactos capturados por Anexus"
Cambia a la pestaña Alcances. La lista es larga, así que usa el buscador de la parte superior y marca exactamente estos dos en la sección CRM:
crm.objects.contacts.read— nos permite buscar un Contacto existente por correo antes de escribir, para que la misma persona nunca se dupliquecrm.objects.contacts.write— nos permite crear el Contacto y actualizar sus propiedades
No marques los alcances de Empresas, Negocios ni Tickets: no se usan, y un token más amplio implica un riesgo mayor si alguna vez se filtra.
Haz clic en Crear aplicación en la parte superior derecha y confirma el cuadro de diálogo que muestra HubSpot.
HubSpot abre la aplicación en su pestaña Auth y muestra el token de acceso detrás de un enlace «Mostrar token». Muéstralo, haz clic en Copiar y deja la pestaña abierta hasta que Anexus confirme la conexión.
Qué te dice el prefijo del token
Un token de aplicación privada de HubSpot empieza por pat- seguido de la región donde está alojada tu cuenta — pat-na1-… para Norteamérica, pat-eu1-… para el centro de datos de la UE — y luego un identificador largo. Si lo que pegaste no tiene el prefijo pat-, has copiado la cadena equivocada: el ID de la aplicación y el secreto de cliente están en la misma pantalla y es fácil tomarlos por error.
Conectarlo en Anexus
En Anexus, ve a Configuración → Integraciones CRM.
Busca la tarjeta de HubSpot y haz clic en Conectar.
Pega el token de acceso. Haz clic en Guardar y conectar.
Anexus realiza una llamada de prueba rápida a HubSpot para confirmar que el token funciona y obtener el nombre de tu cuenta (para mostrarlo en la tarjeta). Si tiene éxito, la tarjeta se vuelve verde: comprueba que el nombre mostrado corresponde a la cuenta cuyo Hub ID anotaste antes.
Cómo se asigna un contacto de Anexus a las propiedades de HubSpot
Cada contacto capturado mediante tu formulario de intercambio se convierte en —o actualiza— un registro del objeto Contacto de HubSpot. HubSpot asigna a cada propiedad una etiqueta legible y un nombre interno en minúsculas; el nombre interno es el que buscas al crear una lista o un filtro de workflow.
| Campo de Anexus | Propiedad de HubSpot | Nombre interno | Conviene saber |
|---|---|---|---|
| Correo electrónico | Correo electrónico | email | La clave de deduplicación de HubSpot para el objeto Contacto. Sin correo, no hay sincronización. |
| Nombre | Nombre | firstname | Propiedad predeterminada de HubSpot, presente en todas las cuentas. |
| Apellido | Apellidos | lastname | Propiedad predeterminada de HubSpot, presente en todas las cuentas. |
| Teléfono | Número de teléfono | phone | No es la misma propiedad que Teléfono móvil (mobilephone). |
| Empresa | Nombre de la empresa | company | Una propiedad de texto en el Contacto. No es el registro de Empresa asociado: ver más abajo. |
| Cargo | Cargo | jobtitle | Propiedad de texto libre, así que lo que se escriba en el formulario de intercambio llega intacto. |
| (definido por Anexus) | Estado del lead = Nuevo | hs_lead_status | Se escribe con el valor interno NEW. Es una propiedad de lista desplegable: ver el error de validación más abajo. |
El correo es el eje de todo el flujo. Como HubSpot deduplica los Contactos por la dirección de correo, buscamos a la persona antes de escribir: si el registro existe se actualiza en su sitio y, si no, se crea uno nuevo. Alguien que toque tu tarjeta dos veces con la misma dirección nunca se convertirá en dos Contactos.
El mensaje del formulario de intercambio y la nota que registra cómo se capturó el contacto (toque NFC, escaneo QR, Apple Wallet, enlace compartido) también viajan con cada contacto: consulta Conectar un CRM para ver la lista completa de lo que envía Anexus.
Nombre de la empresa frente al objeto Empresa
Esta es la causa más común de los tickets de «la empresa está mal» en HubSpot. company es una propiedad de texto simple que está en el Contacto. Es algo distinto del objeto Empresa: el registro aparte, con su propio dominio, sector y contactos asociados.
HubSpot tiene un ajuste global: Configuración → Objetos → Empresas → «Crear y asociar automáticamente empresas con contactos». Cuando está activado, HubSpot ignora el nombre de empresa escrito y construye la asociación a partir del dominio del correo. Así, un contacto que escribe «Acme Manufacturing» pero entrega una dirección @acme-mfg.ca queda asociado a la Empresa que HubSpot ya tenga para ese dominio; y quien use un proveedor gratuito como Gmail u Outlook no obtiene ninguna Empresa, porque HubSpot excluye deliberadamente los dominios de correo gratuitos.
Cuando ocurre esto no hay nada roto: el nombre que escribieron sigue en el Contacto, en la propiedad company. Si quieres que ambos coincidan, desactiva el ajuste de asociación automática o construye tus vistas sobre company en lugar de sobre la Empresa asociada.
Estado del lead, etapa del ciclo de vida y contactos de marketing
Los contactos nuevos llegan con hs_lead_status establecido en NEW, de modo que caen directamente en el filtro estándar «Nuevo» del estado del lead y puedes trabajar la cola desde arriba.
El estado del lead no es la etapa del ciclo de vida. HubSpot incluye dos listas desplegables de nombres parecidos: hs_lead_status (Nuevo, Abierto, En proceso, No cualificado…) es la que escribe esta integración, mientras que lifecyclestage (Suscriptor, Lead, MQL, SQL, Cliente…) es la propiedad de embudo sobre la que se construyen la mayoría de paneles y listas. Si tu vista guardada filtra por etapa del ciclo de vida, las personas recién sincronizadas pueden estar en HubSpot y aun así no verse en esa vista. Conviene recordar también que HubSpot no retrocede una etapa del ciclo de vida por su cuenta: alguien que ya es Cliente sigue siendo Cliente aunque toque tu tarjeta como contacto nuevo.
Una peculiaridad más, exclusiva de HubSpot: si tu cuenta usa el modelo de contactos de marketing de Marketing Hub, los contactos creados a través de la API normalmente se crean como contactos no de marketing. Son totalmente visibles y utilizables por ventas, pero no puedes incluirlos en un correo de marketing hasta que se conviertan en contactos de marketing, a mano o con un workflow que lo haga por ti.
Recuperar los contactos que ya capturaste
Para reponer los contactos capturados antes de la conexión, haz clic en Sincronizar contactos anteriores en la tarjeta de HubSpot. Los enviamos en lotes de 50 con una barra de progreso en vivo.
HubSpot aplica dos límites de peticiones, y no funcionan igual. El límite de ráfaga se cuenta por aplicación sobre una ventana móvil de diez segundos —100 peticiones en Free y Starter, 190 en Professional y Enterprise—, así que lo que cuenta es el tráfico de esta integración por sí sola, no el de todo lo demás que tengas instalado en la cuenta. El límite diario sí se comparte entre todas las aplicaciones de la cuenta, y su tamaño depende de tu suscripción. Si una sincronización grande alcanza cualquiera de los dos, HubSpot responde con un 429 y los contactos rechazados quedan pendientes; vuelve a hacer clic en Sincronizar contactos anteriores un poco más tarde para enviarlos.
Solucionar los errores que HubSpot devuelve realmente
Cuando una sincronización falla, la tarjeta de HubSpot muestra el motivo que nos dio HubSpot. Estos son los que probablemente veas.
401: no se encontraron las credenciales de autenticación
HubSpot no reconoce el token en absoluto. O se truncó por el camino (comprueba que sigue empezando por pat- y que un gestor de contraseñas no lo ha recortado), o la aplicación privada se ha eliminado o su token se ha rotado en HubSpot. Abre Configuración → Integraciones → Aplicaciones Privadas, confirma que «Anexus Connect» sigue en la lista, vuelve a copiar el token desde la pestaña Auth y reconéctate en Anexus.
403: la aplicación no tiene los alcances necesarios
El token es válido, pero a su lista de alcances le falta crm.objects.contacts.read o crm.objects.contacts.write. Los alcances pertenecen a la aplicación, no al token, así que esto se corrige en HubSpot y no en Anexus: abre la aplicación privada Anexus Connect, ve a la pestaña Alcances, marca el alcance que falta y confirma el cambio. Después vuelve a copiar el token de acceso desde la pestaña Auth y reconéctate. El fallo habitual es marcar la lectura y olvidarse de la escritura.
409 CONFLICT: «El contacto ya existe»
HubSpot se niega a crear un segundo Contacto con una dirección de correo que ya tiene y, de forma útil, devuelve el ID del registro existente en el mensaje. Como buscamos primero a la persona, normalmente no deberías ver esto. Cuando aparece, significa que la dirección se añadió a HubSpot por otra vía en ese mismo momento —el envío de un formulario, una importación, otra integración— y el reintento simplemente actualizará ese registro.
400: «Los valores de propiedad no son válidos»
Casi siempre es hs_lead_status. El estado del lead es una enumeración y HubSpot solo acepta los valores internos definidos en su lista de opciones. Las cuentas que han personalizado su pipeline de leads a veces borran o renombran la opción NEW, y entonces todas las sincronizaciones fallan la validación. Corrígelo en Configuración → Propiedades: abre Estado del lead y asegúrate de que sigue existiendo una opción con el valor interno NEW. Puedes ponerle la etiqueta que quieras; lo que debe coincidir es el valor interno.
429: la cuenta alcanzó su límite de peticiones
No es un problema de configuración: HubSpot nos está pidiendo que bajemos el ritmo. El límite de ráfaga que provoca la mayoría de los 429 se cuenta por aplicación, así que normalmente es nuestro propio tráfico durante una sincronización grande y no otra integración que te quita el sitio; el que comparten tus otras aplicaciones es el límite diario. El contacto queda pendiente y el siguiente clic en Sincronizar contactos anteriores lo recogerá. Si los 429 siguen apareciendo en las capturas normales del día a día y no durante una sincronización masiva, contacta con el soporte.
La sincronización tuvo éxito pero no encuentras el contacto
Hazlo en este orden. Haz clic en Probar en la tarjeta de HubSpot para confirmar que el token sigue activo. Después compara el nombre de cuenta de la tarjeta con el Hub ID que anotaste: un token creado en un entorno de pruebas solo escribe en ese entorno. Luego busca a la persona por correo con la búsqueda global de HubSpot en lugar de recorrer una lista: una vista guardada solo muestra los registros que cumplen sus filtros, así que un Contacto nuevo puede estar en HubSpot y aun así no aparecer en la vista que estás mirando.
Aun así aparecen contactos duplicados
Dos registros para una misma persona casi siempre significan dos direcciones de correo: la del trabajo el lunes, la personal en la feria el viernes. HubSpot los trata como dos Contactos distintos por diseño, y nosotros también. En las suscripciones Professional y Enterprise, la herramienta Calidad de datos → Gestionar duplicados de HubSpot sugerirá fusiones para los registros que parezcan la misma persona. En Free y Starter esa herramienta no está disponible, pero aún puedes fusionar dos registros a mano desde el menú Acciones de una ficha de contacto. En ambos casos, fusionar es seguro, y las sincronizaciones futuras con cualquiera de las dos direcciones caerán en el registro que sobreviva.
Desactivar la conexión
Haz clic en Desconectar en la tarjeta de HubSpot. Detenemos de inmediato el envío de nuevos contactos. Para revocar también el token desde el lado de HubSpot —algo que conviene hacer siempre que se marche la persona que lo creó— vuelve a Configuración → Integraciones → Aplicaciones Privadas en HubSpot, abre la aplicación Anexus Connect y haz clic en Eliminar. Eliminar la aplicación anula su token de forma inmediata y permanente; no hay vuelta atrás, y una aplicación nueva significa un token nuevo que pegar.
Los contactos ya escritos permanecen en HubSpot tal cual. Desconectar no es eliminar.