Cómo sincronizar una base de datos de Notion con el CMS de Webflow

Notion es donde muchos equipos ya escriben. Tiene el flujo de trabajo de revisión, los comentarios y las propiedades que los editores entienden. Lo que no tiene es tu sistema de diseño, tu estructura de URL o la velocidad de carga de tus páginas. Webflow sí tiene eso.

Así que el objetivo no es dejar Notion. Es permitir que la gente siga redactando donde ya lo hace y que el resultado publicado aparezca en una página de Webflow sin que nadie tenga que copiar y pegar nada.

Eso es un flujo de trabajo de contenido, y la diferencia entre uno que funciona durante un año y uno que se detiene silenciosamente reside casi por completo en cómo gestiona la segunda ejecución. Esta guía cubre la sincronización de principio a fin, incluido el cambio en la API de Notion que invalida la mayoría de los tutoriales antiguos sobre este tema.

¿Qué necesitas para sincronizar Notion con el CMS de Webflow?

Una integración de Notion con acceso a la base de datos, una colección de Webflow que controles, un token de la API de datos con acceso de escritura al CMS y un lugar donde ejecutar la sincronización. El permiso de integración es lo que la gente suele pasar por alto.

La lista completa:

• Un espacio de trabajo de Notion con una integración interna y la base de datos compartida explícitamente con ella. Una integración no ve nada hasta que alguien la conecta a esa página o base de datos específica.
• Un sitio de Webflow con una colección CMS cuyos campos controles.
• Un token de la API de datos de Webflow con acceso de escritura al CMS.
• Un lugar donde ejecutar la sincronización. Un proyecto de Webflow Cloud lo mantiene junto al sitio, con Node.js 22.13.0 o superior localmente, el requisito mínimo establecido por Webflow CLI 2.x.

Una vez que tengas esto, la sincronización depende de dos cosas: fijar la versión correcta de la API y darle memoria a la ejecución para que la segunda no duplique la primera. Aquí te explicamos cómo.

Por qué los tutoriales antiguos de Notion a Webflow ya no funcionan

Notion lanzó la versión de API 2025-09-03, que introdujo bases de datos de múltiples fuentes, y no es compatible con versiones anteriores. Todo lo escrito antes de ese cambio apunta a endpoints que ahora se comportan de forma distinta.

Los endpoints de consulta y esquema se movieron a un /v1/data_sources espacio de nombres, y esas llamadas ahora requieren un ID de fuente de datos en lugar de un ID de base de datos. Los atributos a nivel de base de datos, como el título y el icono, permanecen en /v1/databases.

La consecuencia es clara y merece la pena decirla sin rodeos: si tu integración está fijada a una versión antigua y alguien añade una segunda fuente de datos a esa base de datos, las llamadas empezarán a fallar. No gradualmente, y sin avisar durante la compilación.

Cualquier guía que te diga que llames a /v1/databases/{database_id}/query fue escrita antes de ese cambio. La llamada actual es consultar una fuente de datos, y el encabezado Notion-Version es obligatorio en cada solicitud. Fija una versión deliberadamente y consulta la referencia para ver el valor actual antes de publicar, porque ese encabezado es cómo Notion decide qué contrato estás utilizando.

Cómo es una sincronización duradera entre Notion y Webflow

Una sincronización que sobrevive es aquella que tiene memoria y un canal para las quejas. Todo lo demás en la arquitectura es puro detalle.

Dos cajas en ese diagrama separan una canalización de un script. El almacén de estado guarda la relación entre el ID de una página de Notion y el ID del elemento de Webflow que creó. Sin él, en la segunda ejecución no hay forma de saber que la página ya existe, por lo que se crea un duplicado. Una sincronización que duplica elementos en su segunda ejecución casi siempre carece de esto.

La cola de mensajes fallidos atrapa los elementos que fallaron para que alguien pueda revisarlos. La alternativa es una sincronización que se traga el error, informa que todo salió bien y deja un artículo perdido en el sitio sin que los registros indiquen cuál es. No necesitas una infraestructura de colas desde el primer día, pero sí un lugar duradero donde registrar la correspondencia de IDs y un lugar visible donde aterricen los fallos.

5 pasos para sincronizar una base de datos de Notion con el CMS de Webflow

La construcción consiste en otorgar permisos, mapear campos, realizar una consulta paginada, transformar los datos y ejecutar una inserción o actualización (upsert). La transformación es donde ocurre la mayor parte del trabajo real.

1. Comparte la base de datos y obtén el ID de la fuente de datos

Crea una integración interna en Notion y copia su token. Luego, abre la base de datos y, desde su menú, conéctala a esa integración. El token por sí solo no otorga nada, por eso una base de datos que tú puedes ver puede devolver un error 404 a la API.

