Integración de Formularios de Hotsite

Aprende a enviar los contactos capturados en tus Landing Pages directamente al CRM usando Claves de Hotsite (Lead API Keys).

Integración de Formularios de Hotsite (Lead API Key)

Caramelo AI ofrece una forma simple y segura para que envíes los contactos (leads) capturados en tus Landing Pages, Hotsites y formularios externos directamente a tu panel de Customers y automatices tus flujos de atención.

Para hacer esto sin exponer datos confidenciales de tu proyecto, utilizamos las Claves de Hotsite (Lead API Keys).

Estas claves son “públicas”, es decir, fueron diseñadas específicamente para ser colocadas en el código JavaScript de tus páginas. Solo tienen permiso para crear y actualizar contactos, siendo incapaces de leer o eliminar ningún dato del sistema.

1. Cómo Generar tu Clave de Hotsite

  1. Accede al Panel (Dashboard) de Caramelo AI y entra a tu Proyecto.
  2. En el menú lateral izquierdo, haz clic en Integraciones > Claves de Hotsite (Leads).
  3. Haz clic en el botón Crear.
  4. Ingresa un Nombre (ej: “Landing Page Black Friday”) y una breve descripción opcional.
  5. Después de crear, se mostrará tu clave (que comienza con lfk_). Copia esta clave.

2. Cómo Integrar en tu Hotsite (JavaScript)

El envío de los datos se realiza a través de una solicitud HTTP POST a nuestra API pública, enviando la clave en el encabezado X-Lead-Key.

Agrega el código a continuación en el JavaScript que procesa el clic en el botón de tu formulario:

// Reemplaza PROJECT_ID y la CLAVE_AQUÍ con tus datos reales.
const PROJECT_ID = "id_de_tu_proyecto";
const LEAD_API_KEY = "lfk_tu_clave_aqui";

// Arma el payload con los datos del formulario
const leadData = {
	name: "Juan Pérez", // Opcional: Nombre del Lead
	email: "juan@ejemplo.com", // Obligatorio: Correo Electrónico (usado como identificador único)
	phone: "11999999999", // Opcional: Teléfono
	interests: "producto-x", // Opcional: Producto de interés

	// El campo 'data' es libre. Úsalo para campos personalizados que quedarán guardados permanentemente en el perfil del cliente
	data: {
		plan_elegido: "Plan Pro",
	},

	// Etiquetas que se agregarán al Lead
	tags: ["hotsite", "black-friday"],

	// Honeypot: Campo de seguridad anti-bot (¡Déjalo siempre VACÍO al enviar por código!)
	_hp: "",
};

// Datos vinculados al evento de conversión que aparecerán en la "Línea de tiempo" del cliente
const eventData = {
	utm_source: "google",
	utm_campaign: "black-friday",
	page_url: window.location.href,
};

// Dispara la solicitud a Caramelo AI
fetch(`https://api.carameloai.com/api/ext/project/${PROJECT_ID}/lead`, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-Lead-Key": LEAD_API_KEY,
	},
	body: JSON.stringify({ 
		lead: leadData,
		event: eventData
	}),
})
	.then((response) => response.json())
	.then((data) => {
		if (data.success) {
			console.log("¡Lead enviado con éxito! ID:", data.customer_id);
			// Redirigir al usuario o mostrar mensaje de éxito
		}
	})
	.catch((error) => {
		console.error("Error al enviar el lead:", error);
	});

3. Seguridad Anti-Bot (Honeypot)

El endpoint de Leads cuenta con protección nativa contra Spam a través de la técnica de “Honeypot” (Tarro de miel) + Limitación de Tasa por IP (Rate Limiting).

El campo _hp presente en el código anterior debe enviarse vacío. Si algún bot de spam rastrea tu código y completa este campo automáticamente con cualquier texto, la solicitud será invalidada silenciosamente. El sistema simulará que todo salió bien para el bot, pero el Lead no se insertará en la base de datos de Caramelo.

4. Protección por Dominio (Origen)

Para evitar que otras personas usen tu clave en sitios no autorizados, puedes restringir de qué dominios tu clave acepta solicitudes.

Al crear o editar tu Clave de Hotsite en el Dashboard, existe un campo opcional para Dominios Permitidos (Origen).

  • Si se deja en blanco, la clave acepta solicitudes de cualquier lugar (útil para pruebas).
  • Si lo completas con https://mihotsite.com, https://otrositio.com, la API de Caramelo AI validará el encabezado Origin de la solicitud y bloqueará automáticamente cualquier envío que provenga de un dominio no listado.

5. Disparo de Flujos (Automatizaciones)

Al recibir la publicación, la API buscará en tu proyecto:

  1. La API buscará estrictamente el contacto utilizando el email proporcionado.
  2. Si el Lead no existe en la base, será Creado usando todos los datos enviados (Nombre, Teléfono, WhatsApp, etc.).
  3. Si el Lead ya existe, el sistema se enfocará en la Integridad de los Datos: los campos principales (name, phone, whatsapp) no serán sobrescritos. Solo los campos complementarios (interests, observations, tags y data) serán actualizados o fusionados con los datos ya existentes en el cliente.

Activando el Flujo: No es necesario configurar ningún webhook especial. Al enviar los datos del Hotsite, la API naturalmente activa el disparador interno database__record_created o database__record_updated. Simplemente crea un flujo en Caramelo que sea “Iniciado al crear o actualizar cliente” y se activará automáticamente, pudiendo enviar correos electrónicos de bienvenida, avisar al equipo comercial, etc.

6. Línea de Tiempo de Eventos (Timeline)

Siempre que se crea o actualiza un contacto a través del Hotsite utilizando esta API, Caramelo AI registrará automáticamente un evento en la pestaña “Timeline” dentro del perfil de este cliente en el Panel.

  • Historial Completo (Payload Guardado): Independientemente de si se actualizan o no los campos vitales del cliente, todos los datos enviados en la solicitud (tanto del objeto lead como del event) se guardan en el evento de la línea de tiempo. Esto garantiza que tu equipo siempre podrá ver exactamente lo que el Lead escribió en un formulario determinado, sin comprometer los datos oficiales del contacto en el sistema.
  • Payload Adicional: El objeto event enviado en la solicitud (fuera del objeto lead) es perfecto para almacenar información puntual y transitoria (ej: la URL donde convirtió, las UTMs específicas de esa sesión o información temporal del dispositivo).

Atención (Límite de Payload): Para proteger la integridad del sistema, el endpoint de envío de leads tiene un límite estricto de 1MB en el tamaño del cuerpo de la solicitud (payload size limit). Evita enviar archivos codificados en Base64 a través de esta ruta.