La API del CMS de Webflow te ofrece un control total mediante programación sobre tus colecciones y contenido, pero saber por dónde empezar te ahorrará horas de prueba y error.
La mayoría de los flujos de trabajo del CMS de Webflow comienzan de forma manual y así se quedan: alguien inicia sesión en el Editor, rellena los campos y pulsa publicar. Eso funciona hasta que gestionas cientos de elementos, sincronizas desde una fuente de datos externa o publicas contenido de forma programada. La API del CMS es la forma de sacar todo ese trabajo de la interfaz de usuario.
Esta guía recorre esa secuencia de principio a fin. Generarás un token de API, te conectarás mediante el SDK de JavaScript, leerás tus colecciones, crearás elementos y los publicarás en tu sitio activo.
¿Qué necesitas para empezar con la API del CMS de Webflow?
Necesitas un sitio de Webflow en cualquier plan de pago, acceso de administrador del sitio para generar un token y Node.js instalado si vas a seguir los ejemplos de JavaScript que aparecen a continuación. La API está basada en REST, por lo que cURL también funciona, pero el SDK reduce considerablemente el código repetitivo.
Antes de empezar, verifica todo esto.
Un sitio de Webflow en un plan de pago
La API del CMS de Webflow está disponible en cualquier plan de sitio de Webflow que incluya CMS: Starter (gratuito), CMS y Business. El plan Basic (14 $/mes) es la excepción. Carece explícitamente de funciones de CMS, por lo que las colecciones del CMS no existen en los sitios Basic y los endpoints del CMS no devolverán datos útiles.
Los límites de velocidad también varían según el plan. Los planes CMS, eCommerce y Business obtienen 120 solicitudes por minuto. Los planes Starter y Basic tienen un límite de 60. Ambos realizan el seguimiento de los límites por clave de API, no por sitio, por lo que cada token que generas tiene su propio contador. Comprueba tu plan en la configuración del sitio.
Acceso de administrador del sitio para generar un token de API
Solo los administradores del sitio pueden generar tokens de sitio. Si tu cuenta tiene acceso de editor o solo de contenido, no verás la sección de acceso a la API en la configuración del sitio. Necesitarás que un administrador genere un token y lo comparta contigo, o solicitar un cambio de rol antes de continuar.
Los tokens caducan tras 365 días consecutivos de inactividad. Cualquier llamada a la API realizada con éxito reinicia el contador. Cada sitio admite hasta 5 tokens simultáneamente, así que si tu sitio ya tiene 5, deberás revocar uno antes de poder crear uno nuevo.
Node.js 18 o superior (para el SDK de JavaScript)
El SDK oficial de JavaScript de Webflow (webflow-api) funciona en cualquier entorno Node.js 18+. Gestiona automáticamente la autenticación, el formato de las solicitudes, la paginación y el retroceso exponencial en caso de errores por límite de velocidad. Tareas que, de otro modo, tendrías que implementar tú mismo al usar la API REST básica.
Si estás creando scripts del lado del servidor, aplicaciones de Webflow Cloud o automatizaciones basadas en Node, el SDK es el punto de partida ideal.
Si utilizas Python, el webflowpaquete en PyPI ofrece una cobertura equivalente. Todos los ejemplos de código de esta guía utilizan TypeScript y el SDK de JavaScript.
Una colección ya creada en el Diseñador de Webflow
La API del CMS puede leer, crear, actualizar y eliminar elementos de una colección. El esquema de la colección (sus campos y estructura) se define en el Diseñador de Webflow. No necesitas una colección con contenido para empezar, pero sí es necesario que la colección exista.
Si aún no has creado ninguna, abre el panel del CMS en el Diseñador, haz clic en "Nueva colección", define tus campos y guárdala antes de ejecutar cualquier llamada a la API.
Una vez que los tengas, podrás realizar tu primera llamada a la API de CMS en unos 15 minutos. Aquí te explicamos cómo.
6 pasos para realizar tu primera llamada a la API de CMS de Webflow
Pasar de cero a leer y escribir contenido del CMS mediante programación implica generar un token, instalar el SDK, encontrar el ID de tu sitio, listar colecciones, crear y leer elementos, y publicar en tu sitio activo.
Cada paso se basa en el anterior. No te saltes ninguno.
1. Genera un token de API para el sitio
Abre el Diseñador de Webflow para tu sitio y haz clic en el icono de engranaje en la esquina superior izquierda para abrir la Configuración del sitio.
En la barra lateral izquierda, selecciona Aplicaciones e integraciones. Desplázate hasta el final de la página para encontrar la sección de acceso a la API.
Haz clic en Generar token de API. Introduce un nombre que describa la función de este token (por ejemplo, "Script de sincronización de CMS" o "Automatización de blog") y luego selecciona los alcances que necesites. Para leer y escribir contenido del CMS, selecciona cms:read y cms:write. Para publicar, añade sites:publish.
Haz clic en Generar token y copia el token inmediatamente. Webflow solo lo muestra una vez. Guárdalo en un .env archivo o en un gestor de secretos. Nunca lo incluyas directamente en el código fuente.
La cadena del token tiene este aspecto: 1234567890abcdef.... Pasarás este valor directamente como tu accessToken en el siguiente paso.
2. Instala el SDK de JavaScript de Webflow
Con el token listo, necesitas dos cosas en tu entorno local: el webflow-api paquete y un lugar donde guardar tus credenciales.
Crea un nuevo directorio para tu proyecto e inicialízalo:
mkdir webflow-cms-demo && cd webflow-cms-demo
npm init -y
npm install webflow-apiEl comando anterior instala el webflow-api paquete desde npm. Este es el SDK oficial de JavaScript de Webflow. Envuelve todos los puntos finales de la API de datos, gestiona las cabeceras Authorization automáticamente y devuelve objetos de respuesta tipados.
Luego, crea un .env archivo en la raíz de tu proyecto:
WEBFLOW_API_TOKEN=your_token_hereDespués, crea index.ts (o index.js si no estás usando TypeScript):
import { WebflowClient } from "webflow-api";
const webflow = new WebflowClient({
accessToken: process.env.WEBFLOW_API_TOKEN!,
});El WebflowClient constructor acepta tu token de acceso y devuelve un objeto cliente con métodos organizados por recurso: webflow.sites, webflow.collections, webflow.collections.items, etcétera. Todos los métodos devuelven promesas, por lo que puedes usar await en todo tu código.
3. Obtén el ID de tu sitio
El ID de tu sitio está disponible directamente en el panel de control de Webflow. Ve a la Configuración del sitio y observa la URL en tu navegador. Ahí encontrarás el ID.
Alternativamente, navega a Configuración del sitio > General, donde el ID del sitio se muestra explícitamente.
Cópialo y añádelo a tu .env archivo:
WEBFLOW_SITE_ID=580e63e98c9a982ac9b8b741Lo usarás como referencia process.env.WEBFLOW_SITE_ID en cada llamada posterior. No hace falta llamar a la API para consultarlo.
4. Enumera tus colecciones y encuentra un ID de colección
Con tu siteId en mano, llama a webflow.collections.list() para ver todas las colecciones del sitio.
Pega lo siguiente en tu archivo y ejecútalo para recuperar todas las colecciones del sitio:
async function listCollections() {
const collections = await webflow.collections.list({
siteId: process.env.WEBFLOW_SITE_ID!,
});
console.log(JSON.stringify(collections, null, 2));
}
listCollections();La respuesta devuelve una matriz de objetos de colección. Cada uno tiene un id, un displayName, un singularName y un slug. También devuelve la matriz de campos: el esquema completo de cada colección, con tipos de campo, nombres para mostrar y reglas de validación.
Cada objeto de colección en la respuesta se ve así:
{
"collections": [
{
"id": "580e63fc8c9a982ac9b8b745",
"displayName": "Blog Posts",
"singularName": "Blog Post",
"slug": "posts",
"fields": [
{
"type": "PlainText",
"displayName": "Title",
"slug": "title",
"isRequired": true
}
]
}
]
}Copia el id de la colección con la que quieras trabajar. Este es tu collectionId. Para los campos de tipo Opción, fíjate en la matriz validations.options dentro de la definición del campo. Cada opción tiene un id generado automáticamente que necesitarás al crear elementos con ese campo completado.
Guarda el ID de la colección en tu .env archivo:
WEBFLOW_COLLECTION_ID=580e63fc8c9a982ac9b8b745La matriz fields muestra el esquema completo de esa colección. Si la colección utiliza campos de tipo Opción, cada opción dentro de validations.options tiene un id generado automáticamente. Necesitarás esos IDs al crear elementos que establezcan un valor de campo de Opción.
5. Crea y lee elementos de colección
Tanto para crear como para enumerar elementos se utiliza el mismo ID de colección.
Empieza enumerando los elementos existentes para confirmar que tu conexión funciona:
async function listItems() {
const result = await webflow.collections.items.listItems(
process.env.WEBFLOW_COLLECTION_ID!,
{ limit: 10, offset: 0 }
);
console.log(`Total items: ${result.pagination?.total}`);
console.log(JSON.stringify(result.items, null, 2));
}
listItems();El parámetro limit limita los resultados a un máximo de 100 por llamada. El parámetro offset te permite paginar a través de colecciones con más de 100 elementos. El objeto pagination en la respuesta contiene total, limit y offset. Úsalos para recorrer todos los elementos en colecciones más grandes.
Para crear un nuevo elemento, llama a webflow.collections.items.createItem(). El objeto fieldData debe coincidir con el esquema de la colección.
Cada colección tiene dos campos predeterminados: name y slug, además de cualquier campo personalizado que hayas definido en el Diseñador:
async function createItem() {
const newItem = await webflow.collections.items.createItem(
process.env.WEBFLOW_COLLECTION_ID!,
{
isDraft: false,
fieldData: {
name: "My First API Post",
slug: "my-first-api-post",
// Add your custom field slugs here:
// "post-summary": "Written via the CMS API",
},
}
);
console.log(`Created item ID: ${newItem.id}`);
}
createItem();Establecer isDraft: false significa que el elemento está preparado para publicarse, pero aún no está activo. El elemento tendrá un valor lastPublished de null y isDraft de false. Ese es el estado "En cola para publicar" en la interfaz de Webflow. No aparecerá en tu sitio activo hasta que lo publiques.
6. Publica elementos en tu sitio activo
Crear un elemento lo deja en fase de preparación. Publicarlo lo hace activo. Tienes dos opciones: publicar elementos específicos o publicar todo el sitio.
Para publicar solo elementos específicos:
async function publishItem(itemId: string) {
const result = await webflow.collections.items.publishItem(
process.env.WEBFLOW_COLLECTION_ID!,
{
itemIds: [itemId],
}
);
console.log(`Published: ${JSON.stringify(result)}`);
}
publishItem("YOUR_ITEM_ID_HERE");Esta llamada se dirige a un solo elemento (o a varios elementos en la matriz) y publica únicamente esos, dejando todo lo demás en el sitio intacto. Úsala cuando envíes actualizaciones de contenido de forma programática: entradas de blog, descripciones de productos o biografías de miembros del equipo.
Para publicar todo el contenido en espera en todo el sitio a la vez:
async function publishSite() {
await webflow.sites.publish(process.env.WEBFLOW_SITE_ID!, {
publishToWebflowSubdomain: true,
});
console.log("Site published");
}
publishSite();La publicación de todo el sitio está limitada a una publicación exitosa por minuto debido al límite de velocidad específico del endpoint de la API. Para migraciones de contenido masivas o lanzamientos programados donde quieras que todo se publique al mismo tiempo, la publicación de todo el sitio es la opción ideal. Para flujos de trabajo de contenido continuos donde los elementos se publican de forma independiente, utiliza el endpoint de publicación a nivel de elemento.
Después de publicar, visita tu sitio de Webflow en vivo y confirma que el nuevo elemento aparece. Si es así, tu canalización de la API de CMS funciona de principio a fin.
¿Qué causa que las llamadas a la API de CMS de Webflow fallen?
Los fallos de la API de CMS se dividen en cuatro categorías: errores de autenticación que impiden que cualquier solicitud llegue al servidor; errores de permisos debido a la falta de alcances (scopes) en el token; errores de ID causados por el uso de un identificador incorrecto; y brechas de publicación donde los elementos se crean pero nunca aparecen en el sitio en vivo.
Cada uno tiene una solución distinta.
Las solicitudes devuelven 401 Unauthorized
Una respuesta 401 significa que la API rechazó tu autenticación. Las tres causas más comunes son un token mal formado, un token caducado o el token incorrecto para el sitio equivocado.
Revisa el valor del encabezado en tu solicitud. Debe tener el formato Bearer con una B mayúscula y un solo espacio. Si estás usando el SDK, verifica dos veces que la variable esté realmente poblada. Registra su valor antes de la llamada del cliente. Una variable de entorno no definida se pasa al SDK como undefined y falla silenciosamente durante la verificación de autenticación.AuthorizationBearer YOUR_TOKENprocess.env.WEBFLOW_API_TOKEN"undefined"
Los tokens caducan después de 365 días de inactividad. Si un token no se ha utilizado en un año, no es válido. Ve a Configuración del sitio > Aplicaciones e integraciones > Acceso a la API, revoca el token antiguo y genera uno nuevo.
Las solicitudes devuelven 403 Forbidden
Una respuesta 403 significa que tu token está autenticado pero no tiene permiso para la operación que intentas realizar. Los tokens de Webflow se definen con alcances (scopes) al momento de su creación. No puedes añadir alcances a un token existente.
Comprueba qué alcances requiere la solicitud fallida en la referencia de la API. Las operaciones de lectura de CMS requieren cms:read. Crear o actualizar elementos requiere cms:write. La publicación requiere cms:publish.cms:readcms:write permissionsites:publish
Si al token le falta alguno de estos, revócalo y crea uno nuevo con los alcances correctos. Pueden existir hasta 5 tokens por sitio, así que puedes crear uno nuevo antes de revocar el anterior si hay integraciones activas que dependen de él.
La lista de elementos devuelve un resultado vacío a pesar de que el contenido existe en el Diseñador
La API de CMS devuelve contenido en espera de forma predeterminada. Si creaste elementos en el Diseñador pero nunca publicaste el sitio, los elementos existen, pero su campo isArchived es true. El endpoint de listar elementos los sigue devolviendo. Aparecen en la respuesta como elementos en borrador.lastPublishednull
Si la lista realmente devuelve un resultado vacío, confirma que estás usando el collectionID correcto. Ejecuta la llamada de nuevo y compara el ID de la colección con lo que ves en el panel de CMS del Diseñador de Webflow. Un error común es copiar el ID del elemento donde debería ir el ID de la colección. Ambos son cadenas hexadecimales de longitud similar.collectionIdwebflow.collections.list()displayNamesiteIdcollectionId
Además, confirma que la colección tenga al menos un elemento. Una colección nueva sin elementos devuelve una matriz vacía con total establecido en 0. Ese es un comportamiento válido, no un error.pagination.total
Los elementos creados a través de la API no aparecen en el sitio en vivo
Crear un elemento mediante createItem() lo deja en fase de preparación, pero no lo publica. El elemento existe en el CMS pero tiene un lastPublished valor de null. El sitio en vivo no lo mostrará hasta que lo publiques explícitamente.
Ejecuta la llamada publishItem con el id del elemento y, luego, recarga tu sitio en vivo. Si el elemento sigue sin aparecer, comprueba si la colección ya se ha publicado anteriormente. Una colección debe publicarse al menos una vez a nivel de sitio para que sus elementos puedan ser referenciados por otras colecciones y ser visibles en las páginas de colección.
Si realizas cambios rápidos en los elementos y recibes errores 429 de límite de tasa durante operaciones masivas, el SDK gestiona el retroceso exponencial automáticamente. Si usas fetch sin procesar, implementa tu propio bucle de reintento que lea la Retry-After cabecera de respuesta.
Qué construir a continuación con la API de CMS de Webflow
Leer y crear elementos es solo el principio. La API de CMS va más allá: actualizaciones masivas de cientos de elementos, publicaciones activadas por webhooks cuando sistemas externos envían contenido, flujos de trabajo de localización que sincronizan contenido traducido en varios idiomas y entrega de contenido en vivo mediante CDN sin llamadas adicionales a la API.
Explora la guía de CMS para obtener una referencia completa de los endpoints, que incluye operaciones masivas de elementos, especificaciones de tipos de campo y APIs de localización.
Preguntas frecuentes
¿Necesito un plan de pago de Webflow para usar la API de CMS?
No necesariamente. El plan Starter gratuito de Webflow incluye CMS (20 colecciones, 50 elementos). El plan Basic ($14/mes) es el único sin funciones de CMS; los sitios en Basic pueden autenticarse y acceder a los metadatos del sitio a través de la API, pero no tienen colecciones de CMS con las que interactuar. Los planes CMS, Business y cualquier plan con CMS habilitado funcionan perfectamente con la API de CMS.
¿Puedo crear una nueva colección de CMS a través de la API?
Sí, usando POST /v2/sites/:site_id/collections. El cuerpo de la solicitud requiere displayName y singularName. El slug y el array de campos son opcionales; si se omiten, el slug se generará automáticamente a partir del displayName. Los campos de opción necesitan un array metadata.options; los campos de referencia necesitan un metadata.collectionId. Los esquemas de colección pueden tener hasta 60 campos en total.
¿Por qué publishItem tiene éxito, pero mi elemento sigue apareciendo como borrador?
El publishItem endpoint marca el elemento como activo en tu subdominio de Webflow. Si usas un dominio personalizado y no se actualiza, confirma que tu dominio personalizado esté publicado mediante customDomains en el Publish Site payload del endpoint. La publicación en subdominios de Webflow y en dominios personalizados son objetivos distintos.
¿Qué sucede cuando alcanzo el límite de tasa?
La API devuelve un error 429 y una Retry-After cabecera que indica cuántos segundos esperar. Los planes CMS y Business tienen 120 solicitudes por minuto. El SDK de JavaScript reintenta automáticamente con retroceso exponencial. Si usas HTTP sin procesar, lee la Retry-After cabecera y espera ese tiempo antes de volver a intentarlo.
¿Puedo crear elementos sin publicar todo el sitio?
Sí. El publishItem endpoint publica elementos de colección específicos sin activar una reconstrucción completa del sitio. Usa POST /v2/collections/:collection_id/items/publish con un itemIds array. La publicación de todo el sitio mediante POST /v2/sites/:site_id/publish es una operación independiente y está limitada a una vez por minuto.