A continuación, recupera la base de datos a través de la API, lee las fuentes de datos que enumera y elige la que vas a sincronizar. Guarda ese ID en la configuración en lugar de buscarlo en cada ejecución. Deberías terminar este paso con un token, un ID de fuente de datos y una solicitud de prueba que devuelva filas en lugar de un error de permisos.

2. Mapea las propiedades antes de escribir código

Primero escribe el mapeo en una tabla, porque ahí es donde reside la incompatibilidad de formatos. Los tipos de propiedad de Notion y los tipos de campo de Webflow no se corresponden uno a uno, y estas dos filas son donde suelen fallar las primeras sincronizaciones:

Aquí hay una trampa con los nombres que te puede costar toda una tarde si te pilla desprevenido. En la API de CMS de Webflow, las claves son los slugs de los campos, por lo que un campo etiquetado como "Body Copy" es body-copy. Eso es lo opuesto al webhook de envío de formularios de Webflow, donde las claves son los nombres de campo legibles por humanos. Es la misma plataforma, pero con dos convenciones distintas, así que comprueba cuál estás usando antes de escribir el mapeo.fieldDatabody-copy

3. Consulta la fuente de datos con paginación

Filtra en la consulta en lugar de hacerlo en tu propio código. Extraer todo para luego descartar la mayor parte desperdicia el límite de tasa en ambos lados, y un filtro de estado es lo que evita que los borradores a medio escribir aparezcan en el sitio.

La siguiente consulta hace ambas cosas:

// lib/notion.ts
const NOTION_VERSION = '2026-03-11'

type NotionPage = {
  id: string
  last_edited_time: string
  properties: Record<string, any>
}

export async function queryDataSource(cursor?: string) {
  const response = await fetch(
    `https://api.notion.com/v1/data_sources/${process.env.NOTION_DATA_SOURCE_ID}/query`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.NOTION_TOKEN}`,
        'Notion-Version': NOTION_VERSION,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        page_size: 100,
        start_cursor: cursor,
        filter: {
          property: 'Status',
          status: { equals: 'Published' },
        },
      }),
    }
  )

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

  return (await response.json()) as {
    results: NotionPage[]
    next_cursor: string | null
    has_more: boolean
  }
}

Notion pagina los resultados. La respuesta incluye has_more y next_cursor, y una sincronización que solo lee la primera página parece perfecta hasta que la base de datos supera las cien filas, que es exactamente el punto en el que ya nadie la está vigilando. Una ejecución correcta registra más de una obtención de página en una base de datos que tiene más de una página.has_morenext_cursor

4. Transforma el contenido a HTML

Esta es la capa de mapeo del diagrama y es donde reside la mayor parte del trabajo real. Notion devuelve el texto enriquecido como objetos estructurados con anotaciones, mientras que el campo de texto enriquecido de Webflow espera una cadena HTML, así que alguien tiene que recorrer el contenido y generar el marcado.

Mantén la conversión en un módulo independiente con sus propias pruebas. Es la parte que cambia cada vez que un editor usa un tipo de bloque que no habías previsto, y querrás que eso se muestre como un error claro en lugar de un campo vacío silencioso. El paso se completa cuando una página representativa se convierte en un HTML que estarías dispuesto a publicar.

5. Escribe en el CMS y haz que la escritura sea repetible

El punto de conexión para crear elementos toma el ID de la colección en la ruta y tus valores mapeados bajo fields:fieldData

// lib/webflow.ts
type Mapped = {
  name: string
  slug: string
  body: string
  notionId: string
}

export async function createItem(item: Mapped) {
  const response = await fetch(
    `https://api.webflow.com/v2/collections/${process.env.WEBFLOW_COLLECTION_ID}/items`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.WEBFLOW_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        isArchived: false,
        isDraft: false,
        fieldData: {
          // Keys are the field SLUGS from your collection, not the labels.
          name: item.name,
          slug: item.slug,
          'rich-text': item.body,
          'notion-id': item.notionId,
        },
      }),
    }
  )

  if (response.status === 429) {
    // Back off and retry rather than dropping the item.
    throw new Error('RATE_LIMITED')
  }

  if (!response.ok) {
    const detail = await response.text()
    throw new Error(`Webflow create failed: ${response.status} ${detail}`)
  }

  return response.json()
}

Añade un campo de texto plano a la colección para guardar el ID de la página de Notion, tal como hace este código con notion-id. Ese simple campo es el almacén de estado más barato que puedes construir: antes de crear nada, busca un elemento que tenga ese ID y actualízalo en su lugar. Esto convierte la sincronización de una operación de solo creación a una de actualización (upsert), que es lo que hace que la segunda ejecución sea segura.notion-id

