Cómo solucionar que la API de Webflow no devuelva todos los campos de la colección

Al extraer elementos de colección de la API de Webflow, es posible que notes que faltan ciertos campos en la carga útil de la respuesta. Un campo aparece en el panel del CMS, tu aplicación Next.js enumera los elementos de la colección y la clave que esperabas no está en fieldData.

Por lo general, la API no los está eliminando. Los elementos sin un valor almacenado se devuelven sin esa clave, y fieldData se organiza por el slug del campo, no por el nombre visible. Las lecturas en vivo añaden dos brechas más, ya que /items/live solo devuelve contenido publicado y la API de entrega de contenido almacena las respuestas en caché hasta por cinco minutos.

En esta guía, crearemos un controlador de rutas en Webflow Cloud que compara el esquema de la colección con los elementos en fase de pruebas y en vivo, seguido de un normalizador que entregará a tu interfaz todos los campos del esquema en cada elemento.

¿Qué necesitas para solucionar la falta de campos de colección en la API de Webflow?

Debes confirmar que cumples con estos cinco requisitos previos:

• Un sitio de Webflow: En el plan Premium o superior, que incluye 20,000 elementos CMS y el dominio personalizado que requiere Webflow Cloud.
• Una aplicación Next.js 15 o superior: Con un directorio app para los controladores de rutas, tal como se indica en la página bring-your-own-app , ejecutándose localmente en Node.js 22 o posterior.
• npm: Webflow Cloud solo admite npm, así que comienza desde un proyecto npm con un package-lock.json.
• Un token de sitio: Con el alcance cms:read , que es todo lo que necesita este tutorial, además del ID de la colección cuyos campos faltan.
• Una terminal con curl: Para llamar a la ruta de auditoría localmente y después de la implementación.

Una vez que tengas estos requisitos previos, estarás listo para comenzar la implementación.

5 pasos para obtener todos los campos de colección de la API de Webflow en Webflow Cloud

La compilación consiste en un cliente de API compartido, una ruta de auditoría que compara el esquema de la colección con los elementos en fase de pruebas y en vivo, y un normalizador para producción. La comparación es lo primero, porque convierte el problema de "faltan campos" en una lista de slugs e IDs de elementos exactos.

1. Crea un token de sitio de solo lectura y guárdalo en Webflow Cloud

Genera un token de sitio en la configuración del sitio, bajo Aplicaciones e integraciones, y otorga solo acceso de lectura al CMS, lo que limita los daños si el token se filtra. Luego, copia el ID de la colección desde su configuración en el CMS. Si no has trabajado con tokens e IDs de colección antes, la guía de Webflow sobre la API del CMS te explicará ambos procesos.

Añade tres variables a .env.local para el trabajo local, y las mismas tres a tu entorno de Webflow Cloud.

El código en los pasos siguientes las lee exactamente como están escritas:

WEBFLOW_API_TOKEN=your_site_api_token
WEBFLOW_COLLECTION_ID=your_collection_id
AUDIT_KEY=a_long_random_string_you_generate

En Webflow Cloud, marca WEBFLOW_API_TOKEN y AUDIT_KEY como secretos. La página de variables de entorno de Webflow indica que tanto las variables secretas como las normales están disponibles durante la compilación y en tiempo de ejecución, y que los valores secretos se ocultan en los registros de compilación. Añade las variables a cada entorno en el que realices el despliegue.

2. Añade un cliente de Webflow tipado que falle de forma evidente

Escribe un pequeño asistente que todas las rutas utilicen para llamar a la API de datos. Este debe lanzar un error con el código de estado y el cuerpo de la respuesta siempre que una solicitud falle, para que un error en la petición nunca se confunda con un campo faltante.

También pagina a través de cada elemento, ya que una llamada de lista devuelve un máximo de 100, y lee el esquema de la colección desde Obtener colección, que enumera el slug de cada campo junto a su displayName.

Guarda este archivo como lib/webflow.ts en la raíz del proyecto:

// lib/webflow.ts
export const API_BASE = 'https://api.webflow.com/v2';
export const CDN_BASE = 'https://api-cdn.webflow.com/v2';

export type SchemaField = {
  id: string;
  slug: string;
  displayName: string;
  type: string;
};

export type CollectionItem = {
  id: string;
  fieldData: Record<string, unknown>;
};

