Conecta HubSpot con Merez con una app privada

Conectar HubSpot a Merez se hace con un solo campo: el token de app privada. Con ese token, los contactos que nacen en Merez llegan a HubSpot y los cambios que haces en Merez viajan al momento. Aquí ves de dónde sale el token, qué permisos necesita, cómo probarlo y qué esperar de la sincronización.

Qué necesitas antes de empezar

• Una cuenta de HubSpot con acceso a la sección Desarrollo. Para crear el token necesitas ser super administrador o tener el permiso de herramientas de desarrollo en la configuración de la cuenta.
• El módulo CRM activo en tu sitio de Merez. La integración vive ahí.
• Claridad sobre qué contacto quieres sincronizar. HubSpot identifica los contactos por correo electrónico, así que el correo es el dato que más importa.
• Un responsable del token. Es una credencial de larga vida: si se filtra, cualquiera con ella puede leer y escribir contactos en tu portal.

Un detalle que cambió y conviene saber: HubSpot ya no permite crear apps privadas heredadas. Las que existen siguen funcionando, pero si empiezas de cero el camino documentado para obtener un token de API es una service key. Las dos rutas te dan un token con el mismo formato y los mismos permisos por objeto, y las dos sirven para este campo. Abajo están las dos, en orden.

Las credenciales, una por una

En Merez solo hay un campo que llenar. Todo lo demás pasa en HubSpot.

Campo	Qué es	Dónde se consigue
Token de app privada	El access token que autoriza a Merez a leer y escribir contactos en tu portal. Viaja en la cabecera de autorización como un token Bearer y empieza por pat-.	En HubSpot, en Desarrollo. Con la ruta de app privada heredada o con la ruta de service key, según lo que tengas disponible.

Ruta A: app privada heredada, solo si ya la tienes

1. En tu cuenta de HubSpot entra a Desarrollo y en el menú lateral abre Aplicaciones anteriores (en inglés, Legacy apps).
2. Abre tu app privada y ve a la pestaña Auth.
3. Haz clic en Show token para revelar el token y luego en Copy para copiarlo.
4. Pega ese valor en el campo Token de app privada de Merez.

Si no tienes una app privada creada, esta ruta no está disponible: HubSpot cerró la creación de apps privadas heredadas. Pasa a la ruta B.

Ruta B: service key, la que funciona hoy si empiezas de cero

1. En tu cuenta de HubSpot entra a Desarrollo y en el menú lateral abre Keys y luego Service keys.
2. Arriba a la derecha, haz clic en Create service key y ponle un nombre reconocible, por ejemplo Merez CRM.
3. Haz clic en Add new scope y marca los dos permisos que necesita la integración: crm.objects.contacts.read y crm.objects.contacts.write. Puedes buscarlos en la barra Find a scope.
4. Haz clic en Update, revisa la lista de permisos y confirma con Create.
5. Abre la service key, haz clic en Show para verla y en Copy para copiarla.
6. Pega ese valor en el campo Token de app privada de Merez.

Los dos permisos son obligatorios. Con solo read, Merez puede leer contactos pero no crearlos ni actualizarlos. Con solo write, escribe pero no puede comprobar qué hay del otro lado. Si falta uno, la sincronización falla con un error de permisos, no con un error de red.

El permiso de lectura y el de escritura de contactos están disponibles en cualquier plan de HubSpot. Los permisos sobre datos sensibles y altamente sensibles son otra cosa y solo aplican a Enterprise: si Merez te muestra un error de permisos con un plan básico, revisa que hayas marcado los dos permisos de contactos y no unos de datos sensibles.

Simulación de uso: de la plataforma a Merez

Una ferretería con dos sedes usa Merez para atender su sitio web y HubSpot para su equipo comercial. El dueño del sitio pega el token en el módulo CRM y guarda.

El lunes a las diez de la mañana entra un lead por el formulario del sitio: un contratista que pide precio de malla y varilla. Merez crea el contacto con su nombre, su correo y su teléfono. Ese contacto aparece en HubSpot en la siguiente pasada de sincronización, que corre cada 6 horas. Si el lead entra a las diez de la mañana y la última pasada fue a las nueve, aparece en la pasada de las tres de la tarde.

Mientras tanto, la asesora abre la ficha del contacto en Merez y le agrega una nota y cambia la etapa. Ese cambio no espera: viaja a HubSpot al momento. La regla es sencilla. Lo que haces en Merez sale de inmediato; lo que haces en HubSpot llega a Merez en la siguiente pasada de 6 horas.

