Un formulario de contacto que manda un email a alguien que está de vacaciones es el cementerio de los leads. Con Sitecog, cada formulario de tu web llega como una tarjeta al CRM: con teléfono o email, un estado y alguien responsable de devolver la llamada. Basta con un atributo en un <form>; si necesitas más control, tienes JavaScript y el servidor.
Tres formas de enviar un lead; elige la que mejor te encaje:
- Un formulario con
data-crm-lead: cero JavaScript. El widget intercepta el envío y se encarga del resto. window.crmLead(): para React, Vue y cualquier formulario que controles tú.POST /marketing/eventdesde tu servidor: pedidos por teléfono, formularios procesados en el backend, integraciones con otros sistemas.
Cómo llega un lead de tu formulario al CRM
Cada formulario de leads tiene un nombre, y tu sitio ya viene con uno: el formulario integrado lead_submit, “Solicitud desde la web”. Cualquier formulario con el atributo data-crm-lead vacío envía sus leads ahí, y cada envío se convierte en una tarjeta en CRM → Leads sin tocar nada en el CRM. El formulario integrado aparece en los sitios cuyo plan incluye leads.
- Un visitante rellena el formulario y pulsa “Enviar”.
- El widget recoge los campos del formulario y los envía; el servidor se encarga de averiguar cuál es el nombre, el teléfono, el email y el mensaje.
- El servidor comprueba que ese formulario existe, que el lead trae teléfono o email y que no tiene pinta de bot.
- Aparece una tarjeta de lead en el CRM y, si lo has configurado, una notificación en Telegram.
Dos reglas que conviene tener claras desde el principio:
- Un nombre no declarado se rechaza. El CRM solo acepta los formularios que conoce: nada de basura sorpresa por culpa de una errata. El único que se crea por sí solo es el integrado,
lead_submit. - Los formularios de leads y los eventos de analítica no se mezclan. Un lead enviado con el nombre de un evento de analítica se rechaza, y
crmTrackcon el nombre de un formulario de leads no registra nada. El CRM te enseña cada uno de esos rechazos en “Últimos rechazos”.
Formularios propios: créalos en el CRM
El formulario integrado basta mientras todos los leads de tu web sean del mismo tipo. ¿Quieres distinguir “Te llamamos” de “Pide presupuesto” en la lista de leads, en el filtro y en los contadores de la página “Formularios”? Dale a cada formulario su propio nombre. Un par de clics, una vez por cada tipo de formulario:
Abre Leads → Formularios
Es el botón “Formularios” de la cabecera de la sección Leads. Aquí están todos los formularios de leads del sitio y cuántos leads ha traído cada uno en los últimos 30 días. Los formularios archivados aparecen al marcar “Mostrar archivo”.Pulsa “Nuevo formulario”
Ponle el nombre que usará tu código: letras latinas, dígitos y guiones bajos, empezando por una letra:callback_request,quote_request. Luego el nombre no se puede cambiar: revisa bien cómo lo escribes.Opcional: marca “Este formulario genera ingresos”
Solo así se guardan el importe y la moneda del lead. Sin esta casilla se ignoran sin decir nada.Pon el nombre en tu web
data-crm-lead="callback_request"en el formulario,crmLead('callback_request', …)en el código o"name": "callback_request"en la petición desde el servidor. El CRM te enseña el código listo para las tres vías en la página del formulario.
Opción A: un formulario con un atributo
Añade el atributo data-crm-lead a cualquier formulario de una página que tenga el script del widget. Esa es toda la integración. Un atributo vacío envía el lead al formulario integrado lead_submit; con un valor, a tu formulario con ese nombre (data-crm-lead="quote_request"). Los formularios que aparecen más tarde (en un modal, tras un cambio de ruta en una SPA) se detectan solos, siempre que se inserten en la página ya con el atributo.
<form data-crm-lead>
<input name="name">
<input name="phone" type="tel">
<textarea name="message"></textarea>
<button type="submit">Enviar</button>
</form>Ejemplo completo
Un formulario de “pide presupuesto” (quote_request, creado en “Leads → Formularios” con la casilla “Este formulario genera ingresos”) con nombre, teléfono, email y mensaje, el importe del pedido (el total del formulario se ve en su tarjeta, en “Leads → Formularios”), un mensaje de “gracias” y una validación propia. Primero HTML puro; las versiones de React y Vue llaman a crmLead() desde su propio manejador de envío.
<form id="quote" data-crm-lead="quote_request" data-crm-value="149900" data-crm-currency="EUR">
<label>Tu nombre <input name="name" autocomplete="name" required></label>
<label>Teléfono <input name="phone" type="tel" autocomplete="tel"></label>
<label>Email <input name="email" type="email" autocomplete="email"></label>
<label>¿Qué necesitas? <textarea name="message" rows="4"></textarea></label>
<!-- No es uno de los campos conocidos: aparece tal cual en la tarjeta del lead -->
<label>Tamaño del equipo
<select name="team_size">
<option>1–5</option>
<option>6–20</option>
<option>20+</option>
</select>
</label>
<button type="submit">Enviar solicitud</button>
<p class="form-status" role="status" hidden></p>
</form>
<script>
const form = document.getElementById('quote');
const status = form.querySelector('.form-status');
const button = form.querySelector('button');
function say(text) {
status.textContent = text;
status.hidden = false;
}
// 1. Antes de enviar: nuestra propia validación. preventDefault() = no se envía nada
form.addEventListener('crm:lead-before', (event) => {
const phone = form.elements.phone.value.trim();
const email = form.elements.email.value.trim();
if (!phone && !email) {
event.preventDefault();
say('Déjanos un teléfono o un email para poder responderte.');
return;
}
button.disabled = true;
});
// 2. Después de enviar: el widget no muestra nada, el "gracias" es cosa nuestra
form.addEventListener('crm:lead', (event) => {
button.disabled = false;
say(event.detail.ok
? '¡Gracias! Te responderemos en un día laborable.'
: 'Algo ha fallado. Inténtalo de nuevo o llámanos.');
});
</script>
<script src="https://widget.sitecog.com/widget.js" defer></script>'use client';
import { useState, type FormEvent } from 'react';
const EMPTY = { name: '', phone: '', email: '', message: '' };
export function QuoteForm() {
const [form, setForm] = useState(EMPTY);
const [status, setStatus] = useState<'idle' | 'sending' | 'done' | 'error'>('idle');
const set = (key: keyof typeof EMPTY) => (e: { target: { value: string } }) =>
setForm((prev) => ({ ...prev, [key]: e.target.value }));
async function onSubmit(e: FormEvent) {
e.preventDefault();
if (!form.phone.trim() && !form.email.trim()) {
setStatus('error');
return;
}
setStatus('sending');
// crmLead nunca lanza excepciones; solo es undefined si widget.js no está en la página
const res = await window.crmLead?.('quote_request', form, { value: 149900, currency: 'EUR' });
if (res?.ok) {
setForm(EMPTY);
setStatus('done');
} else {
setStatus('error');
}
}
if (status === 'done') return <p>¡Gracias! Te responderemos en un día laborable.</p>;
// Aquí no hay data-crm-lead: este formulario envía con crmLead por su cuenta
return (
<form onSubmit={onSubmit}>
<input value={form.name} onChange={set('name')} placeholder="Tu nombre" required />
<input value={form.phone} onChange={set('phone')} type="tel" placeholder="Teléfono" />
<input value={form.email} onChange={set('email')} type="email" placeholder="Email" />
<textarea value={form.message} onChange={set('message')} placeholder="¿Qué necesitas?" />
<button disabled={status === 'sending'}>Enviar solicitud</button>
{status === 'error' && <p role="alert">Déjanos un teléfono o un email y vuelve a intentarlo.</p>}
</form>
);
}<script setup lang="ts">
import { reactive, ref } from 'vue';
const empty = () => ({ name: '', phone: '', email: '', message: '' });
const form = reactive(empty());
const status = ref<'idle' | 'sending' | 'done' | 'error'>('idle');
async function submit() {
if (!form.phone.trim() && !form.email.trim()) {
status.value = 'error';
return;
}
status.value = 'sending';
// crmLead nunca lanza excepciones; solo es undefined si widget.js no está en la página
const res = await window.crmLead?.('quote_request', { ...form }, { value: 149900, currency: 'EUR' });
if (res?.ok) {
Object.assign(form, empty());
status.value = 'done';
} else {
status.value = 'error';
}
}
</script>
<template>
<p v-if="status === 'done'">¡Gracias! Te responderemos en un día laborable.</p>
<!-- Aquí no hay data-crm-lead: este formulario envía con crmLead por su cuenta -->
<form v-else @submit.prevent="submit">
<input v-model="form.name" placeholder="Tu nombre" required />
<input v-model="form.phone" type="tel" placeholder="Teléfono" />
<input v-model="form.email" type="email" placeholder="Email" />
<textarea v-model="form.message" placeholder="¿Qué necesitas?" />
<button :disabled="status === 'sending'">Enviar solicitud</button>
<p v-if="status === 'error'" role="alert">Déjanos un teléfono o un email y vuelve a intentarlo.</p>
</form>
</template>Qué pasa cuando se envía el formulario
- El widget cancela el envío nativo (con el botón, con la tecla Enter o con
form.requestSubmit()): la página no se recarga y elactiondel formulario no se usa. - Lanza
crm:lead-beforesobre el formulario. Si algún listener llama aevent.preventDefault(), la historia acaba aquí y no se envía nada. - Recoge los campos con
FormData, salvo los campos excluidos (contraseñas, datos de tarjeta y compañía). Solo cuentan los valores de texto: los campos de archivo se ignoran. Varios campos con el mismo nombre (un grupo de checkboxes) se unen con", ". El valor del botón pulsado no se envía: si lo necesitas, pásalo en un campo oculto. - Envía el lead, protegido con un pase de formulario de un solo uso (más sobre esto en protección contra spam). Si se vuelve a enviar el mismo formulario mientras el primer envío sigue en curso (un doble clic), ese segundo envío no sale.
- Cuando el envío termina (el servidor ha respondido o no se ha podido conectar), lanza
crm:leadcon{ ok: true }o{ ok: false }enevent.detail. - Si
okes true, llama aform.reset(). Si falla, el formulario se queda como está para que el visitante no pierda lo que ha escrito.
El widget no muestra ninguna interfaz propia: ni toast, ni spinner, ni “gracias”. Tu web, tu diseño, tus palabras: escucha crm:lead y enseña lo que quieras.
Atributos del formulario
| Atributo | Ejemplo | Qué hace |
|---|---|---|
data-crm-lead | "quote_request" | Convierte el formulario en un formulario de leads. Un atributo vacío es el formulario integrado lead_submit, que funciona sin configurar nada. Con valor, es el nombre de tu formulario de “Leads → Formularios”. |
data-crm-value | "149900" | Importe en unidades menores, un entero: 149900 son 1.499,00. Solo se guarda si el formulario tiene “Este formulario genera ingresos”. Si no es un número, no se envían ni el importe ni la moneda. |
data-crm-currency | "EUR" | Moneda del importe: EUR, USD, UAH…, de 1 a 10 letras latinas o dígitos. Si no la indicas, se usa la moneda del formulario. |
data-crm-ignore | sin valor | Va en un campo o en un contenedor (fieldset, div…), no en el propio formulario. Ese campo, o todo lo que haya dentro del contenedor, nunca se envía. No lo pongas en el formulario ni en uno de sus ancestros: entonces no se envía ningún campo. Mira Campos que nunca se envían. |
Eventos del formulario
Los dos eventos hacen bubbling, así que puedes escucharlos en el propio formulario o una sola vez en document para todos los formularios de la página.
| Evento | Cuándo | event.detail | Cancelable |
|---|---|---|---|
crm:lead-before | Justo después del submit, antes de enviar el lead | { name }: el nombre del formulario | Sí: preventDefault() detiene el envío |
crm:lead | Cuando el envío ha terminado: el servidor ha respondido o no se ha podido conectar | { ok }: true si el lead se ha aceptado | No |
document.addEventListener('crm:lead', (event) => {
if (event.detail.ok) {
event.target.closest('.modal')?.classList.add('is-thanks');
}
});Nombres de campo que entiende el CRM
Una tarjeta de lead tiene cuatro huecos principales: nombre, teléfono, email y mensaje. El servidor los rellena fijándose en los nombres de los campos. Los nombres se recortan y se pasan a minúsculas, y luego se comparan de forma exacta con esta lista (así que Phone funciona y your-phone no):
| Hueco | Nombres de campo que lo rellenan | Límite |
|---|---|---|
| Nombre | name, fio, username, user_name, fullname, full_name, firstname, first_name, contact_name, client_name, имя, фио, ім'я | 200 caracteres |
| Teléfono | phone, tel, telephone, mobile, phone_number, contact_phone, телефон, тел | 7–20 dígitos |
email, e_mail, e-mail, mail, contact_email, почта, пошта, емейл | 320 caracteres | |
| Mensaje | message, comment, comments, text, question, note, description, task, сообщение, комментарий, вопрос, повідомлення, коментар | 4000 caracteres |
- Gana el primer campo que encaja. Si un formulario tiene
phoneymobile, el hueco lo rellena el que aparezca primero. - Todo lo demás también se guarda. Los campos desconocidos y las segundas coincidencias van a “extra” y aparecen en la tarjeta del lead en el orden del formulario. Hasta 30 campos extra; claves de hasta 60 caracteres, valores de hasta 1000.
- Un teléfono solo cuenta con entre 7 y 20 dígitos. Espacios, paréntesis y guiones no molestan. Se guarda listo para marcar, solo con dígitos y el
+inicial:+49 30 1234567queda como+49301234567. - Un email solo cuenta si parece una dirección (
nombre@dominio.tld). Si no, el valor va a “extra”. - Teléfono o email, sí o sí. Un lead sin ninguno de los dos se rechaza con
no_contact: no habría forma de responder.
Campos que nunca se envían
Un formulario de leads no es sitio para contraseñas ni números de tarjeta, y el widget se encarga de que no acaben en el CRM aunque alguien los meta en el mismo <form> por despiste. Estos campos se saltan siempre:
- Los
<input type="password">, se llamen como se llamen. - Todo lo marcado con
data-crm-ignore: el atributo puede ir en el propio campo o en cualquier contenedor (fieldset,div…), y entonces se salta todo lo que haya dentro. - Los campos con un nombre sensible. El nombre se trocea en palabras (por
_,-,., camelCase…) y se excluye si alguna de ellas, como palabra suelta, escard,cc,csc,cvv,cvc,cvv2,cvc2,iban,ssn,secretopass. Además, basta con que el nombre, pegado sin separadores, contenga en cualquier sitiopassword,passwd,pwd,token,csrf,xsrf,creditcard,cardnumber,cardnum,ccnum,ccnumber,cvvocvc.
Unos ejemplos: card_number, cvv, csrf_token y user_password no se envían; acc_num tampoco, porque sin separadores queda accnum, que contiene ccnum. discard_reason sí se envía, porque ahí card no es una palabra suelta. Y si un campo con cierto nombre queda excluido, quedan excluidos todos los campos con ese mismo nombre.
Los campos ocultos (type="hidden") sí se envían, siempre que su nombre no sea sensible: son perfectos para pasar el producto, el plan o la página desde la que se escribió.
<form data-crm-lead="signup_request">
<input name="email" type="email"> <!-- ✓ se envía -->
<input name="plan" type="hidden" value="pro"> <!-- ✓ oculto, pero se envía -->
<input name="password" type="password"> <!-- ✗ type="password" -->
<input name="card_number"> <!-- ✗ nombre sensible -->
<fieldset data-crm-ignore> <!-- ✗ nada de lo que hay dentro -->
<input name="billing_address">
<input name="billing_zip">
</fieldset>
<button type="submit">Empezar</button>
</form>crmLead() aplica la misma regla de nombres a las claves de fields. Y el servidor vuelve a pasar el mismo filtro por su cuenta, también en los leads enviados desde tu servidor con clave secreta: un campo con nombre sensible nunca acaba en el CRM, venga de donde venga.
Opción B: envía leads desde JavaScript
Cuando el estado del formulario es tuyo (React, Vue, un asistente de varios pasos, un chatbot), llama al widget directamente. Las dos funciones aparecen en window en cuanto se carga widget.js (dentro de un iframe no existen). El widget pide el pase de formulario por su cuenta cuando el visitante toca por primera vez un campo de cualquier formulario de la página; así un lead enviado desde tu código no parece “rellenado en un segundo”.
crmLead(name, fields, options)
const { ok } = await window.crmLead(
'callback_request',
{ name: 'Anna', phone: '+49 30 1234567', message: 'Llamadme después de las 17:00, por favor' },
{ value: 149900, currency: 'EUR' },
);namestringobligatoriolead_submit para el integrado, o el de uno tuyo de “Leads → Formularios”. Letras latinas, dígitos y guiones bajos, empezando por una letra (^[A-Za-z][A-Za-z0-9_]*$). Un nombre que no encaja recibe un aviso en la consola y { ok: false }. El nombre de un evento de analítica también devuelve { ok: false }.fieldsobjectobligatoriopassword, card_number…) se descartan, igual que en los formularios.options.valueintegeropcional149900 = 1.499,00. Solo se guarda en formularios con “Este formulario genera ingresos”.options.currencystringopcionalEUR: de 1 a 10 letras latinas o dígitos. Si no la indicas, se usa la moneda del formulario.Cada llamada es un lead distinto con su propio pase: dos llamadas diferentes seguidas dan dos leads. La misma llamada con los mismos datos, mientras la primera sigue en camino y un par de segundos después (un doble clic), no se vuelve a enviar: devuelve la respuesta de la primera.
Devuelve una Promise que se resuelve en:
okbooleantrue: el lead se ha aceptado. false: se ha rechazado o no ha llegado; el motivo no se indica, a propósito (mira por qué).crmLeadForm(form, name)
Hace exactamente lo mismo que el atributo data-crm-lead, pero desde código. Viene bien cuando el formulario lo renderiza una librería de terceros y no puedes añadirle atributos, o cuando el nombre del formulario se decide en tiempo de ejecución. No devuelve nada; el resultado llega por el mismo evento crm:lead. Sin nombre, el formulario envía al integrado lead_submit. Volver a llamarla con un formulario que ya está vinculado no cambia nada.
const form = document.querySelector('#newsletter-popup form');
window.crmLeadForm(form, 'newsletter_signup');
form.addEventListener('crm:lead', (e) => {
if (e.detail.ok) form.innerHTML = '<p>¡Ya estás dentro! Revisa tu bandeja de entrada.</p>';
});formHTMLFormElementobligatorionamestringopcionalcrmLead. Si no lo pasas, se usa el integrado lead_submit.Declaraciones de TypeScript
El widget es un script normal, así que TypeScript no sabe nada de él. Pega esto en cualquier archivo .d.ts:
export {};
declare global {
interface Window {
crmLead?: (
name: string,
fields: Record<string, string>,
options?: { value?: number; currency?: string },
) => Promise<{ ok: boolean }>;
crmLeadForm?: (form: HTMLFormElement, name?: string) => void;
}
}Cómo funciona la protección contra spam
Un formulario público es un imán para bots. No necesitas un CAPTCHA para mantenerlos fuera: el widget y el servidor se encargan juntos, y los visitantes reales ni se enteran.
Un pase de formulario de un solo uso
Antes de enviar, el widget obtiene del servidor un “pase de formulario” firmado. Lo pide por adelantado: en cuanto el visitante toca por primera vez un campo de un formulario, de cualquier formulario de la página, incluido el que luego envíe el lead con crmLead. El tiempo que pasa desde ese primer contacto hasta el envío es el tiempo de relleno. Un pase es:
- de un solo uso: un pase, un lead; para el siguiente envío el widget pide uno nuevo;
- ligado a tu web: un pase de un sitio no sirve en otro;
- válido durante 24 horas: si la pestaña lleva abierta más tiempo, el widget pide uno nuevo.
Los bots que hacen POST a ciegas contra el endpoint no tienen pase y se rechazan. Repetir la petición con el mismo pase devuelve { ok: true }, pero el lead se guarda una sola vez. Y del doble clic en el botón se encarga el propio widget: mientras el primer envío está en curso, el segundo no sale.
El honeypot
Es el campo oculto company_site de antes. Una persona no lo ve, así que se queda vacío. Un bot que rellena todos los campos que encuentra se delata solo, y el lead se rechaza.
Leads “sospechosos”
Algunos leads tienen algo raro pero podrían ser reales. Esos se aceptan y reciben la etiqueta Sospechoso en el CRM, para que un gestor les eche un vistazo antes de llamar:
- entre el primer contacto con el formulario y el envío pasaron menos de 3 segundos, más rápido de lo humanamente posible;
- el formulario estuvo abierto más de 30 minutos antes de enviarse;
- llegaron más de 5 envíos desde una misma IP en una hora; cuentan todos, también los rechazados.
Un formulario enviado sin tocar ningún campo (autocompletar y “Enviar” al instante) también se marca como rápido: en ese caso el pase se pide en el momento del envío. Los leads enviados desde el servidor no reciben etiquetas.
La IP que ves en la tarjeta del lead está recortada (en IPv4 el último octeto pasa a cero: 203.0.113.57 → 203.0.113.0; en IPv6 se corta a /48). La dirección completa no llega a la base de datos; para los contadores de la protección contra spam se mantiene en la memoria del servidor una hora como máximo. Más en qué guardamos y durante cuánto.
“Spam” es un estado que una persona pone a mano en el CRM. Nada se marca como spam automáticamente, así que ningún cliente real acaba en la papelera sin que nadie se entere.
Por qué el navegador solo recibe ok: true o false
Decirle a un bot “rechazado: honeypot relleno” es darle una clase gratis de cómo colarse. Por eso el código de la página (crmLead() y el evento crm:lead) solo recibe ok: true u ok: false, sin motivo. ¿Depurando tu propio formulario? Tú sí ves el motivo: el CRM lo anota en “Últimos rechazos”, y los errores de configuración (un nombre no creado, un formulario que apunta a un evento de analítica, sin teléfono ni email) también se ven en la pestaña Network: una respuesta 400 con el campo message. Los rechazos de la protección (sin pase, honeypot relleno) llegan como un simple { "ok": false }. La lista de comprobación cubre el resto.
Por dentro: la petición del navegador
Para curiosos: nunca tendrás que montarla tú. El widget obtiene un pase de POST https://back.sitecog.com/marketing/fk (respuesta: {"pass":"…"}) y luego envía el lead:
POST https://back.sitecog.com/marketing/f
Content-Type: application/json
{
"n": "contact_form",
"pass": "…",
"fields": {
"name": "Anna",
"email": "anna@example.com",
"message": "Hi!",
"company_site": ""
},
"val": 149900,
"cur": "EUR",
"u": "https://shop.example/contacts",
"vid": "…",
"sid": "…"
}Respuestas: { "ok": true }, el lead se ha aceptado (o es una repetición con el mismo pase); { "ok": false }, rechazo al comprobar el pase o el honeypot; los errores del propio lead llegan como 400 con el campo message (mira errores). Si la recepción de leads no está configurada en el servidor, /fk responde { "pass": null, "reason": "not_configured" }. vid y sid son los ids del visitante y de la sesión, para que el lead quede vinculado al canal publicitario por el que llegó el visitante: mira Eventos y analítica.
Envía leads desde tu servidor
No todos los leads nacen en un navegador. Usa la vía del servidor cuando:
- un gestor toma un pedido por teléfono y lo mete en tu back office;
- tu formulario se procesa en el backend (un handler en PHP, una server action de Next.js) y prefieres no depender del widget;
- los leads llegan de otro sistema: un marketplace, un servicio de reservas, un bot.
POST https://back.sitecog.com/marketing/event
x-event-key: sk_…
Content-Type: application/jsonEs la misma dirección que la de los eventos de servidor: Sitecog decide por el nombre qué le ha llegado. El nombre de un formulario de leads crea un lead; el de un evento de analítica, un evento. Pero si la petición trae campos de formulario (fields) y el nombre es de un evento de analítica, es un error y no un evento: 400 not_lead_form. La dirección anterior, https://back.sitecog.com/marketing/lead, sigue funcionando, pero solo acepta formularios de leads.
Claves secretas
La vía del servidor se autentica con una clave secreta. Puedes emitirla en dos sitios, y la lista es la misma para todo el sitio: CRM → Leads → Formularios, pestaña “Desde un servidor” de cualquier formulario, o CRM → Marketing → Eventos, panel “Claves secretas”. Escribe un nombre y pulsa “Emitir una clave”. Una clave tiene la forma sk_ + 48 caracteres hexadecimales; un sitio puede tener hasta 5 claves activas y cualquiera de ellas se puede revocar. Ponle a cada clave un nombre que diga dónde vive (“servidor de pagos”, “pedidos por teléfono”): tu yo del futuro te lo agradecerá cuando toque revocar una.
Ven y emiten claves el propietario y cualquier gestor que pueda editar Leads (o Marketing → Eventos). Quien solo puede ver la sección no verá las claves.
Ejemplo de petición
curl https://back.sitecog.com/marketing/event \
-H "x-event-key: sk_3f9a1c7e5b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d" \
-H "Content-Type: application/json" \
-d '{
"name": "phone_order",
"event_id": "order-1024",
"fields": {
"name": "Anna Schmidt",
"phone": "+49 30 1234567",
"message": "Two pairs of Air 3, graphite. Delivery to the office."
},
"value": 149900,
"currency": "EUR",
"url": "https://shop.example/contacts"
}'// Node 18+: fetch viene de serie
const res = await fetch('https://back.sitecog.com/marketing/event', {
method: 'POST',
headers: {
'x-event-key': process.env.CRM_EVENT_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'phone_order',
event_id: `order-${order.id}`, // un reintento no creará un segundo lead
visitor_id: order.crmVid, // guardado desde el navegador al pagar, si lo tienes
session_id: order.crmSid,
fields: {
name: order.customerName,
phone: order.phone,
message: order.comment,
delivery: order.deliveryMethod, // va a "extra"
},
value: order.totalCents, // 149900 = 1.499,00
currency: 'EUR',
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`CRM lead: ${res.status} ${data.message}`);
// data → { ok: true, duplicate: false, lead: true }import os
import requests
res = requests.post(
"https://back.sitecog.com/marketing/event",
headers={"x-event-key": os.environ["CRM_EVENT_KEY"]},
json={
"name": "phone_order",
"event_id": "order-1024",
"fields": {
"name": "Anna Schmidt",
"phone": "+49 30 1234567",
"message": "Two pairs of Air 3, graphite.",
},
"value": 149900,
"currency": "EUR",
},
timeout=10,
)
res.raise_for_status()
print(res.json()) # {'ok': True, 'duplicate': False, 'lead': True}Cuerpo de la petición
x-event-keyheaderstringobligatoriosk_… del CRM. Si falta, está revocada o el sitio está desactivado → 401 invalid_key.namestringobligatoriolead_submit para el integrado, o el de uno tuyo de “Leads → Formularios”. Alias corto: n.fieldsobjectobligatoriofields: entonces cuenta como campo del lead todo lo que no sea una de las claves de servicio de esta tabla. Eso sí, el nombre de la persona en la raíz va como full_name o fio, porque ahí name es el nombre del formulario. Los campos con nombre sensible el servidor los descarta también aquí, aunque la petición venga con clave secreta.event_idstring | numberopcionalid.visitor_idstringopcionalsession_idstringopcionalcrm_sid). Con él, el lead hereda el canal publicitario y las etiquetas UTM de esa sesión. Alias: sid.valueintegeropcional149900 = 1.499,00. Solo se guarda en formularios con “Este formulario genera ingresos”. Alias: val.currencystringopcionalEUR: de 1 a 10 letras latinas o dígitos. Si no la pasas, se usa la moneda del formulario. Alias: cur.urlstringopcionalu.Respuesta
{ "ok": true, "duplicate": false, "lead": true }okbooleanduplicatebooleantrue si este formulario ya tiene un lead con este event_id. No se ha guardado nada nuevo, y no pasa nada.leadbooleantrue: la petición se ha aceptado como lead. La dirección es la misma que la de los eventos de analítica, y la respuesta a un evento no trae este campo. ¿Has enviado un lead y no ha llegado lead? El nombre es de un evento de analítica: no habrá tarjeta.A diferencia del navegador, la vía del servidor no usa pases de formulario ni comprobaciones de tiempo: la clave secreta ya es prueba suficiente. El honeypot sigue valiendo: un company_site no vacío en fields recibe 400 rejected. Y el filtro de nombres sensibles también: aunque la petición venga firmada con tu clave, un campo como card_number o user_password no se guarda.
Idempotencia: reintenta sin miedo
Las redes fallan en el peor momento. ¿La petición llegó o no? Con event_id no necesitas saberlo: vuelve a enviarla. Una repetición devuelve {"ok":true,"duplicate":true} y el lead no se guarda dos veces.
{ "ok": true, "duplicate": true, "lead": true }Atribución: qué anuncio trajo el lead
Los leads del widget se vinculan al visitante automáticamente. Un lead del servidor no sabe nada del navegador, a menos que se lo cuentes. El widget guarda el id del visitante en localStorage con la clave crm_vid y el id de sesión con crm_sid. Envíalos a tu backend junto con el formulario o el pedido, y pásalos después. Léelos solo cuando el visitante haya aceptado la analítica, y dentro de un try/catch: el almacenamiento del navegador puede estar bloqueado, y entonces acceder a él lanza una excepción.
let crm = {};
try {
// Sin el modo de consentimiento, status() siempre es 'granted'
if (window.crmConsent?.status() === 'granted') {
crm = {
vid: localStorage.getItem('crm_vid'),
sid: localStorage.getItem('crm_sid'),
};
}
} catch {
// almacenamiento no disponible: el lead se envía sin atribución
}
await fetch('/api/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ ...order, crm }),
});
// …y en el servidor: visitor_id: body.crm.vid, session_id: body.crm.sidCon session_id, el lead hereda el canal publicitario, el enlace publicitario y las etiquetas UTM de la primera visita de esa sesión: los verás en la tarjeta del lead, en el bloque “Origen”. Más en Eventos y analítica.
Errores
Desde el navegador, crmLead() y el evento crm:lead solo dicen ok: false. La vía del servidor responde con un estado y un message:
| Estado | Cuerpo | Qué ha pasado |
|---|---|---|
| 400 | {"message":"unknown_event","name":"phone_order"} | No hay ningún formulario con este nombre en el CRM. Créalo en “Leads → Formularios” (revisa la ortografía y las mayúsculas) o restáuralo desde el archivo. |
| 400 | {"message":"not_lead_form","name":"purchase"} | Un lead (con campos de formulario en fields o enviado a la dirección anterior /lead) se ha enviado con el nombre de un evento de analítica. Crea un formulario de leads con otro nombre. |
| 400 | {"message":"invalid_event_name"} | Falta el nombre, o tiene caracteres que no son letras latinas, dígitos o guiones bajos, o no empieza por una letra. |
| 400 | {"message":"no_contact"} | No hay ni teléfono (7–20 dígitos) ni un email que parezca una dirección. |
| 400 | {"message":"invalid_body"} | El cuerpo no es un objeto JSON, o la petición no lleva el Content-Type adecuado (hace falta application/json). Un JSON roto recibe un 400 con el texto del error de análisis. |
| 400 | {"message":"rejected"} | El campo honeypot company_site está relleno. |
| 401 | {"message":"invalid_key"} | x-event-key falta, está mal formada o revocada, o el sitio está desactivado. |
| 413 | — | El cuerpo pesa más de 8 KB. |
| 429 | {"message":"rate_limit_exceeded"} | Demasiadas peticiones en este minuto. Espera al siguiente. |
Las peticiones del navegador también pueden recibir 400 unknown_domain (el dominio de la página no está añadido al CRM como sitio o está desactivado) y 400 unknown_origin (la petición no lleva ni Origin ni Referer, por ejemplo porque la página se ha abierto directamente desde un archivo). Los verás en la pestaña Network, mientras el código sigue recibiendo ok: false.
Límites
| Qué | Límite |
|---|---|
| Peticiones por IP (todas las rutas de marketing juntas) | 120 por minuto |
| Peticiones por sitio | 6000 por minuto |
| Pases de formulario por IP | 20 por minuto |
| Cuerpo de la petición | 8 KB |
| Nombre / email / mensaje | 200 / 320 / 4000 caracteres |
| Campos extra | hasta 30; clave de hasta 60 y valor de hasta 1000 caracteres |
| Teléfono | 7–20 dígitos para contar como contacto |
event_id | hasta 128 caracteres (si es más largo, se recorta) |
| Claves secretas | hasta 5 activas por sitio |
Las ventanas son minutos fijos: tras un 429, espera a que empiece el minuto siguiente. Un visitante real nunca se acercará; un script aporreando tu formulario, sí.
Solución de problemas
Últimos rechazos
El primer sitio donde mirar. Al final de la página CRM → Leads → Formularios están los envíos de tu web que no se convirtieron en leads, cada uno con su motivo: cuándo, desde dónde (navegador o servidor), con qué nombre y desde qué página.
| Motivo | Qué hacer |
|---|---|
| El nombre no está en el CRM | Créalo con el botón “Crear el formulario «nombre»” de la propia entrada (lo ve quien puede editar Leads). Si el nombre está archivado, la entrada te lo dirá: restaura el formulario desde el archivo (marca “Mostrar archivo” encima de la lista). |
| Enviado a un evento de analítica | Ese nombre ya lo usa un evento de “Marketing → Eventos”. Crea un formulario de leads con otro nombre y ponlo en tu web. |
Enviado con crmTrack | crmTrack solo registra eventos de analítica. Para un formulario, usa el atributo data-crm-lead o crmLead(). |
| Sin teléfono ni email | Revisa los nombres de los campos con la tabla. |
| Nombre no válido | Solo letras latinas, dígitos y guiones bajos, empezando por una letra. |
| Ha saltado el honeypot | El campo oculto company_site venía relleno: así envían los bots. Si es un campo real tuyo, cámbiale el nombre. |
Se guardan los últimos 50 rechazos del sitio, compartidos entre formularios y eventos; la lista desaparece 7 días después del último rechazo. El mismo rechazo (mismo motivo, mismo nombre y mismo origen: navegador o servidor) se anota como mucho una vez por minuto. Los leads rechazados en sí (teléfono, email, texto) no se guardan: solo queda el rastro. Las peticiones que se saltan el widget (sin pase de formulario) no aparecen aquí, salvo que traigan el honeypot relleno: no es un fallo de tu formulario, sino un bot que se ha quedado fuera. Los rechazos de eventos de analítica tienen su propia página: Marketing → Eventos.
El lead no ha llegado
Mira primero en “Últimos rechazos”. Si ahí no hay nada, repasa la lista:
- El nombre no está declarado. En “Leads → Formularios” tiene que haber un formulario con exactamente este nombre, mayúsculas incluidas. Un
data-crm-leadvacío es el integradolead_submit: se crea automáticamente, pero solo en los planes con leads, y si está archivado no vuelve del archivo por sí solo. - El nombre es de un evento de analítica. Con ese nombre no se acepta ningún lead: crea un formulario con otro nombre.
- Se envió con
crmTrack.crmTrackno crea leads: necesitas el atributodata-crm-leadocrmLead(). - Ni teléfono ni email. O están, pero con nombres que el CRM no conoce (
your-phone,contact[email]) y han acabado en “extra”. Renómbralos: mira la tabla de campos. Un teléfono con menos de 7 dígitos tampoco cuenta. - Los datos estaban en un campo de archivo. Los archivos se ignoran: el widget solo envía texto.
- Un campo real se llama
company_site. Es el nombre del honeypot; el lead se trata como un bot. - Tu propio listener de
crm:lead-beforeha llamado apreventDefault(), quizá cuando no te lo esperabas. - El widget no está en esta página. Sin
widget.jsel atributo no hace nada y el formulario se envía a la antigua (o no se envía). - El formulario está en un iframe, el atributo se añadió después o se envía con
form.submit(). En esos casos el widget no intercepta el formulario: mira dónde no funciona el atributo. data-crm-ignoreestá en el propio formulario o en un contenedor suyo. Entonces no se envía ningún campo, y el lead se rechaza por “sin teléfono ni email”.- Lo bloquea una Content Security Policy. Si tu web tiene CSP, necesita
script-src https://widget.sitecog.comyconnect-src https://back.sitecog.com. La consola del navegador te lo dirá en rojo. - El dominio no es un sitio del CRM. El sitio se reconoce por el origen exacto de la página (se quita el
www.): un subdominio comoshop.example.comes un sitio aparte. Probar enlocalhosto en un dominio de staging que no está añadido al CRM daunknown_domainen la pestaña Network. ¿Acabas de añadir el dominio? Espera hasta 5 minutos. - Has hecho muchas pruebas. 20 pases de formulario por minuto y por IP sobran para personas, pero no para clics frenéticos. Espera un minuto.
Ha llegado el lead, pero falta un campo
- El nombre del campo parece sensible. Repasa la regla de nombres: un
promo_passse descarta porquepasses una palabra suelta. Renómbralo (promo_code) y listo. - El campo, o algo que lo envuelve, lleva
data-crm-ignore. Suele pasar con unfieldseto undivheredado de otra parte del formulario. - Es un
type="password": esos no se envían nunca. - Es un campo de archivo. Los archivos se ignoran de todas formas: el widget solo envía texto.
No se muestra el importe
El importe se ve como total de los últimos 30 días en la tarjeta del formulario, en Leads → Formularios; en la tarjeta del lead no aparece. Si ahí tampoco hay nada, marca “Este formulario genera ingresos” en el formulario (icono “Editar” del formulario): los importes se guardan en los leads que lleguen a partir de ese momento. Comprueba también que el importe es un entero en unidades menores: 1499.00 se envía como 149900.
Notificaciones en Telegram
Un lead que nadie ve es un lead perdido. Conecta tu propio bot de Telegram y el aviso de cada lead nuevo te llegará en menos de medio minuto, con un enlace a su tarjeta:
Crea el bot y pega el token
Los bots se crean con@BotFather. En el CRM: Leads → “Ajustes de leads” (en la cabecera de la sección), campo “Token del bot”, botón “Conectar”. Hay un bot por sitio: a través de él reciben los avisos todos los gestores que elijas.Reúne a los destinatarios
Cada persona que deba recibir leads le escribe/startal bot (también puedes añadir el bot a un grupo de trabajo). Después pulsa “Actualizar” en el bloque “Quién los recibe” y activa a quien corresponda: los nuevos aparecen desactivados. Sin este paso no llega nada.Activa los avisos y compruébalo
Marca “Enviar notificaciones” y, si quieres, “Enviar también los sospechosos”; guarda y pulsa “Probar conexión”: el CRM te dirá a cuántos destinatarios ha llegado el mensaje de prueba.
- Las horas de silencio aplazan los avisos, no los descartan: un lead de madrugada te llega a primera hora de la mañana. La franja es común para todo el sitio, pero cada destinatario puede tener la suya propia o no tener ninguna.
- Los leads sospechosos, con la casilla desmarcada, no se envían nunca: ni al momento ni por la mañana. En el CRM siguen estando.
- Si el bot tiene un webhook, la lista de destinatarios no se puede reunir: quita el webhook o crea un bot aparte para los leads.
Las notificaciones usan formato HTML, y todo lo que escribió el visitante se escapa antes de llegar ahí. Un “nombre” como <a href="…">Haz clic aquí</a> llega como texto plano: un visitante no puede disfrazar un enlace de texto ni romper el formato. Una dirección escrita tal cual en un campo sí la mostrará Telegram como enlace. Los campos largos se recortan (el mensaje a 500 caracteres, los demás a 200); el lead completo siempre está en el CRM.
Eliminar los datos de una persona a petición suya
“Por favor, borren todo lo que tengan sobre mí” es una petición normal, y atenderla no debería suponer una semana excavando en tablas. El CRM tiene dos herramientas para ello, sin código por tu parte.
Desde un lead o un chat
La ficha de un lead y la de un chat tienen “Eliminar los datos del visitante”. Antes de borrar nada, el CRM muestra exactamente qué se va a eliminar:
- el perfil del visitante y la analítica: visitas a páginas y eventos;
- chats y adjuntos: el número de chats, mensajes y archivos;
- leads: solo si marcas “Eliminar también las solicitudes de este visitante”. Desactivado por defecto: un lead suele ser un negocio en curso, y la decisión es tuya.
Un lead sin visitor_id (enviado desde tu servidor sin él, o desde el navegador antes de que el visitante diera su consentimiento en el modo de consentimiento) no está vinculado a ningún visitante, así que ahí solo se puede eliminar el propio lead.
Por correo o teléfono
Normalmente la petición llega por correo: “Soy anna@example.com, olvídenme”. Ve a CRM → Ajustes → “Solicitudes de eliminación de datos”, introduce el correo o el teléfono que dio la persona y el CRM encontrará sus leads y sus chats (por correo o por teléfono) y su cuenta en tu web (solo por correo). El botón “Eliminar todo lo encontrado” lo borra todo de una vez.
- Estadísticas de visitas. La casilla “Eliminar también las estadísticas de visitas de los visitantes relacionados” está marcada por defecto: desmárcala si necesitas conservar las estadísticas.
- Los chats se eliminan enteros. De los visitantes encontrados se borran todos sus chats, también los archivados, con sus adjuntos. Los archivos insertados en las páginas del sitio se quedan.
- Permisos. Para eliminar hace falta el permiso de editar la sección correspondiente: los leads, “Leads”; los chats, “Chats”; las cuentas, “Usuarios del sitio”; las estadísticas, “Tráfico”. Un gestor que solo puede ver ve lo encontrado, pero no puede borrarlo.
- Registro de actividad. Cada eliminación queda en el registro de actividad, sin el correo ni el teléfono de la persona: si no, el registro guardaría justo lo que se pidió olvidar.
- Sin deshacer. Eliminado es eliminado. Revisa las cifras antes de confirmar.