export async function webflowGet<T>(base: string, path: string): Promise<T> {
  const token = process.env.WEBFLOW_API_TOKEN;
  if (!token) {
    throw new Error('WEBFLOW_API_TOKEN is not set for this environment');
  }

  const res = await fetch(`${base}${path}`, {
    headers: { Authorization: `Bearer ${token}`, accept: 'application/json' },
    cache: 'no-store',
  });

  if (!res.ok) {
    throw new Error(`Webflow API ${res.status} on ${path}: ${await res.text()}`);
  }
  return (await res.json()) as T;
}

export async function getSchemaFields(collectionId: string): Promise<SchemaField[]> {
  const collection = await webflowGet<{ fields: SchemaField[] }>(
    API_BASE,
    `/collections/${collectionId}`,
  );
  return collection.fields;
}

export async function listAll(base: string, path: string): Promise<CollectionItem[]> {
  const all: CollectionItem[] = [];
  const separator = path.includes('?') ? '&' : '?';
  let offset = 0;
  for (;;) {
    const page = await webflowGet<{ items: CollectionItem[]; pagination: { total: number } }>(
      base,
      `${path}${separator}limit=100&offset=${offset}`,
    );
    all.push(...page.items);
    offset += page.items.length;
    if (page.items.length === 0 || offset >= page.pagination.total) return all;
  }
}

El tipo de registro abierto para fieldData conserva todas las claves que devuelve la API, incluidos los campos añadidos a la colección después de que escribieras el tipo. Los campos de opción también incluyen validations.options en el esquema, lo cual necesitarás más adelante si un campo contiene un ID de opción.

3. Crea una ruta de auditoría que compare el esquema con cada elemento

Crea un manejador de rutas que cargue el esquema e informe de cada slug que no esté presente en el fieldData de un elemento en fase de pruebas o publicado. Omite export const runtime = 'edge', aunque la página de "bring-your-own-app" todavía te indique que lo añadas.

Webflow Cloud se ejecuta en Cloudflare Workers, pero el destino del entorno de ejecución edge de Next.js es una configuración independiente que el adaptador de OpenNext para Cloudflare no admite, por lo que la directiva interrumpe la compilación.

Coloca la ruta en app/api/fields-audit/route.ts.

Es un diagnóstico temporal, así que elimínalo una vez que la auditoría haya terminado:

// app/api/fields-audit/route.ts
import { NextResponse } from 'next/server';
import { API_BASE, getSchemaFields, listAll, type CollectionItem } from '../../../lib/webflow';

async function sha256(value: string): Promise<string> {
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
}

function findGaps(items: CollectionItem[], slugs: string[]) {
  return items
    .map((item) => ({
      id: item.id,
      missing: slugs.filter((slug) => !(slug in item.fieldData)),
    }))
    .filter((row) => row.missing.length > 0);
}

export async function GET(request: Request) {
  const expected = process.env.AUDIT_KEY;
  const provided = request.headers.get('x-audit-key') ?? '';
  if (!expected || (await sha256(provided)) !== (await sha256(expected))) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const collectionId = process.env.WEBFLOW_COLLECTION_ID;
  if (!collectionId) {
    return NextResponse.json({ error: 'WEBFLOW_COLLECTION_ID is not set' }, { status: 500 });
  }

  try {
    const fields = await getSchemaFields(collectionId);
    const slugs = fields.map((field) => field.slug);
    const staged = await listAll(API_BASE, `/collections/${collectionId}/items`);

    let live: { count: number; gaps: ReturnType<typeof findGaps> } | { error: string };
    try {
      const liveItems = await listAll(API_BASE, `/collections/${collectionId}/items/live`);
      live = { count: liveItems.length, gaps: findGaps(liveItems, slugs) };
    } catch (err) {
      live = { error: String(err) };
    }

    return NextResponse.json({
      schema: fields.map(({ slug, displayName, type }) => ({ slug, displayName, type })),
      staged: { count: staged.length, gaps: findGaps(staged, slugs) },
      live,
    });
  } catch (err) {
    return NextResponse.json({ error: String(err) }, { status: 502 });
  }
}

La comprobación de claves compara resúmenes SHA-256, lo que oculta la longitud de la clave y funciona igual bajo next dev y en Workers, a diferencia de crypto.subtle.timingSafeEqual. La auditoría lee los elementos publicados desde api.webflow.com en lugar del host de entrega en caché, por lo que siempre muestra lo que está publicado en ese momento.

