Cómo añadir completado de texto de OpenAI a un formulario de Webflow con una Cloud App

Llamar a la API de OpenAI directamente desde el código personalizado de una página de Webflow expone tu clave en el navegador. Un gestor de rutas de Webflow Cloud App soluciona esto: el formulario se envía, el gestor llama a OpenAI con tu clave almacenada en una variable de entorno del servidor y el resultado aparece en la página en un solo paso.

En esta guía, veremos todo el proceso: instalar el SDK de OpenAI en la Cloud App, crear el gestor de rutas que procesa la llamada a la API, montar el formulario en el Webflow Designer y escribir el JavaScript personalizado que conecta todo.

¿Qué necesitas para añadir la finalización de texto de OpenAI a un formulario de Webflow?

Necesitas una Webflow Cloud App, una clave de API de OpenAI, un formulario en el Webflow Designer y un pequeño bloque de JavaScript personalizado.

Estos son los requisitos:

1. Un sitio de Webflow con un plan de pago (necesario para Webflow Cloud)
2. Una Webflow Cloud App ya creada (ejecuta webflow auth login && webflow cloud init si aún no lo has hecho)
3. Una cuenta de OpenAI con una clave de API
4. Node.js 20.0.0 o superior y npm instalados

La parte de la Cloud App añade un gestor de rutas y una variable de entorno. La parte del sitio de Webflow añade un formulario y unas 25 líneas de código personalizado.

Algo que quiero aclarar desde el principio: nunca llames a la API de OpenAI directamente desde el código personalizado de una página de Webflow. Eso expone tu clave de API en el navegador, donde cualquiera puede encontrarla en el inspector de red y usarla para vaciar tu cuenta.

5 pasos para añadir la finalización de texto de OpenAI a un formulario de Webflow

Estos cinco pasos se dividen claramente en dos flujos de trabajo: el trabajo en el servidor dentro de la Cloud App (pasos 1-3) y el trabajo en el front-end en Webflow (pasos 4 y 5).

El formulario vive en tu sitio de Webflow. La lógica de OpenAI vive en el gestor de rutas de la Cloud App. El JavaScript personalizado en la página de Webflow sirve de puente: intercepta el envío del formulario, llama al gestor de rutas y escribe el resultado de vuelta en la página.

Aquí tienes la secuencia para configurarlo.

1. Instala el SDK de OpenAI en la Cloud App

El openaipaquete npm es la única dependencia nueva. Te proporciona un cliente tipado para la API de respuestas que se ejecuta de forma nativa en Cloudflare Workers.

En la raíz de tu proyecto Cloud App:

npm install openai

El openai paquete es el SDK oficial de TypeScript. Las versiones 4 en adelante utilizan la Web Fetch API para las peticiones HTTP en lugar de las funciones integradas de Node.js, lo que significa que se ejecutan en aislamientos V8, el entorno de ejecución que utiliza Cloudflare Workers. No se necesitan polyfills ni flags de compatibilidad.

Tras la instalación, verifica que el paquete aparezca en package.json bajo dependencies. La versión debe ser ^4 o superior.

2. Añade la clave de API de OpenAI a tu entorno

La clave de API debe ir en dos lugares:

• .env.local para el desarrollo local
• El panel de entorno de Webflow Cloud para producción

La clave debe permanecer solo en el servidor. Nada de prefijos NEXT_PUBLIC_ , nunca.

Añádela a .env.local en tu proyecto de Cloud App:

OPENAI_API_KEY=sk-proj-your_key_here

OPENAI_API_KEY no tiene prefijo NEXT_PUBLIC_ . Se mantiene exclusivamente en el servidor y nunca se envía al navegador. Si accidentalmente le añades el prefijo NEXT_PUBLIC_, la clave aparecerá en tu paquete de JavaScript de producción.

Antes de desplegar, añade la misma clave a tu entorno de Webflow Cloud. Ve a la configuración de tu sitio Webflow, navega hasta Webflow Cloud, abre tu entorno Cloud y añade OPENAI_API_KEY en Variables de entorno.

3. Crea el gestor de rutas para las respuestas de OpenAI

Este es todo el backend. El gestor de rutas recibe una instrucción desde la página de Webflow, llama a la API de respuestas de OpenAI con tu clave del lado del servidor y devuelve el texto generado en formato JSON. El código personalizado de Webflow nunca llega a tocar la clave de la API.

