Cómo integrar una API REST con la interfaz de un panel en Webflow Cloud sin exponer tu token de API

Una página desplegada añade restricciones de enrutamiento que cURL no pone a prueba. Un despliegue funcional mantiene el token en el código del servidor. También omite una directiva de tiempo de ejecución no compatible que puede detener la compilación antes de que se renderice la página.

Antes de sumergirte en la configuración, es útil entender la pila tecnológica exacta y los requisitos previos necesarios para establecer este puente seguro entre tu API REST y la interfaz de Webflow.

¿Qué necesitas para integrar una API REST con una interfaz de panel de control en Webflow?

Necesitas un sitio de Webflow en el plan Starter o superior, Next.js, npm, credenciales de API REST y herramientas locales de Node.js. Para montar la aplicación desplegada en un dominio personalizado, necesitas el plan Premium o superior.

Reúne estos elementos antes de empezar:

• Sitio de Webflow en plan Starter o superior: Webflow Cloud está incluido desde el plan gratuito Starter, y un panel de control en un dominio personalizado requiere el plan Premium o superior.
• Next.js 15 o superior: La versión 15 es el requisito mínimo que admite Webflow Cloud para Next.js, y esta compilación utiliza Next.js.
• npm como gestor de paquetes: La documentación de Webflow Cloud es explícita: "Actualmente, Webflow Cloud solo admite el gestor de paquetes npm". Usa npm para esta compilación; pnpm y yarn no son compatibles.
• Un endpoint REST y un token: Necesitas una API a la que puedas llamar desde un servidor con el método de autenticación que documente su proveedor, además de una respuesta de muestra que indique qué campos mostrará el panel de control.
• Node.js local y un editor: Una instalación de Node.js con npm cubre la ejecución y la gestión de paquetes. Usa una terminal y un editor para el resto del trabajo local.

Con estos requisitos previos listos, puedes crear la ruta del servidor, conectar la página a ella y desplegar ambos bajo la misma ruta de montaje de Webflow Cloud.

5 pasos para integrar una API REST con una interfaz de panel de control en Webflow Cloud

La compilación requiere cinco pasos: preparar la aplicación Next.js, configurar las variables del servidor y del cliente, crear el Route Handler, conectar la página del panel de control y desplegar todo bajo una misma ruta de montaje coincidente.

Completa la configuración en este orden para que puedas verificar cada capa antes del despliegue.

1. Prepara la aplicación Next.js con npm

Prepara la aplicación con npm para que el proyecto genere un package-lock.json archivo y utilice una versión de Next.js compatible con Webflow Cloud.

Crea el proyecto en el directorio donde guardas tus proyectos y, a continuación, abre el nuevo directorio del proyecto antes de continuar:

npx create-next-app@15 rest-dashboard --typescript --app --no-src-dir --import-alias "@/*" --use-npm

El @15 mantiene la versión principal donde el soporte de middleware de Webflow Cloud es estable, y se resuelve a la versión 15.x más reciente, que está por encima del requisito mínimo 15.2.3 mencionado en la sección de solución de problemas. --no-src-dir coloca app/ en la raíz del proyecto, donde las rutas de archivo en los pasos 3 y 4 esperan encontrarlo.

cd rest-dashboard

Usa los valores predeterminados para ESLint y Tailwind si los quieres; ninguno cambia nada en el despliegue. Mantén el proyecto en npm. Deja next.config en su configuración de salida predeterminada: la página de "bring-your-own-app" de Webflow Cloud lo establece como "No adapter, no base path, no wrangler.json".

Ahora deberías tener un directorio app/ . La carpeta del proyecto también debería contener package.json y package-lock.json, y el servidor de desarrollo local debería mostrar la página predeterminada de Next.js en localhost.

2. Almacena el token de la API REST como un secreto en Webflow Cloud

Almacena el token de la API en la variable de entorno METRICS_API_TOKEN , que solo es accesible desde el servidor, y reserva NEXT_PUBLIC_BASE_PATH para la ruta de montaje que el cliente antepondrá a su solicitud. El JavaScript del navegador puede leer variables con el prefijo NEXT_PUBLIC_ .

Para el desarrollo local, crea el archivo que Next.js lee automáticamente:

# .env.local
METRICS_API_TOKEN=your-token-here
NEXT_PUBLIC_BASE_PATH=

Deja NEXT_PUBLIC_BASE_PATH vacío localmente, ya que el servidor de desarrollo local sirve la aplicación en la raíz. En tu entorno de Webflow Cloud, añade METRICS_API_TOKEN como secreto y establece NEXT_PUBLIC_BASE_PATH en la ruta donde se montará la aplicación, como /dashboard.

