Enviar leads a HubSpot

Qué necesitas

La service key de una private app: el token que HubSpot emite en la pestaña Auth de la propia app. HubSpot → Settings → Integrations → Private apps → crea una app → Auth → cópialo. Empieza por pat-.

Tiene que tener estos ocho permisos:

Las rutas que aterrizan en un Deal necesitan crm.objects.deals.read y crm.objects.deals.write; una que aterriza en un Ticket necesita tickets. El de lectura no es opcional: el constructor de rutas lista las propiedades del objeto antes de que puedas asignarlas, y un token que solo tiene el de escritura falla en ese primer listado con "HubSpot aceptó el token pero a la private app le falta el permiso deals-read".

Una Personal Access Key no sirve. Una cuenta de desarrollador de HubSpot emite una clave con permisos developer.* y cms.* y, como mucho, CRM de lectura; no se le puede conceder crm.objects.contacts.write, así que nunca podría escribir un lead por muy nueva que sea. La credencial tiene que salir de una private app dentro del portal CRM donde quieres los leads.

Conectar y enrutar

1. En Destinos, conecta HubSpot con el token.
2. Crea una ruta: elige el objeto (normalmente Contacto) y de que widget toma los leads. Si dejas el widget vacío, toma todos.
3. Mapea los campos. Mapear con IA rellena lo que tiene claro; revísalo y corrige el resto.

Una ruta por widget, y por tanto una por formulario

El alcance de una ruta es un widget. Déjalo en todos los widgets y la ruta toma todos los leads; átalo a uno y toma solo los de ese widget.

Así es también como dos formularios llegan a dos sitios, porque un widget usa un formulario: su captura de leads nombra el formulario que pregunta, así que elegir el widget elige el formulario. Un formulario de contacto en un widget y una solicitud de demo en otro son dos rutas, cada una a su destino. Dos formularios en el mismo widget no es algo que se pueda montar: si cambias el formulario del widget, has cambiado qué formulario pregunta.

Elegir un widget hace algo más: la columna izquierda del mapeo muestra las preguntas de ese formulario, en vez de todas las preguntas de todos los formularios del espacio de trabajo. Así una ruta hecha para la demo no se mapea contra los campos del formulario de contacto, y las preguntas en pantalla son las que de verdad se le van a hacer a un visitante. Si dejas la ruta en todos los widgets las tienes todas, que es lo correcto: la ruta toma leads de todos.

Una consecuencia que conviene saber: un lead que el asistente capta en la conversación lleva el widget del que vino, así que una ruta atada a un widget lo toma como cualquier otro. Un lead empujado por la API sin widget lo toma solo una ruta sin widget.

Como llega un lead

Los contactos se emparejan por email, así que la misma persona rellenando un formulario dos veces actualiza un registro en vez de crear dos.

Un campo sin nada detrás se deja fuera de la petición en lugar de enviarse vacío, porque un valor vacío sobrescribiria lo que HubSpot ya sabe de esa persona.

Compruébalo antes que un visitante

• Comprobar conexión vuelve a preguntarle a HubSpot si el token guardado sigue funcionando y guarda la respuesta con la fecha de hoy. Un token revocado, rotado o cuya app se desinstaló vuelve de HubSpot como "expired 20703 day(s) ago": ese número es la edad del epoch de unix, no un dato sobre tu token, así que lo traducimos.
• Enviar lead de ejemplo crea un contacto inventado por esta ruta, para que veas exactamente qué llega. Usa el mismo mapeo que un lead real. No se guarda como lead ni cuenta contra tu plan; el registro de envíos lo marca como ejemplo.

Cuando falla

El registro de envíos bajo las rutas muestra cada intento, que enviamos y que respondió HubSpot. Respuestas habituales:

• 401 o 403. El token fue revocado, o le falta un scope. La conexión se marca con error.
• Una propiedad no existe. Créala en HubSpot, o usa Nuevo campo en el diálogo de la ruta.
• Falta una propiedad obligatoria. El lead no tenía nada para ella. Mapea otro origen o hazla opcional en HubSpot.

Los problemas de red y las caidas de HubSpot se reintentan cinco veces a lo largo de unas dos horas. Una petición rechazada no se reintenta, porque volver a enviar lo mismo mal no lo va a arreglar.