Registra un script de seguimiento una vez y luego aplícalo desde el código a las páginas de destino exactas que lo necesiten, sin borrar los scripts que ya están allí.
Añadir manualmente un píxel de campaña a muchas páginas de destino en el Diseñador lleva tiempo, y tienes que repetir el trabajo con cada etiqueta nueva. La API de datos de Webflow te permite registrar un script una vez y aplicarlo a las páginas que elijas mediante código.
El riesgo reside en cómo escribe el endpoint de la página. Reemplaza toda la lista de scripts en cada solicitud, por lo que un descuido puede eliminar scripts que otra aplicación o compañero de equipo haya añadido.
He creado una función de lectura-fusión-escritura que primero lee la página y luego vuelve a escribir la lista completa con tu script fusionado. Una publicación al final hace que el cambio se aplique.
El acceso funciona de forma distinta a la mayoría de las llamadas a la API de Webflow. Estos endpoints requieren un token OAuth de una aplicación de Webflow, y un token de sitio no puede acceder a ellos. La configuración comienza con ese token.
¿Qué necesitas para aplicar código personalizado a través de la API de datos de Webflow?
Necesitas un token OAuth de una aplicación de Webflow. También necesitas los ID del sitio y de la página a los que te diriges, además del script en sí.
Cada requisito tiene una limitación que conviene resolver antes de escribir el código.
Una aplicación de Webflow con OAuth (no un token de sitio)
Los tokens de sitio no pueden acceder a los endpoints de código personalizado. Los permisos custom_code:read y custom_code:write están reservados para una Webflow Data Client App autenticada mediante OAuth.
El propio tutorial de código personalizado de Webflow solicita los alcances sites:read, sites:write, pages:read, pages:write, custom_code:read y custom_code:write. Juntos, estos alcances cubren el listado de páginas y la aplicación de scripts, y te permiten publicar el sitio después.
Una vez que tu aplicación complete el flujo OAuth, establece el token de acceso y el ID del sitio como variables de entorno en la terminal desde la que ejecutarás los scripts:
export WEBFLOW_OAUTH_TOKEN="your-oauth-access-token"
export WEBFLOW_SITE_ID="your-site-id"
Los scripts de abajo corren en Node.js 20 o superior con tsx (un ejecutor de TypeScript para Node.js) y aprovechan la API fetch integrada, así que te ahorras paquetes de Webflow. Si prefieres su SDK oficial, el paquete webflow-api cubre exactamente los mismos endpoints.
Añadir el asistente de solicitudes
Cada script importa un pequeño asistente que añade el token a cada solicitud y vuelve a intentar la operación una vez si recibe un error 429:
// webflow.ts
const API = process.env.WEBFLOW_API_BASE ?? "https://api.webflow.com/v2";
const token = process.env.WEBFLOW_OAUTH_TOKEN;
if (!token) {
throw new Error("Set WEBFLOW_OAUTH_TOKEN to your Webflow App's OAuth access token.");
}
export type Location = "header" | "footer";
export type AppliedScript = {
id: string;
version: string;
location: Location;
attributes?: Record<string, string>;
};
// One request helper: adds auth, retries once on 429, and throws on any other error
export async function wf<T>(path: string, init: RequestInit = {}): Promise<T> {
for (let attempt = 0; attempt < 2; attempt++) {
const res = await fetch(`${API}${path}`, {
...init,
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
...init.headers,
},
});
if (res.status === 429 && attempt === 0) {
const wait = Number(res.headers.get("Retry-After") ?? "60");
await new Promise((r) => setTimeout(r, wait * 1000));
continue;
}
if (!res.ok) {
throw new Error(`${init.method ?? "GET"} ${path} failed: ${res.status} ${await res.text()}`);
}
return (await res.json()) as T;
}
throw new Error(`${path} still rate limited after one retry`);
}
El asistente también lanza un error ante cualquier otro fallo, por lo que una lectura fallida nunca se convertirá en una lista vacía que sobrescriba los scripts reales de la página en una escritura posterior.
El ID de tu sitio y los IDs de las páginas a las que quieres dirigirte
El ID de tu sitio se obtiene del endpoint List Sites, y los ID de las páginas provienen del endpoint List Pages para ese sitio.
Guarda esto como list-pages.ts para imprimir el slug y el ID de cada página:
// list-pages.ts
import { wf } from "./webflow";
const siteId = process.env.WEBFLOW_SITE_ID!;
const { pages } = await wf<{ pages: { id: string; slug: string; title: string }[] }>(
`/sites/${siteId}/pages?limit=100`,
);
for (const page of pages) {
console.log(`${page.slug}\t${page.id}\t${page.title}`);
}
Al ejecutar npx tsx list-pages.ts se imprime la lista. El endpoint devuelve hasta 100 páginas por solicitud, por lo que un sitio grande necesita una segunda llamada con un desplazamiento (offset). Ahora deberías tener los ID de las páginas que necesitan el script.
El contenido del script o la URL alojada
Los scripts en línea contienen el JavaScript propiamente dicho, sin etiquetas de script, y Webflow lo aloja por ti. La referencia de la API limita el código fuente en línea a 2000 caracteres.
Cualquier contenido más largo debe ir en tu propio servidor o CDN como un script alojado. El registro de scripts alojados requiere la URL pública del archivo y un hash de integridad de subrecursos (SRI) de su contenido.
Genera el hash a partir del archivo activo:
curl -s https://cdn.example.com/analytics.js | openssl dgst -sha384 -binary | openssl enc -base64 -A
Añade el prefijo sha384- al resultado y úsalo como valor de integrityHash. El navegador compara ese hash con el archivo que descarga, por lo que cualquier cambio posterior en el archivo requiere un nuevo hash y una nueva versión registrada.
5 pasos para aplicar un script a una página de Webflow mediante la API de datos
El flujo de trabajo consta de dos fases: registrar un script una vez a nivel de sitio y luego aplicarlo a cada página que lo necesite.
Los ejemplos utilizan un script en línea, aplicado primero a una página y luego a muchas.
1. Registra tu script en el sitio
El registro almacena el script y su versión en el sitio. Después, lo referenciarás por su ID y versión en cada página.
La solicitud de registro para un script en línea se realiza en register-inline.ts:
// register-inline.ts
import { wf } from "./webflow";
const siteId = process.env.WEBFLOW_SITE_ID!;
const script = await wf<{ id: string; version: string }>(
`/sites/${siteId}/registered_scripts/inline`,
{
method: "POST",
body: JSON.stringify({
displayName: "PricingLogger",
version: "1.0.0",
sourceCode: `console.log("Pricing page script loaded");`,
canCopy: false,
}),
},
);
console.log(`Registered ${script.id} at version ${script.version}`);
Ejecútalo con npx tsx register-inline.ts y guarda el ID que aparece. Webflow deriva ese ID del nombre para mostrar, que debe tener entre 1 y 50 caracteres alfanuméricos.
El registro no requiere una ubicación, por lo que eliges el encabezado o el pie de página cada vez que aplicas el script a una página. El valor canCopy decide si Webflow copia el script cuando alguien duplica o transfiere el sitio.
Registrar un script alojado en su lugar
El registro de scripts alojados reemplaza sourceCode con hostedLocation e integrityHash.
Guarda esto como register-hosted.ts, con tu propia URL y hash:
// register-hosted.ts
import { wf } from "./webflow";
const siteId = process.env.WEBFLOW_SITE_ID!;
const script = await wf<{ id: string; version: string }>(
`/sites/${siteId}/registered_scripts/hosted`,
{
method: "POST",
body: JSON.stringify({
displayName: "CampaignAnalytics",
version: "1.0.0",
hostedLocation: "https://cdn.example.com/analytics.js",
integrityHash: "sha384-REPLACE_WITH_YOUR_HASH",
canCopy: false,
}),
},
);
console.log(`Registered ${script.id} at version ${script.version}`);
La ejecución imprime el ID y la versión del script alojado, igual que en la versión en línea. A partir de aquí, ambos tipos de script funcionan de la misma manera.
2. Confirma los scripts registrados en el sitio
Una lista rápida de los scripts registrados en el sitio confirma el registro y muestra las cadenas exactas de ID y versión que debes usar.
El script de listado es list-registered.ts:
// list-registered.ts
import { wf } from "./webflow";
const siteId = process.env.WEBFLOW_SITE_ID!;
const { registeredScripts = [] } = await wf<{
registeredScripts?: { id: string; version: string; displayName: string }[];
}>(`/sites/${siteId}/registered_scripts`);
for (const s of registeredScripts) {
console.log(`${s.id}\t${s.version}\t${s.displayName}`);
}
Ejecuta npx tsx list-registered.ts para verlos. Un sitio puede albergar hasta 800 scripts registrados, así que esta lista también sirve para revisar versiones antiguas antes de alcanzar el límite.
3. Lee los scripts actuales de la página antes de cambiarlos
El endpoint de página reemplaza toda la lista de scripts en cada escritura. Webflow elimina de la página cualquier script que omitas en la solicitud, incluidos los que hayan añadido otra aplicación o un compañero de equipo.
Por lo tanto, la lectura previa a cada escritura es la llamada más importante del flujo de trabajo. La función applyToPage en el siguiente paso siempre lee la página primero, y el manejo de errores del asistente detiene la ejecución si esa lectura falla.
Cada elemento en la lista de una página incluye un id, una versión y una ubicación, además de atributos opcionales. Una escritura debe devolver el id, la versión y la ubicación de cada script que desees conservar.
4. Fusiona tu script en la lista y escríbelo de vuelta
La función applyToPage lee la página, reemplaza cualquier versión anterior de tu script, mantiene todo lo demás y escribe la lista completa de nuevo.
Coloca la función en apply-script.ts:
// apply-script.ts
import { wf, type AppliedScript } from "./webflow";
// Read the page's scripts, swap in the new one, and write the full list back
export async function applyToPage(pageId: string, script: AppliedScript) {
const { scripts = [] } = await wf<{ scripts?: AppliedScript[] }>(
`/pages/${pageId}/custom_code`,
);
const current = scripts.find((s) => s.id === script.id);
if (current?.version === script.version && current.location === script.location) {
return "unchanged";
}
const next = [...scripts.filter((s) => s.id !== script.id), script];
await wf(`/pages/${pageId}/custom_code`, {
method: "PUT",
body: JSON.stringify({ scripts: next }),
});
return current ? "updated" : "added";
}
const [pageId, id, version, location = "footer"] = process.argv.slice(2);
if (pageId && id && version) {
const result = await applyToPage(pageId, { id, version, location: location as "header" | "footer" });
console.log(`${pageId}: ${result}`);
}
Ejecútala con el ID de página, el ID de script, la versión y la ubicación, por ejemplo npx tsx apply-script.ts <page-id> <script-id> 1.0.0 footer. Imprime si se añadió, actualizó o no hubo cambios, y los demás scripts de la página permanecen intactos.
El objeto de atributos opcionales se convierte en atributos HTML en la etiqueta script renderizada. Para renderizar data-page="pricing" en la etiqueta, establece { "data-page": "pricing" } como los atributos del objeto script que le pasas a applyToPage.
Aplicar el script en muchas páginas
La misma función gestiona las actualizaciones masivas. Cada página requiere dos solicitudes, una de lectura y otra de escritura, por lo que el bucle hace una pausa entre páginas.
El bucle va en bulk-apply.ts:
// bulk-apply.ts
import { applyToPage } from "./apply-script";
// Each page costs two requests, so 2 seconds per page keeps you at 60 requests a minute
const DELAY_MS = Number(process.env.DELAY_MS ?? "2000");
const pageIds = (process.env.PAGE_IDS ?? "").split(",").filter(Boolean);
const script = {
id: process.env.SCRIPT_ID!, // the id that register-inline.ts printed
version: process.env.SCRIPT_VERSION ?? "1.0.0",
location: "footer" as const,
};
const failed: string[] = [];
for (const pageId of pageIds) {
try {
console.log(`${pageId}: ${await applyToPage(pageId, script)}`);
} catch (err) {
failed.push(pageId);
console.error(`${pageId}: ${(err as Error).message}`);
}
await new Promise((r) => setTimeout(r, DELAY_MS));
}
console.log(`Done. ${pageIds.length - failed.length} succeeded, ${failed.length} failed.`);
if (failed.length) process.exitCode = 1;
Ejecútalo con SCRIPT_ID=<script-id> PAGE_IDS=<id1>,<id2> npx tsx bulk-apply.ts. El límite de Webflow es de 60 solicitudes por minuto en sitios Starter y Basic, y 120 en planes de pago con CMS, tal como indica la referencia de límites de tasa . El valor predeterminado de 2 segundos es adecuado para el límite inferior, y puedes establecer DELAY_MS en 1000 en un plan de 120 solicitudes.
El bucle informa de cada fallo y termina con un código de error, de modo que cualquier programador de tareas que supervise los códigos de salida detectará una ejecución parcial. Ahora deberías ver cada página listada como añadida, actualizada o sin cambios.
5. Publica el sitio para que los cambios entren en vigor
Al aplicar un script, se modifica el código personalizado en borrador del sitio. Los visitantes solo lo verán después de que publiques el sitio.
Al publicar, todos los cambios en borrador del sitio se ponen en vivo, incluidos los que no tienen nada que ver con tu script. La guía de código personalizado de Webflow recomienda pedir al propietario del sitio que publique cuando esté listo, en lugar de hacerlo en su nombre.
Si tu aplicación se encarga de publicar, el endpoint Publish Site requiere el permiso sites:write y admite una publicación exitosa por minuto. El cuerpo de la solicitud debe incluir customDomains o publishToWebflowSubdomain. Si pasas un ID de página, publicarás solo esa página sin tocar el resto de los cambios pendientes.
Revisa el código fuente de la página publicada después para confirmar que la etiqueta del script aparece en el head o antes de la etiqueta de cierre body.
¿Qué provoca que fallen las llamadas a la API de código personalizado de Webflow?
La mayoría de los fallos se deben al token o a una escritura incompleta, y no publicar puede ocultar una escritura que sí tuvo éxito. Cada causa produce un síntoma diferente.
Empieza por el síntoma que observes.
Todas las solicitudes de código personalizado fallan: se usó el token del sitio en lugar de OAuth
Causa: La solicitud usa un token de sitio obtenido en Configuración del sitio > Apps e integraciones > Acceso a la API. Los tokens de sitio no tienen acceso a los endpoints de código personalizado.
Solución: Usa el token de acceso OAuth de tu aplicación de Webflow con los permisos custom_code autorizados. Si el token es correcto y las solicitudes siguen fallando, asegúrate de haber autorizado la aplicación en el sitio correspondiente.
Los scripts desaparecen de una página tras una escritura
Causa: La escritura envió una lista que omitió los scripts ya existentes en la página. El endpoint asume que la lista enviada es la definitiva y reemplaza todo.
Solución: Canaliza cualquier cambio con un flujo de lectura-fusión-escritura como applyToPage, y jamás armes la lista desde cero. Si los scripts ya desaparecieron, vuelve a aplicar cada uno con su ID y versión registrados, que puedes consultar con list-registered.ts.
Una escritura devuelve un error 400 o 409
Causa: Un error 400 suele indicar un elemento incompleto —como una versión faltante— o que apunta a un script no registrado. Un 409 en el endpoint de la página significa que el sitio ya alcanzó su tope de 800 scripts registrados.
Solución: Ante un 400, coteja cada elemento con la salida de list-registered.ts e incluye siempre id, version y location para cada script. Ante un 409, reutiliza una versión ya registrada en lugar de dar de alta otra.
El script se aplica pero no aparece en el sitio en vivo
Causa: No has publicado el sitio tras aplicar el script. Los scripts aplicados quedan en espera hasta que lances una publicación.
Solución: Publica el sitio desde Webflow o mediante el endpoint Publish Site si tu aplicación gestiona las publicaciones. Luego abre el código fuente en el dominio activo y busca el script.
Construye la capa de automatización de tu sitio
La misma fórmula de lectura-fusión-escritura sirve a nivel de sitio, donde el endpoint de código personalizado del sitio aplica un script a todas las páginas de un solo golpe. Los scripts de sitio son ideales para analítica y herramientas de consentimiento, mientras que los de página van de perlas para píxeles de campaña en una landing específica.
Para retoques puntuales, el servidor MCP de Webflow permite que un agente de IA lea y modifique código personalizado de sitios y páginas o gestione scripts registrados. Nuestra guía de configuración de Cookiebot muestra cómo cargar un script justo al inicio del head. La guía de la API de CMS explora a fondo la gestión de contenidos con esta misma Data API.
Preguntas frecuentes
El tipo de token y los límites de scripts son las dudas más frecuentes, así que aquí tienes las respuestas.
¿Puedo usar un token de sitio para la API de código personalizado?
No. Los tokens de sitio no pueden acceder a los endpoints de código personalizado. Necesitas un token de acceso OAuth de una aplicación cliente de datos de Webflow con los permisos custom_code:read y custom_code:write.
¿Qué pasa si envío una lista de scripts vacía a una página?
La página pierde todos los scripts aplicados. La lista que envíes se convierte en el conjunto completo de la página, así que una lista vacía la deja limpia una vez que se publica el sitio.
¿Existe un límite de velocidad en las llamadas a la API de código personalizado?
Sí. El límite es de 60 solicitudes por minuto en sitios Starter y Basic, y de 120 en planes de pago con CMS, por cada clave de API. Una respuesta 429 incluye una cabecera Retry-After, que el asistente webflow.ts respeta una vez antes de fallar.
¿Puedo actualizar el código fuente de un script registrado después del registro?
No. Registra el código nuevo como una versión nueva y luego aplícala a cada página. La función de lectura-fusión-escritura reemplaza la versión antigua de la página por la nueva.
¿Cómo elimino un script de una página sin borrar todos los scripts?
Lee los scripts de la página, filtra el que quieras eliminar y vuelve a escribir el resto. Los demás scripts se mantienen y el cambio se publica en la siguiente actualización del sitio.