El jueves, alguien del equipo comercial actualiza el teléfono del contacto directamente en HubSpot. Ese cambio aparece en Merez en la siguiente sincronización. Si el equipo comercial edita el mismo contacto justo antes de una pasada, conviene esperar a que la sincronización termine antes de editar desde Merez, para no escribir dos versiones del mismo dato.

Cómo comprobar que quedó bien

1. Guarda el token en Merez. Si el campo queda guardado sin error de permisos, la autenticación pasó.
2. Crea un contacto de prueba en Merez con un correo que controles, por ejemplo prueba.hubspot@tudominio.com. No uses el correo de un cliente real.
3. Espera la ventana de 6 horas y busca ese correo en Contactos de HubSpot. Si aparece con los datos que escribiste, la escritura funciona.
4. Cambia un dato del contacto en Merez, por ejemplo el teléfono. Ese cambio debe verse en HubSpot sin esperar la ventana, porque los cambios hechos en Merez viajan al momento.
5. Cambia un dato en HubSpot, por ejemplo el cargo. Revisa la ficha en Merez en la siguiente pasada de 6 horas: así confirmas que la lectura también está funcionando.
6. Revisa los registros del lado de HubSpot. En la app privada heredada hay una pestaña Logs con las llamadas de los últimos 30 días. En la service key, el botón View logs te muestra lo mismo. Ahí ves si las llamadas salen con 200 o con 401 y 403.

Errores frecuentes

Síntoma	Causa	Qué hacer
Merez rechaza el token	El token se copió incompleto o se rotó en HubSpot y el guardado quedó viejo.	Vuelve a copiarlo con el botón Copy y pégalo de nuevo. No lo escribas a mano.
Error de permisos al crear o actualizar contactos	Falta crm.objects.contacts.write en el token.	Edita la service key o la app privada y agrega el permiso que falta. El token no cambia de texto, pero los permisos sí se actualizan.
El token funciona pero no veo contactos	Falta crm.objects.contacts.read, o el token pertenece a otro portal.	Agrega el permiso de lectura. Si el token es de otro portal, genera uno nuevo en el portal correcto.
Deja de funcionar de un día para otro	Se eliminó el usuario que creó la app o la service key. HubSpot responde que el usuario no tiene permisos.	Rota el token desde una cuenta activa y pega el nuevo en Merez.
Faltan permisos después de un cambio de plan	El portal perdió acceso a una funcionalidad y los permisos del token se ajustaron solos.	Revisa los permisos de la app en HubSpot y confirma el plan. El texto del token no cambia, pero sus permisos sí.
El contacto no aparece en HubSpot	Todavía no pasó la ventana de 6 horas, o el correo ya existe en HubSpot como otro contacto.	Espera la siguiente pasada. Si el correo ya existe, revisa el contacto que ya estaba antes de duplicarlo.

Límites y buenas prácticas

La sincronización de entrada corre cada 6 horas. La de salida, la de los cambios que haces en Merez, viaja al momento. Esa asimetría es la que más confunde: no es un error, es el diseño. Si necesitas que un cambio hecho en HubSpot se vea ya en Merez, espera la siguiente pasada en lugar de repetir el cambio.

Merez no administra tu portal de HubSpot ni sus propiedades personalizadas. Lo que hace es leer y escribir contactos con los permisos que le diste. Si le quitas un permiso, deja de hacer esa parte y el resto sigue igual.

Plan de HubSpot	Llamadas por cada 10 segundos	Llamadas por día
Free y Starter	100 por app privada	250.000 por cuenta
Professional	190 por app privada	625.000 por cuenta
Enterprise	190 por app privada	1.000.000 por cuenta

Buenas prácticas con el token:

• Trátalo como una contraseña. Quien lo tenga puede leer y escribir contactos en tu portal.
• Rota el token cada seis meses, que es la recomendación de HubSpot, o de inmediato si sospechas que se filtró. Al rotarlo, pega el nuevo en Merez el mismo día.
• No compartas el token por chat ni lo dejes en un documento abierto. Guárdalo en el gestor de contraseñas de la empresa.
• Da solo los permisos que se usan. Los dos de contactos alcanzan para esta integración; no agregues permisos de otros objetos por si acaso.
• Ten en cuenta los límites de apps. En apps privadas heredadas el tope es de 20 por cuenta. En service keys, apps de proyecto y conectores MCP hay un límite combinado de 100 por cuenta.