La página de "bring-your-own-app" de Webflow Cloud lo explica claramente: "Tanto las variables de entorno secretas como las no secretas están disponibles para el proceso de compilación de tu aplicación... y permanecen disponibles para la aplicación desplegada en tiempo de ejecución". Los secretos se ocultan en los registros de compilación, por lo que el token no aparece en ellos.

Con estas variables configuradas, process.env.METRICS_API_TOKEN se resuelve dentro del código del servidor tanto localmente como en el Worker desplegado, y process.env.NEXT_PUBLIC_BASE_PATH está disponible para el paquete del cliente.

3. Escribe el manejador de rutas que llama a la API REST

Crea el manejador de rutas en app/api/metrics/route.ts y utiliza su configuración de tiempo de ejecución predeterminada.

Lee METRICS_API_TOKEN dentro del manejador, rechaza la solicitud si falta el token y llama al punto de conexión del proveedor utilizando el método de autenticación documentado para esa API. Comprueba si hay una respuesta fallida del proveedor antes de leer sus datos y, a continuación, devuelve solo los campos que necesita el panel de control.

El manejador, con la URL del proveedor como el único valor a reemplazar:

// app/api/metrics/route.ts
import { NextResponse } from 'next/server';

// Replace with your vendor's metrics endpoint.
const UPSTREAM_URL = 'https://api.example.com/v1/metrics';

type Metrics = {
  signups: number;
  revenue: number;
  updatedAt: string;
};

export async function GET() {
  const token = process.env.METRICS_API_TOKEN;
  if (!token) {
    return NextResponse.json({ error: 'Metrics API is not configured' }, { status: 500 });
  }

  let upstream: Response;
  try {
    upstream = await fetch(UPSTREAM_URL, {
      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
    });
  } catch {
    return NextResponse.json({ error: 'Metrics API is unreachable' }, { status: 502 });
  }

  if (!upstream.ok) {
    // Report the status only. The upstream body can echo account details.
    return NextResponse.json(
      { error: 'Metrics API request failed', upstreamStatus: upstream.status },
      { status: 502 },
    );
  }

  let data: Record<string, unknown>;
  try {
    data = (await upstream.json()) as Record<string, unknown>;
  } catch {
    return NextResponse.json({ error: 'Metrics API returned invalid JSON' }, { status: 502 });
  }

  // Map the vendor's field names to the three the dashboard renders.
  const { signups, revenue, updated_at } = data;
  if (
    typeof signups !== 'number' ||
    typeof revenue !== 'number' ||
    typeof updated_at !== 'string'
  ) {
    return NextResponse.json({ error: 'Metrics API returned an unexpected shape' }, { status: 502 });
  }

  const metrics: Metrics = { signups, revenue, updatedAt: updated_at };
  return NextResponse.json(metrics);
}

Asigna los campos devueltos a los nombres que utilice la respuesta real; signups, revenue y updated_at son marcadores de posición para los nombres de tu proveedor. La comprobación de tipos es deliberada: si un proveedor cambia el nombre de un campo, se producirá un error 502 visible, en lugar de un panel de control que muestra cero sin avisar.

Doy forma a la respuesta deliberadamente para que el navegador reciba solo los campos que el panel de control renderiza. Cualquier identificador de cuenta o metadatos internos que incluya el proveedor permanecen en el servidor. Una respuesta de error de origen distinta identifica la llamada al proveedor como la fuente del problema.

Este manejador de rutas de ejemplo expone la API de origen sin autenticación del llamador ni límites de solicitud. Antes de exponer una API de proveedor financiada por tokens en producción, exige la autenticación del llamador y aplica límites de tasa.

Configura también un límite de gasto o de cuota para el proveedor. Una ruta sin restricciones permite que cualquiera que pueda acceder a ella consuma la API de origen a través de tu token. Mantén la ruta privada hasta que tengas esos controles implementados.

Ejecuta el servidor de desarrollo local y abre http://localhost:3000/api/metrics. La ruta debería devolver los campos que seleccionaste con valores reales de tu API.

4. Crea la página del panel de control que realiza las peticiones a través de la ruta base

Crea la página en app/page.tsx, para que cada solicitud del lado del cliente anteponga la ruta base configurada en Webflow Cloud.

Webflow Cloud inyecta la ruta base en tiempo de compilación, pero las solicitudes del lado del cliente no se reescriben, y la documentación de "bring-your-own-app" es clara: "Las llamadas fetch del lado del cliente deben incluir manualmente la ruta base para llegar correctamente a tus puntos de conexión". Una solicitud simple a /api/metrics apunta a la raíz del sitio en producción y no encuentra el manejador de rutas.

Marca la página con 'use client' en la parte superior del archivo. Las páginas del App Router son componentes de servidor por defecto, y tanto el estado de carga como la obtención de datos al cargar que aparecen a continuación requieren renderizado en el cliente.