Ejecución de la auditoría local

Inicia el servidor de desarrollo con npm run dev, exporta la misma clave en una segunda terminal (export AUDIT_KEY=your_value), y llama a la ruta:

curl -H "x-audit-key: $AUDIT_KEY" http://localhost:3000/api/fields-audit

Obtendrás el esquema junto con el ID de cada elemento que tenga carencias, indicando sus slugs faltantes. Compara el resultado con esta tabla:

Una vez que una fila coincida con tu resultado, sabrás si debes revisar tu contenido o tu propio código.

4. Normaliza los elementos para que todos los campos del esquema estén presentes

Completa cada slug del esquema en cada elemento, usando null donde la API no haya proporcionado nada. Sin esto, un elemento al que le falte una clave le entrega a tu componente undefined en lugar de un null que pueda verificar, y un front-end que espera una estructura estable se rompe con cualquier elemento que resulte estar incompleto. Normalizar en la ruta centraliza esa corrección.

Creación del normalizador de campos

Añade el normalizador como lib/normalize.ts:

// lib/normalize.ts
import type { CollectionItem, SchemaField } from './webflow';

export type NormalizedItem = {
  id: string;
  fields: Record<string, unknown>;
};

export function normalizeItem(item: CollectionItem, schema: SchemaField[]): NormalizedItem {
  const fields: Record<string, unknown> = {};
  for (const field of schema) {
    fields[field.slug] = item.fieldData[field.slug] ?? null;
  }
  return { id: item.id, fields };
}

La ruta de producción sirve elementos publicados normalizados a tu front-end. Los lee desde la API de entrega de contenido, donde las respuestas en caché no cuentan para los límites de tasa de la API de datos, y mantiene los detalles de los errores internos en los registros en lugar de en su respuesta pública.

Creación de la ruta de la API de producción

Añádela en app/api/items/route.ts:

// app/api/items/route.ts
import { NextResponse } from 'next/server';
import { CDN_BASE, getSchemaFields, listAll } from '../../../lib/webflow';
import { normalizeItem } from '../../../lib/normalize';

export async function GET() {
  const collectionId = process.env.WEBFLOW_COLLECTION_ID;
  if (!collectionId) {
    return NextResponse.json({ error: 'WEBFLOW_COLLECTION_ID is not set' }, { status: 500 });
  }

  try {
    const [schema, live] = await Promise.all([
      getSchemaFields(collectionId),
      listAll(CDN_BASE, `/collections/${collectionId}/items/live`),
    ]);
    return NextResponse.json({ items: live.map((item) => normalizeItem(item, schema)) });
  } catch (err) {
    console.error(err);
    return NextResponse.json({ error: 'Upstream request failed' }, { status: 502 });
  }
}

El endpoint en vivo devuelve solo elementos publicados, por lo que los borradores nunca llegan a tu front-end. Llamar a /api/items localmente devuelve cada elemento publicado con un conjunto idéntico de claves de esquema, y los valores faltantes llegan como null.

5. Despliega en Webflow Cloud y ejecuta la auditoría

Confirma los cuatro archivos junto con el package-lock.json de npm, y despliega la aplicación en el entorno de Webflow Cloud que contiene tus variables.

Luego, vuelve a ejecutar la auditoría contra la URL desplegada, incluyendo la ruta de montaje de la aplicación, y compárala con el resultado local para saber si el problema está en tus datos o en tu entorno:

curl -H "x-audit-key: $AUDIT_KEY" https://www.example.com/app/api/fields-audit

Cualquier código del navegador que llame a /api/items debe anteponer la ruta de montaje por sí mismo, ya que Webflow Cloud no reescribe las llamadas fetch del lado del cliente.

Añade una NEXT_PUBLIC_BASE_PATH variable configurada con tu ruta de montaje, ya que Webflow Cloud no crea ninguna, y construye la URL como ${process.env.NEXT_PUBLIC_BASE_PATH}/api/items. Una vez que la auditoría desplegada confirme la causa, elimina la ruta fields-audit.

¿Por qué desaparecen los campos de colección de las respuestas de la API de Webflow?

La falta de campos suele deberse a valores vacíos o a claves leídas por el nombre de visualización. El resto proviene de las reglas de publicación y almacenamiento en caché del endpoint en vivo, o de campos que contienen IDs en lugar del contenido que esperabas.