Gestiona el error 429 explícitamente en lugar de tratarlo como un fallo genérico. La API de datos de Webflow impone un límite de solicitudes por minuto que varía según el plan del sitio, y la primera importación de una base de datos grande es precisamente la carga de trabajo que lo alcanza. Haz una pausa y vuelve a intentar procesar el elemento en lugar de descartarlo.

El diagrama muestra operaciones masivas hacia el CMS, que es la ruta de escalado una vez que una importación es lo suficientemente grande como para que las llamadas por elemento se conviertan en el cuello de botella. Empieza con la llamada de creación individual y pasa al procesamiento por lotes cuando el volumen lo requiera. Los elementos creados de esta manera se guardan en borrador, por lo que existen en el CMS pero no están en el sitio activo hasta que se publican, lo que te da un paso de revisión antes de que una canalización automatizada cambie una página pública.

¿Qué causa que una sincronización de Notion a Webflow falle? Consejos para solucionar problemas

Cinco fallos cubren casi todo, y cuatro de ellos son silenciosos: un problema de permisos, un mapeo de ID faltante, URL de imágenes caducadas y un slug de campo que no coincide.

Notion devuelve un error 404 para una base de datos que puedes ver

Causa: la integración no se ha conectado a ella. Tu acceso personal a la cuenta no tiene nada que ver con la API, que solo ve lo que se le ha permitido a la integración.

Solución: abre la base de datos, ve a Conexiones y añade la integración. Vuelve a ejecutar la consulta y aparecerán las filas. Vale la pena comprobar esto primero siempre que una sincronización que funcionaba deje de devolver resultados, ya que si una base de datos se duplica o se mueve en Notion, no conserva la conexión anterior.

Cada segunda sincronización duplica todo

Causa: no hay mapeo de ID. La sincronización no tiene memoria de lo que creó, así que lo vuelve a crear en la siguiente ejecución.

Solución: guarda el ID de la página de Notion en el elemento de Webflow y búscalo antes de escribir, para que la sincronización actualice en lugar de insertar. Limpia los duplicados una vez y la actualización (upsert) funcionará correctamente.

Las imágenes desaparecen aproximadamente una hora después de la sincronización

Causa: guardaste una URL de archivo de Notion en lugar del archivo. Esas URL solo son válidas durante una hora.

Solución: pasa la URL a Webflow en la misma ejecución, mientras aún sea válida; Webflow descargará y volverá a alojar la imagen para que el recurso pertenezca a tu sitio.

La compilación falla después de añadir la ruta de sincronización

Causa: una directiva export const runtime = 'edge'. Webflow Cloud despliega Next.js a través del adaptador OpenNext Cloudflare, que no es compatible con el entorno de ejecución edge de Next.js.

Solución: elimina la línea y vuelve a desplegar. Los Route Handlers ya se ejecutan en el entorno de Workers sin ella. Ten en cuenta que la propia página de "bring-your-own-app" de Webflow sigue indicando a los usuarios de Next.js que añadan la directiva, por lo que es posible que la instrucción que estás siguiendo sea la fuente del problema y no tu código.

Un campo permanece vacío sin avisar

Causa: la clave fieldData no coincide con el slug del campo. Una clave no reconocida no rellena el campo, y la respuesta no te indica qué clave era la incorrecta.

Solución: comprueba el slug en la configuración de la colección en lugar de confiar en la etiqueta, y luego vuelve a ejecutar un solo elemento para confirmar que el valor se guarda correctamente.

Qué puedes construir a continuación con Notion y Webflow Cloud

Una vez que la sincronización se ejecuta de forma programada, lo siguiente suele ser añadir un disparador: un webhook de Notion para que un cambio de estado llegue al CMS en segundos en lugar de esperar al siguiente intervalo. Guarda ambas credenciales como variables de entorno, marcadas como secretas, ya que están disponibles tanto para la compilación como para la aplicación desplegada en tiempo de ejecución.

Cualquier proceso que se ejecute sin supervisión también necesita avisarte cuando falla, y enviar una notificación a un canal es la opción más sencilla. Nuestra guía de notificaciones de Slack cubre ese patrón, incluyendo cómo verificar que un webhook entrante sea auténtico. Para las rutas de conexión que no requieren código, consulta la integración de Webflow y Notion.

Para una personalización más profunda más allá de lo que permiten esas rutas, la documentación para desarrolladores de Webflow cubre la API del CMS, los límites de tasa y el resto del entorno de ejecución de Webflow Cloud.