Luego lee NEXT_PUBLIC_BASE_PATH en el paquete del cliente, antepon su valor a /api/metrics, y solicita la ruta resultante cuando se cargue la página. Muestra un estado de carga mientras la solicitud está pendiente y un estado de error cuando falle. Una vez que llegue la respuesta, muestra los registros y los ingresos. Incluye la marca de tiempo actualizada junto a ellos.

La página completa:

// app/page.tsx
'use client';

import { useEffect, useState } from 'react';

type Metrics = { signups: number; revenue: number; updatedAt: string };

const base = process.env.NEXT_PUBLIC_BASE_PATH ?? '';

export default function Dashboard() {
  const [metrics, setMetrics] = useState<Metrics | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetch(`${base}/api/metrics`)
      .then(async (res) => {
        if (!res.ok) throw new Error(`Request failed with status ${res.status}`);
        return (await res.json()) as Metrics;
      })
      .then(setMetrics)
      .catch((err: unknown) => {
        setError(err instanceof Error ? err.message : 'Request failed');
      });
  }, []);

  if (error) return <p role="alert">Could not load metrics: {error}</p>;
  if (!metrics) return <p>Loading metrics...</p>;

  return (
    <main>
      <h1>Dashboard</h1>
      <dl>
        <dt>Signups</dt>
        <dd>{metrics.signups.toLocaleString()}</dd>
        <dt>Revenue</dt>
        {/* Match the currency your vendor reports. */}
        <dd>{metrics.revenue.toLocaleString(undefined, { style: 'currency', currency: 'USD' })}</dd>
      </dl>
      <p>Updated {new Date(metrics.updatedAt).toLocaleString()}</p>
    </main>
  );
}

Aplica el estilo a las métricas según lo dicte tu sistema de diseño; lo que debe sobrevivir es la ruta de solicitud. Si añades más Route Handlers más adelante, dale a cada solicitud del cliente el mismo prefijo de ruta base.

Localmente, http://localhost:3000 debería mostrar las dos cifras y una marca de tiempo con formato después de cargar.

5. Despliega la aplicación en Webflow Cloud y móntala en el sitio

Haz commit de package-lock.json, mantén .env.local ignorado y utiliza ese commit para crear un proyecto de Webflow Cloud en el sitio.

Monta la aplicación en la ruta configurada en el entorno. Un montaje en /dashboard con una variable de entorno de /dash significa que el prefijo de solicitud del cliente ya no coincide con el montaje, por lo que la solicitud nunca llega al Route Handler.

Confirma que el plan del sitio admite el montaje elegido antes de prometer a un cliente que el panel vivirá en la propia URL de su marca.

Los límites de solicitud y CPU son valores fijos de la plataforma, no niveles del plan: 20 segundos de tiempo real por solicitud, 30 segundos de CPU de Worker, 6 solicitudes salientes simultáneas y 1.000 subsolicitudes. El almacenamiento, la retención y el número de aplicaciones por sitio son las cifras que varían según el plan.

Una vez completada la compilación, https://your-site-domain/dashboard renderiza las mismas dos métricas que viste localmente, y el código fuente de la página excluye METRICS_API_TOKEN.

¿Qué hace que un panel de API REST en Webflow Cloud falle?

Los paneles de API REST suelen fallar debido a una directiva de tiempo de ejecución no compatible, un prefijo de ruta base faltante, un secreto desplegado incorrecto o un comportamiento del middleware que cambia tras una actualización del framework.

Utiliza el síntoma visible para identificar la causa relevante y aplica su solución correspondiente.

La compilación falla con un error de tiempo de ejecución no compatible

Causa: Un Route Handler o una página incluye export const runtime = 'edge', y el adaptador de Cloudflare de OpenNext que utiliza Webflow Cloud para desplegar Next.js no admite el objetivo de tiempo de ejecución edge de Next.js.

La directiva suele aparecer porque la documentación de "trae tu propia aplicación" describe la plataforma como una que "despliega tu aplicación usando el tiempo de ejecución Edge", y un lector atento lo toma como una instrucción para optar por el tiempo de ejecución edge de Next.js.

La plataforma y el objetivo de compilación comparten nombre pero cumplen funciones diferentes. Webflow Cloud se ejecuta en Cloudflare Workers, y OpenNext no puede compilar la directiva de Next.js.

Solución: Elimina la línea export const runtime = 'edge' de cada Route Handler y página, luego vuelve a desplegar. Tu manejador seguirá ejecutándose en Workers en el edge, porque ahí es donde se ejecuta toda la aplicación.

El panel se carga en producción pero no muestra datos

