Cuando alguien envía el formulario de contacto de roxex.es pasan cuatro cosas: el servidor valida lo que llega, lo guarda en nuestra base de datos, manda un acuse de recibo a quien escribió y nos avisa por Telegram de que hay un mensaje nuevo. Este build log cuenta cómo está hecho cada paso, leyendo el código del repositorio, y sobre todo dos decisiones: el aviso de Telegram no lleva ningún dato de la persona y cada aviso deja registrado si llegó o no, algo que vemos en el panel interno.
Todo lo que sigue sale de cuatro sitios del repositorio: functions/api/contact.ts (el formulario de contacto), functions/api/lead.ts (altas a recursos y newsletter), functions/_lib/ (origen, límites y avisos) y schema/ (las tablas de la base de datos). No damos volúmenes de mensajes ni tiempos de llegada de los avisos: no los hemos medido para publicarlos.
El recorrido completo
Este es el orden en el que trabaja POST /api/contact:
- 1.Comprueba que el cuerpo es JSON y que la petición viene de nuestro propio origen.
- 2.Comprueba el tamaño del cuerpo y que sea un objeto JSON.
- 3.Mira el campo trampa (honeypot). Si está relleno, finge éxito y no hace nada más.
- 4.Aplica el límite de envíos por IP.
- 5.Valida campo a campo.
- 6.Guarda el lead y el mensaje en D1, en una transacción.
- 7.Envía el acuse de recibo, si el correo está configurado.
- 8.Lanza el aviso en segundo plano (
waitUntil), sin retrasar la respuesta: abre un registro del aviso, avisa por Telegram (y por n8n, si está configurado) y guarda el resultado. - 9.Responde al navegador.
El orden es la decisión de diseño más importante: todo lo que puede rechazar la petición va antes de tocar la base de datos, y todo lo que depende de un tercero va después de guardar. Así, un fallo de Telegram no puede hacer perder un mensaje, y un mensaje que no se ha guardado no puede generar un aviso.
Antes de guardar: origen, tamaño, trampa y límite
Solo JSON y solo desde nuestro origen
Lo hace functions/_lib/origin.ts, y su comentario explica el motivo. Un formulario HTML de otra web puede hacer un POST a nuestra API sin la comprobación previa del navegador (el preflight de CORS) si usa los tipos text/plain o application/x-www-form-urlencoded, y un cuerpo text/plain puede ser JSON válido. Exigir application/json obliga al navegador a pedir ese permiso previo, que no concedemos; si el tipo es otro, la función responde 415.
Después mira la cabecera Origin. Se aceptan el origen de la propia petición, el dominio canónico con y sin www y el de la variable PUBLIC_SITE_URL; cualquier otro recibe un 403. Si no hay cabecera Origin pero el navegador manda Sec-Fetch-Site: cross-site, también 403. Sin ninguna de las dos (curl, scripts, monitores) no hay un navegador ajeno del que abusar, y esos clientes quedan cubiertos por el límite por IP.
Tamaño y forma
El cuerpo no puede pasar de 32 KB: se comprueba con la cabecera Content-Length y otra vez al leer el texto (32.768 caracteres), porque esa cabecera la escribe el cliente. Si lo que llega no es un objeto JSON, la respuesta es 400.
El campo trampa
El formulario lleva un campo que una persona no ve ni rellena. Si llega con texto, la función responde { ok: true } sin guardar ni avisar: al bot le parece que ha funcionado y no aprende nada.
Límite por IP
functions/_lib/rate-limit.ts cuenta peticiones en la tabla rate_limits de D1, con una clave por ámbito, IP y ventana fija de un minuto. El formulario de contacto admite 5 envíos por minuto e IP y el de altas a recursos, 10. Por encima, la respuesta es 429 y el formulario pide esperar un minuto. En una pequeña parte de las peticiones, elegidas al azar, se borran además las filas caducadas.
Hay una decisión escrita en el código que conviene conocer: si D1 falla al contar, el límite deja pasar la petición, porque una caída del contador no debe bloquear el formulario. En la práctica, si D1 no responde, el siguiente paso, guardar, también fallará y la función devolverá 503.
Validación: las mismas reglas en el navegador y en el servidor
Los límites viven en un solo sitio, src/app/contact/contact-options.ts, y los usan tanto el formulario como la función: nombre hasta 120 caracteres, email hasta 254 y con la misma expresión regular que usan los formularios públicos y el envío de emails del panel, empresa hasta 120, teléfono hasta 40 (si es más largo, se recorta a 40 en lugar de dar error), mensaje entre 10 y 4.000, y un enlace opcional a una especificación o un repositorio de hasta 500 caracteres, solo https y sin usuario ni contraseña en la URL. El servicio, el presupuesto y el plazo tienen que ser identificadores de listas conocidas. Si algo falla, la respuesta es un 400 con un objeto fields que dice qué campo y por qué, y el formulario marca cada uno.
Un detalle menos visible: en los campos de una línea (nombre, empresa, teléfono) los caracteres de control, saltos de línea incluidos, se cambian por un espacio:
tsconst line = (v: unknown): string => str(v).replace(CONTROL_CHARS, " ").replace(/ {2,}/g, " ").trim();
El motivo está en el comentario de al lado: la actividad del CRM es texto por líneas («Servicio: …», «Presupuesto: …»). Sin esa limpieza, un POST hecho a mano podría meter en el nombre una línea falsa de presupuesto.
Guardar en D1, o no decir que se ha enviado
Se escriben dos tablas a la vez. leads tiene una fila por email (la columna es única) y activities es el historial de cada lead, donde queda el mensaje con su cualificación. Las dos escrituras van en un batch de D1, que se ejecuta como una transacción: o se guardan las dos o ninguna.
tsif (!ctx.env.DB) return json({ ok: false, error: "storage_unavailable" }, 503); try { await saveContact(ctx.env.DB, contact, ip); } catch { // Sin escritura en D1 no hay {ok:true}: el cliente ofrece WhatsApp y email. return json({ ok: false, error: "storage_failed" }, 503); }
En el navegador, cualquier otra respuesta de error (salvo la validación por campo, un 400 que solo marca los campos) muestra que el mensaje no se ha guardado, deja el texto en el formulario y ofrece WhatsApp y email. No fingimos que el mensaje se entregó.
El endpoint es anónimo: nadie demuestra que el email que escribe es suyo. Por eso, si el lead ya existe, la función no sobrescribe lo que ya estaba guardado (nombre, empresa, teléfono), solo rellena los huecos vacíos, y no toca el consentimiento ni una baja previa; el mensaje queda en la actividad. El consentimiento para comunicaciones comerciales se registra solo al crear un lead nuevo, y el texto que se guarda como prueba es el del servidor (src/lib/consent.ts), no el que mande el navegador. La ruta de altas a recursos y newsletter sigue la misma regla de «sin escritura no hay éxito» y además nunca deshace una baja.
Por encima de todas las funciones de /api/* hay un middleware (functions/api/_middleware.ts). Si un error se escapa de un handler, responde 500 { ok: false, error: "internal" } en JSON y deja en el log el método, la ruta y el mensaje, sin cuerpo ni cabeceras. También añade cabeceras de seguridad a las respuestas de la API, que no reciben las del sitio estático.
El acuse de recibo
Si el correo transaccional está configurado (Resend), la persona recibe un acuse. No incluye nada de lo que escribió, ni su nombre ni su mensaje: así el formulario no sirve para enviar texto arbitrario a terceros desde nuestro dominio. Sale como mucho uno por email cada 24 horas, hay un tope global de acuses por día y, si D1 no puede confirmar alguna de esas dos cosas, no se envía. La respuesta al navegador lleva ack: true o false según si el proveedor lo aceptó.
El aviso de Telegram: tipo y referencia, nada más
El aviso que nos llega tiene esta forma (el número de referencia es de ejemplo):
textNuevo mensaje de contacto · ref. 42 Detalles en el panel: https://roxex.es/admin
No lleva el nombre, el email, el teléfono, la empresa, el mensaje, los enlaces ni el presupuesto. La función que lo construye, minimalTelegramText en functions/_lib/notify.ts, solo recibe el tipo de alta, la referencia y la URL del sitio. La referencia es el identificador de la fila del aviso en lead_notifications, así que con ella encontramos el mensaje en el panel.
Por qué lo hicimos así:
- •Minimización. Telegram es un tercero que trata datos fuera de la UE, como dice la información de privacidad del propio formulario y nuestra política de privacidad. El aviso solo tiene que decirnos que abramos el panel; para eso no necesita ningún dato de nadie.
- •Nada escrito por el visitante llega al chat. El mensaje se envía como texto plano y no contiene ningún carácter que haya escrito otra persona, así que el formulario no sirve para colar contenido en nuestro chat.
- •Lo que se ve en la pantalla de un móvil no dice nada de nadie. Una notificación puede verse con el teléfono bloqueado; con este formato, solo dice que hay un mensaje.
El código tiene un segundo canal opcional: un evento a n8n, la herramienta de automatización que, según nuestra política de privacidad, corre en un servidor que gestionamos nosotros. En los mensajes de contacto, el evento lleva solo la cualificación (servicio, presupuesto, plazo, las casillas marcadas, si hay enlace y si se envió el acuse) y la misma referencia, nunca nombre, email, teléfono, empresa ni mensaje. En las altas a recursos y newsletter sí lleva el email, el formulario de origen, el recurso y el consentimiento. Si la variable del webhook no está configurada, el canal queda apagado y no pasa nada más.
Saber si el aviso llegó: la tabla lead_notifications
Un aviso que se manda y se olvida falla en silencio: un token caducado o un chat equivocado y dejas de enterarte de los mensajes sin que nada lo diga. Por eso cada envío del formulario abre una fila en esta tabla (schema/0014_notifications.sql) antes de avisar:
sqlCREATE TABLE IF NOT EXISTS lead_notifications ( id INTEGER PRIMARY KEY AUTOINCREMENT, email TEXT NOT NULL, kind TEXT NOT NULL, -- contacto | lead created_at TEXT NOT NULL DEFAULT (datetime('now')), notified_at TEXT, notify_error TEXT, channels TEXT );
El email se queda en D1 para cruzar el aviso con su lead en el panel; no viaja a Telegram. Los dos canales se intentan en paralelo y, al terminar, se cierra la fila:
- •
notified_atse rellena si al menos un canal confirmó la entrega. - •
notify_errorguarda qué falló, por canal (por ejemplo, el código HTTP y la descripción que devuelve Telegram). Puede tener valor aunquenotified_attambién lo tenga: es un fallo parcial. - •
channelsresume el estado de cada canal, del tipotelegram=ok n8n=off.
Qué cuenta como «entregado» está en el código. Para Telegram no basta con un HTTP 2xx: la respuesta de su API es un objeto JSON con un campo booleano ok y, si hay error, una description. El aviso solo se da por entregado con las dos cosas:
tsif (res.ok && payload.ok === true) return { ok: true };
Para n8n basta con un HTTP 2xx. Cada intento tiene 5 segundos como máximo, y los fallos que pueden ser pasajeros (error de red, tiempo agotado, 429 o 5xx) se reintentan una vez tras una pausa corta. Lo que se guarda no lleva secretos: de Telegram, el código y su descripción, con el token tachado si apareciera; de n8n, solo el código HTTP, porque su cuerpo podría devolver datos del flujo. Los errores se recortan antes de guardarse.
Toda la función notifyNewLead está envuelta para no lanzar nunca: corre en segundo plano (waitUntil), sin retrasar la respuesta, y un fallo ahí no puede cambiar la respuesta «guardado». Si la tabla todavía no existe en la base de datos (una migración sin aplicar), el aviso se envía igual y solo se pierde el registro.
Lo que se ve en el panel
El listado del CRM (GET /api/admin/leads, que exige sesión con rol de lectura como mínimo) añade dos cosas a partir de esa tabla:
- •Un contador de avisos sin confirmar de los últimos 30 días, separado en fallidos (hay resultado guardado y ningún canal confirmó, o no hay ningún canal configurado) y sin resultado (el proceso se cortó antes de saberlo), con una lista de los más recientes. No filtra por el estado del lead: un cliente que vuelve a escribir no reinicia su estado, y un filtro por «nuevo» escondería justo esos mensajes.
- •El estado del último aviso de cada lead: «Confirmado», «Fallo parcial», «Fallido» o «Sin resultado», con cuántos avisos tiene sin confirmar.
Al borrar un lead desde el panel se borran también sus filas de avisos, y las respuestas de la API del panel no se guardan en caché.
Qué pasa cuando algo falla
| Qué falla | Qué responde el formulario | Qué queda |
|---|---|---|
| D1 no configurada | 503 storage_unavailable | Nada guardado; el formulario ofrece WhatsApp y email |
| La escritura en D1 falla | 503 storage_failed | Lo mismo |
| Límite por IP superado | 429 | Nada guardado; mensaje para esperar un minuto |
| Telegram falla o no responde | 200: el mensaje ya está guardado | Fila con notify_error; el panel la cuenta |
| Ningún canal de aviso configurado | 200 | Fila marcada como «ningún canal configurado», sin notified_at |
| El acuse de recibo falla | 200 con ack: false | Log con solo el código de error |
Falta la tabla lead_notifications | 200 | El aviso sale; no queda registro |
| Error no previsto en una función | 500 internal | Log con método, ruta y mensaje |
Dos límites que conviene decir. No hay reenvío automático: tras el único reintento, un aviso que no llegó se queda pendiente en el panel hasta que alguien lo mire. Y si la ejecución se corta antes de cerrar la fila, esta queda como «Sin resultado», sin saber si el aviso salió.
Qué haríamos distinto para un cliente
Esto está hecho para una web con un solo destinatario de avisos. En un proyecto de cliente valoraríamos, según el caso, estas opciones; ninguna es un compromiso cerrado:
- •El canal de aviso. Email, Slack, Teams o ninguno externo. El patrón (aviso mínimo con referencia y registro de entrega) se mantiene; cambia dónde trabaja el equipo y qué permite su política de datos.
- •Reenvío de avisos pendientes. Una cola o una tarea programada que reintente lo que quedó sin confirmar, si el volumen o la urgencia lo justifican. Nosotros nos apoyamos en revisar el panel.
- •El CRM. Si ya existe uno, escribir en él por API en lugar de en D1. La regla sería la misma: sin escritura confirmada, no hay mensaje de éxito.
- •Antispam. Un desafío como Cloudflare Turnstile si el campo trampa y el límite por IP no bastan. Hoy no lo usamos.
- •Conservación. Decidir cuánto tiempo se guardan los registros de avisos. Hoy salen de la lista del panel a los 30 días y se borran con el lead.
- •Doble confirmación en la newsletter. Nuestro flujo registra el consentimiento con su texto y su fecha, pero no pide confirmar el email.
Si quieres un flujo así en tu negocio, es parte de lo que hacemos en automatización de procesos, y en cómo trabajamos está el orden de las fases. Para el lado de diseño y conversión del formulario, mira la guía de formularios web que convierten; para la arquitectura completa de esta web, el caso de estudio de roxex.es.
Preguntas frecuentes
¿Por qué el aviso de Telegram no lleva el mensaje completo? Porque Telegram es un tercero que trata datos fuera de la UE y el aviso solo tiene que decirnos que abramos el panel. El nombre, el email y el mensaje se quedan en nuestra base de datos y se leen en el panel, con sesión.
¿Qué pasa si Telegram está caído cuando alguien escribe? El mensaje ya está guardado antes de avisar, así que la persona recibe la confirmación igual. El aviso se reintenta una vez y, si no llega, queda marcado como fallido en el panel con el motivo.
¿Hace falta n8n para esto? No. El aviso de Telegram sale directamente desde la función de Cloudflare. n8n es un segundo canal opcional: si su variable no está configurada, el código lo marca como apagado y sigue.
¿Se puede usar email en lugar de Telegram? Sí. Lo importante no es el canal sino el patrón: un aviso sin datos personales con una referencia, una comprobación real de la respuesta y un registro de si llegó.
¿El campo trampa para a todos los bots? No. Para a los que rellenan todos los campos. Por eso hay además límite por IP, comprobación de origen y validación en el servidor, y en un proyecto con más spam valoraríamos un desafío.
Fuentes
- •Telegram — Bot API (formato de las respuestas: campos ok y description). https://core.telegram.org/bots/api