Un campo aparece en el panel del CMS, pero su clave falta en fieldData en algunos elementos

Causa: La auditoría enumera ese slug como ausente en algunos IDs de elementos y en otros no, lo que significa que esos elementos no tienen ningún valor almacenado para el campo. La API omite la clave en lugar de enviar un valor vacío, y sus documentos de filtro tratan una clave faltante igual que null.

Solución: Abre dos de los elementos marcados en el panel del CMS. Si el campo está en blanco allí, procesa cada elemento a través de normalizeItem para que los campos en blanco lleguen como null, y renderiza un valor de respaldo para null en tu componente.

Si el campo nunca debería estar en blanco, rellena los elementos vacíos y vuelve a ejecutar la auditoría para confirmar que esos IDs desaparecen de la lista.

Tu código lee el nombre de visualización del campo en lugar de su slug

Causa: fieldData está indexado por slug, y el esquema enumera displayName y slug por separado. Cambiar el nombre de un campo modifica su nombre de visualización pero no su slug, por lo que un componente que lee item.fieldData['Author Name'] o una clave que adivinó a partir de la etiqueta obtiene undefined en cada elemento.

Solución: Lee la matriz schema de la auditoría, busca el nombre de visualización del campo y asigna a tu componente la clave slug que aparece al lado.

El endpoint en vivo devuelve menos campos que el endpoint de prueba

Causa: /items devuelve elementos de prueba, y /items/live devuelve solo los publicados. Un slug que aparece en live.gaps pero no en staged.gaps pertenece a ediciones que aún no se han publicado.

Solución: Publica los elementos o el sitio y vuelve a ejecutar la auditoría. Si las brechas en vivo ahora coinciden con las de prueba, la causa era la publicación. Si el bloque live contiene un error en lugar de un recuento, lee primero el código de estado en el texto del error.

Los valores en vivo se retrasan respecto a las ediciones que acabas de publicar

Causa: La ruta de producción se lee a través de la Content Delivery API, que almacena las respuestas en caché durante 300 segundos, o 120 segundos en los planes Enterprise. Un campo que rellenaste hace un minuto puede seguir faltando allí mientras que la auditoría, que lee api.webflow.com, ya lo muestra.

Solución: Comprueba la cabecera de respuesta cf-cache-status en una solicitud al host de entrega. Si dice HIT, espera a que pase el tiempo de caché antes de considerar que el campo falta.

Una configuración regional secundaria devuelve valores en blanco o diferentes

Causa: Las solicitudes de lista devuelven la configuración regional principal a menos que pases un cmsLocaleId, por lo que los valores traducidos de una configuración regional secundaria nunca aparecen en una solicitud sin uno.

Solución: Obtén el cmsLocaleId de cada configuración regional de la respuesta Get Site, luego añade cmsLocaleId=<id> a las rutas de los elementos en ambas rutas y vuelve a ejecutar la auditoría para esa configuración regional.

Un campo contiene un ID o HTML en lugar del valor que esperabas

Causa: El slug está presente, pero su valor no es el que el componente esperaba. Según la referencia de tipos de campo de Webflow, un campo de Referencia devuelve un ID de elemento y un campo de Referencia múltiple devuelve una matriz de IDs. Un campo de Opción devuelve un ID de opción y un campo de Texto enriquecido devuelve HTML como una cadena de texto.

Solución: Para las referencias, obtén los elementos relacionados, crea un índice por ID de elemento y sustituye cada ID por los campos del elemento relacionado en la ruta para que el navegador no solicite la referencia. Para las opciones, busca el ID en el del esquema. Renderiza el texto enriquecido como HTML en lugar de texto sin formato.Mapvalidations.options

Qué puedes construir a continuación con la API de Webflow y Webflow Cloud

Una vez que cada elemento llega con una estructura predecible, tu colección se convierte en una fuente de datos fiable para cualquier proceso que la lea, como una sincronización programada con una base de datos o un índice de búsqueda, o un front-end creado fuera del Diseñador. Esa estructura se mantiene porque el normalizador lee el esquema en lugar de una lista de campos codificados de forma rígida.

Para obtener la lista completa de endpoints de elementos y sus parámetros, la documentación para desarrolladores de Webflow cubre la referencia de la API de CMS.