Causa: La solicitud del cliente omitió el valor de la ruta base configurado para la aplicación desplegada. Este error de enrutamiento puede parecer un problema de Webflow, aunque la página en sí se cargue correctamente.

Webflow Cloud no reescribe las solicitudes del lado del cliente, por lo que una /api/metrics ruta vacía apunta a la raíz del sitio en lugar de a la aplicación montada. Por lo tanto, la solicitud no llega al gestor de rutas (Route Handler), aunque el panel de control siga siendo visible.

Solución: Restaura el valor de la ruta de montaje en tu entorno de Webflow Cloud, manteniendo la barra diagonal inicial, y vuelve a desplegar para actualizar el paquete del cliente. Abre la pestaña de Red (Network) del navegador en la página desplegada y confirma que la URL de la solicitud sea /dashboard/api/metrics, lo que confirma que el prefijo está aplicado.

Si sigue siendo diferente, compara NEXT_PUBLIC_BASE_PATH con la ruta de montaje real carácter por carácter. Ambos valores deben coincidir para que la solicitud pueda llegar al gestor.

La API REST devuelve un error 401 desde la aplicación desplegada, pero el token funciona en curl

Causa: El gestor de rutas está leyendo una METRICS_API_TOKEN vacía o diferente a la que usaste en tus pruebas. Un token almacenado solo en .env.local permanece en la máquina local porque ese archivo no se incluye en el repositorio. La discrepancia también puede deberse a una variable añadida a otro entorno de Webflow Cloud.

Revisa también el secreto pegado por si hubiera alguna comilla suelta o un espacio al final. Como los secretos se ocultan en los registros de compilación, no puedes verificar el valor allí, por lo que el error permanece invisible hasta que el proveedor lo rechaza.

Solución: Devuelve temporalmente un diagnóstico desde el gestor, como token ? token.length : 0, y compáralo con la longitud de tu token de curl funcional. Mantén el token fuera de la respuesta.

Un cero significa que la variable falta en ese entorno; una discrepancia significa que la pegaste incorrectamente. Vuelve a introducir el secreto en el entorno de Webflow Cloud, despliega de nuevo y elimina el diagnóstico una vez que la longitud coincida.

Las comprobaciones de encabezados y las redirecciones dejan de funcionar tras una actualización de Next.js

Causa: El archivo pasó de llamarse middleware.ts a proxy.ts. Las notas de actualización de Next.js renombran el middleware a proxy, y proxy se ejecuta en el entorno de ejecución de Node.js sin opción de elegir el entorno Edge.

La documentación de personalización de frameworks de Webflow Cloud establece esta restricción directamente: "El middleware del entorno de ejecución de Node.js no es compatible. Solo el middleware del entorno Edge funciona en el entorno de ejecución de Workers". Por lo tanto, un cambio de nombre sugerido por un codemod o una guía de actualización de Next.js genera un archivo que no puede ejecutarse en Workers. Cualquier comprobación de encabezados, redirección o control de acceso para el panel debe permanecer en un middleware compatible.

Solución: Fija la aplicación en Next.js 15 y mantén el archivo llamado middleware.ts en el entorno Edge. Mantener solo el nombre del archivo no es suficiente en la versión 16, donde la convención está obsoleta y proxy.ts no puede optar por Edge. En la versión 15, mantente en la 15.2.3 o superior, ya que las versiones 15.x anteriores contienen la vulnerabilidad GHSA-f82v-jwr5-mffw, que permite saltarse un control de middleware.

Si proteges el panel con una comprobación de encabezado de secreto compartido, se aplica un detalle adicional de Workers. El entorno de ejecución de Workers desplegado incluye crypto.subtle.timingSafeEqual, una extensión de Cloudflare para Web Crypto. El next dev local no tiene ese método en crypto.subtle, por lo que una comparación de tiempo constante escrita para él fallará durante el desarrollo local.

La función crypto.timingSafeEqual propia de Node, proveniente de node:crypto, es distinta y está disponible localmente. Protégela con una alternativa para desarrollo y prueba el middleware en la aplicación desplegada antes de confiar en él frente a una API de pago.

Qué puedes construir a continuación con APIs REST y Webflow

Un segundo gestor puede conectar el panel a un CRM, mientras que un control de filtro puede pasar parámetros de consulta a la llamada ascendente. En la práctica, suelo ampliar el panel sin cambiar la disciplina de tokens ni la regla de la ruta base.

La parte de Webflow de la pila también es accesible mediante el mismo patrón. El CMS de Webflow admite contenido que los editores siguen gestionando en colecciones. Su API de datos ampliada puede suministrar ese contenido a una aplicación.

Esto respalda la dirección headless nativa de Webflow, mientras que las métricas de terceros siguen estando disponibles en la misma página.