Un apunte sobre el riesgo de abuso: Una vez que este endpoint esté desplegado, será accesible públicamente. Cualquiera que encuentre la URL podrá llamarla, enviar una instrucción y cargar tokens a tu cuenta de OpenAI.

El código que aparece a continuación incluye dos medidas de mitigación:

• Primero, la instrucción del sistema está codificada directamente en el servidor; quienes llamen al endpoint no podrán anular las instrucciones del modelo desde el cliente.
• Segundo, el gestor comprueba el referente de la solicitud y rechaza las llamadas que no provengan de tu dominio.

Ninguna de estas protecciones es infalible (las cabeceras de referencia pueden falsificarse), pero juntas suben el listón considerablemente. Si gestionas un formulario con mucho tráfico, añade además una limitación de tasa con Cloudflare.

Crea app/api/complete/route.ts en tu Cloud App:

// app/api/complete/route.ts
export const runtime = 'edge'

import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

// Hard-code all system prompts here. Never accept instructions from the client.
// If you have multiple forms, add an entry per form ID and use a hidden field
// in your Webflow form to pass the matching key (see Step 5).
const SYSTEM_PROMPTS: Record<string, string> = {
  default: 'You are a helpful assistant.',
  // product: 'You write punchy, benefit-first product copy in 50 words or fewer.',
  // bio: 'You write first-person professional bios for LinkedIn.',
}

const ALLOWED_ORIGIN = process.env.ALLOWED_ORIGIN // e.g. 'https://your-site.webflow.io'

export async function POST(request: Request) {
  // Referrer check — rejects requests that don't come from your domain.
  // Not foolproof, but filters opportunistic abuse.
  const referrer = request.headers.get('referer') ?? ''
  if (ALLOWED_ORIGIN && !referrer.startsWith(ALLOWED_ORIGIN)) {
    return Response.json({ error: 'Forbidden' }, { status: 403 })
  }

  const { prompt, formId } = await request.json()

  if (!prompt || typeof prompt !== 'string' || prompt.trim().length === 0) {
    return Response.json({ error: 'Prompt is required' }, { status: 400 })
  }

  // formId selects a pre-approved system prompt. Unknown IDs fall back to default.
  const systemPrompt = SYSTEM_PROMPTS[formId] ?? SYSTEM_PROMPTS.default

  const response = await openai.responses.create({
    model: 'gpt-4o',
    instructions: systemPrompt,
    input: prompt.trim(),
  })

  return Response.json({ text: response.output_text })
}

Añade ALLOWED_ORIGIN como variable de entorno en Webflow Cloud junto a OPENAI_API_KEY — asígnala al dominio de tu sitio publicado (por ejemplo, https://your-site.webflow.io).

Algunos puntos a tener en cuenta en este código:

• export const runtime = 'edge' indica a Next.js que ejecute este gestor en Cloudflare Workers en lugar de en un servidor Node.js.
• SYSTEM_PROMPTS es un mapa del lado del servidor. Las instrucciones del sistema nunca se aceptan desde el cliente; quien realiza la llamada puede elegir qué prompt preaprobado usar mediante formId, pero no puede proporcionar el texto de la instrucción por sí mismo. Añade una entrada por cada formulario en tu sitio.
• ALLOWED_ORIGIN filtra las solicitudes por referente. Configúralo en tu entorno Cloud con tu dominio publicado. Elimínalo solo durante las pruebas locales.
• openai.responses.create() es la API recomendada actualmente por OpenAI para la generación de texto. OpenAI recomienda la API de Respuestas sobre Chat Completions para todos los proyectos nuevos.
• output_text agrega toda la salida de texto del modelo en una sola cadena.

Para una tarea sencilla de completar texto, eso es todo lo que necesitas.

Probar el manejador de rutas localmente antes de tocar Webflow

Antes de conectar el formulario de Webflow, confirma que el manejador de rutas funciona por sí solo. Ejecuta esto desde tu terminal mientras el servidor de desarrollo de tu Cloud App esté activo:

curl -X POST http://localhost:3000/app/api/complete \
  -H "Content-Type: application/json" \
  -H "Referer: https://your-site.webflow.io" \
  -d '{"prompt": "Write a 50-word product description for noise-cancelling headphones.", "formId": "product"}'

La cabecera Referer es necesaria localmente si ALLOWED_ORIGIN está configurado. Pasa la clave formId que coincida con una de tus entradas de SYSTEM_PROMPTS, u omítela para usar el prompt default.

En este punto, la capa de IA está completa y se puede probar de forma independiente.

4. Crea el formulario de prompts de OpenAI en el Diseñador de Webflow

El formulario necesita cuatro elementos:

• Un área de texto para el prompt
• Un botón de envío
• Un div contenedor para el resultado
• Un indicador de carga

Los ID de los elementos que configures aquí son los que usará el JavaScript personalizado. Si los haces bien, la conexión en el paso 5 será pan comido.

Añade un elemento de área de texto y establece su ID en ai-prompt en la configuración del elemento. Aquí es donde los usuarios escribirán su solicitud.

Añade un bloque Div con el ID ai-result y establece su visualización (Display) en "None" por defecto. Aquí es donde aparecerá el texto generado. Dentro, añade un bloque de texto con el ID ai-output para el contenido real, y un segundo bloque de texto con el ID ai-loading que diga "Generando...". Mostrarás y ocultarás ambos mediante JavaScript.

El botón de envío del formulario puede quedarse como está. El JavaScript interceptará el evento de envío antes de que el procesador de formularios de Webflow lo gestione.

Si tienes más de un formulario con IA en tu sitio, añade un elemento de campo oculto dentro de cada bloque de formulario. Establece su ID en form-id y su valor predeterminado en una cadena que coincida con la clave correspondiente en tu mapa SYSTEM_PROMPTS (por ejemplo, product, bio).

El JavaScript del paso 5 leerá este campo y lo enviará como formId. Así es como puedes ejecutar varios formularios con distintos comportamientos desde un único Route Handler sin necesidad de que el usuario pueda configurar el prompt del sistema.

No hace falta cambiar la URL de acción ni el método del formulario en el Diseñador. La interceptación ocurre a nivel de JavaScript.

5. Añade el código personalizado de Webflow para llamar al Route Handler

Este script intercepta el envío del formulario, llama al Route Handler de la Cloud App con el prompt y escribe la respuesta de OpenAI en el contenedor de resultados. Debes colocarlo en la configuración de tu página de Webflow, en el apartado de código del pie de página (antes de la etiqueta </body>):

<script>
const form = document.querySelector('[data-name="your-form-name"]');
const promptField = document.getElementById('ai-prompt');
const formIdField = document.getElementById('form-id'); // optional: hidden field
const resultContainer = document.getElementById('ai-result');
const outputText = document.getElementById('ai-output');
const loadingText = document.getElementById('ai-loading');

if (form) {
  form.addEventListener('submit', async (event) => {
    event.preventDefault();

    const prompt = promptField.value.trim();
    if (!prompt) return;

    // Read formId from a hidden field if present, otherwise send nothing (Route Handler defaults to 'default').
    const formId = formIdField ? formIdField.value : 'default';

    resultContainer.style.display = 'block';
    loadingText.style.display = 'block';
    outputText.textContent = '';
    resultContainer.scrollIntoView({ behavior: 'smooth' });

    try {
      const response = await fetch('/app/api/complete', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ prompt, formId }),
      });

      if (!response.ok) {
        throw new Error(`Request failed: ${response.status}`);
      }

      const data = await response.json();
      outputText.textContent = data.text;
    } catch (error) {
      outputText.textContent = 'Something went wrong. Please try again.';
      console.error('Completion error:', error);
    } finally {
      loadingText.style.display = 'none';
    }
  });
}
</script>

Sustituye YOUR_CLOUD_APP_DOMAIN.webflow.io por tu dominio real si la Cloud App está en un nombre de host distinto, o usa una ruta /app/api/complete relativa si la Cloud App está montada en el mismo dominio.

El data-name selector del bloque de formulario apunta al formulario de Webflow mediante su atributo de nombre, que habrás definido en los ajustes del bloque de formulario en el Diseñador. Usar data-name es más fiable que apuntar por clase, ya que Webflow a veces regenera los nombres de las clases. Sustituye "your-form-name" por el nombre que le hayas dado al formulario.

event.preventDefault() es lo que hace el trabajo pesado aquí. Sin esto, al hacer clic en Enviar se activa el envío nativo de Webflow, que manda los datos a su punto de conexión de procesamiento y redirige al estado de éxito. Tu llamada fetch nunca se ejecuta. Con esto, el envío completo del formulario se transfiere a tu función asíncrona.

El prompt del sistema no está definido en este script. Vive en el mapa SYSTEM_PROMPTS del Route Handler en el lado del servidor, donde el usuario no puede sobrescribirlo. El valor formId que envía este script solo sirve para seleccionar qué prompt aprobado se aplica, nada más.

Para añadir un nuevo comportamiento, añade una entrada a SYSTEM_PROMPTS en el Route Handler y configura el valor formId correspondiente en el campo oculto del formulario de Webflow.

Despliega cuando estés listo:

webflow auth login
webflow cloud deploy

O haz un push a la rama de GitHub conectada para activar un despliegue automático.

El formulario ya está activo. Escribe un prompt, haz clic en Enviar y la respuesta aparecerá en la página sin necesidad de recargar ni redirigir.

¿Por qué falla la integración del formulario de OpenAI en Webflow?

Casi todos los fallos se deben a una de estas cuatro causas: ruta de fetch incorrecta, interceptación del evento de formulario rota, variable de entorno ausente o una respuesta vacía del modelo.

Aquí tienes cómo diagnosticar cada uno.

Lafetchllamada apunta a una ruta incorrecta

Si el basePath de tu Cloud App en next.config.ts está configurado como /app, el Route Handler se encuentra en /app/api/complete en tu dominio. Si el basePath es otro, actualiza la URL de fetch para que coincida. Abre el inspector de red del navegador mientras envías el formulario. La solicitud fallida mostrará la URL exacta a la que se está intentando acceder y el código de estado HTTP.

event.preventDefault()no se está ejecutando

Si la página redirige al estado de éxito de Webflow al enviar, es que el script no se está cargando (revisa el panel de código personalizado por si hay errores de sintaxis) o que el selector del formulario no coincide. Confirma que el atributo data-name en el script coincida exactamente con el nombre del formulario en los ajustes del Diseñador de Webflow, incluyendo mayúsculas y espacios.

OPENAI_API_KEYno configurada en el entorno Cloud

El Route Handler devuelve un error 500 y la consola del navegador muestra un error de autenticación de OpenAI. Confirma que la clave esté presente en Webflow Cloud → Variables de entorno y vuelve a desplegar. Las variables de entorno solo surten efecto tras un nuevo despliegue; no se aplican a mitad de una sesión.

El modelo devuelve un resultado vacíooutput_text

Esto es poco común, pero ocurre cuando el prompt activa la política de contenido de OpenAI y el modelo se niega a responder. En este caso, la propiedad devuelve una cadena vacía en lugar de un error. Añade una comprobación: .output_textif (!data.text) { outputText.textContent = 'No response generated. Try rephrasing your prompt.'; }

La verificación de referencia está bloqueando tu propio formulario

Si el Route Handler devuelve un error 403 en un formulario activo, pero las pruebas con curl funcionan localmente, la variable de entorno no coincide exactamente con tu dominio publicado. Comprueba si hay una discrepancia con la barra diagonal final ( vs ) o si un subdominio de pruebas difiere del de producción.ALLOWED_ORIGINhttps://your-site.webflow.iohttps://your-site.webflow.io/

Actualiza en Webflow Cloud para que coincida exactamente con el origen que envía el navegador y vuelve a desplegar.ALLOWED_ORIGIN

Próximos pasos para tu integración de Webflow Cloud con modelos de IA

Ya tienes un formulario de Webflow que llama a la API de OpenAI desde el servidor y muestra el resultado en la página sin necesidad de redirecciones ni recargas. A partir de aquí, la mejora más habitual es el streaming. En lugar de esperar a que se complete todo el texto, la respuesta aparece palabra por palabra.

Explora Webflow + ChatGPT para obtener respuestas en streaming y un historial de conversaciones multironda en tus formularios de Webflow.

Explora Webflow + Claude para análisis de contexto largo, procesamiento de documentos y respuestas que requieren un razonamiento complejo.

Explora Webflow + Gemini para entradas multimodales que combinan imágenes y texto en un mismo formulario.