Cómo usar imágenes y fotografías de Unsplash en una tienda Webflow

La mayoría de las tiendas nuevas se topan con el mismo muro el primer día. Los productos están ahí y el diseño funciona, pero todo parece inacabado porque falta fotografía: no hay una imagen de estilo de vida tras el banner principal ni nada en las tarjetas de categoría. A veces, hasta la página de "Sobre nosotros" se siente vacía.

Unsplash suele ser la solución, y para una tienda Webflow es una muy buena. Lo que confunde a la gente es que la licencia y la API son dos conjuntos de reglas distintos, y la API pide cosas que la licencia no exige.

Esta guía explica qué puedes hacer con las fotografías de Unsplash en una tienda comercial y cómo realizar la integración cumpliendo con ambos conjuntos de términos.

¿Qué necesitas para usar imágenes de Unsplash en una tienda Webflow?

Necesitas una cuenta de desarrollador de Unsplash y un lugar en el servidor donde guardar la clave de acceso. La clave no puede estar en un componente del cliente, porque cualquier cosa en el paquete del navegador es pública en cuanto tu sitio se publica.

Para empezar, asegúrate de tener esto listo:

• Una cuenta de Unsplash registrada para la API, con una aplicación creada
• Tu clave de acceso, que la API espera como Client-ID encabezado de autorización
• Un sitio Webflow con la colección o las páginas que decorarán las imágenes
• Un proyecto de Webflow Cloud que ejecute una aplicación Next.js, además de Node.js 22.13.0 o superior de forma local, el requisito mínimo establecido por Webflow CLI 2.x

Toda aplicación nueva comienza en modo de demostración, algo más importante de lo que parece y que trataremos en el primer paso. Pero antes de nada, una cuestión de licencias determinará si esta integración es adecuada para tu tienda.

Qué permite hacer la licencia de Unsplash en una tienda

Las fotografías de Unsplash pueden decorar una tienda, pero no pueden ser el producto. Esa distinción separa una integración legal de un problema jurídico, y la licencia lo deja claro sin rodeos.

La Licencia de Unsplash permite el uso comercial sin necesidad de pedir permiso. Solo enumera dos cosas prohibidas: recopilar imágenes para replicar un servicio similar o competidor, y vender imágenes "sin una modificación significativa". Una tienda que venda impresiones, fondos de pantalla o paquetes descargables de fotos de Unsplash está haciendo esto último.

Obtener imágenes a través de la API añade obligaciones adicionales a la licencia, que es donde la mayoría de las integraciones dejan de cumplir las normas sin darse cuenta:

La última fila se refiere específicamente a las creaciones en Webflow. El instinto es descargar una foto, subirla a los recursos de Webflow y referenciarla como cualquier otra imagen, que es precisamente lo que las directrices te piden que no hagas.

5 pasos para añadir imágenes de Unsplash a una tienda en Webflow

La estructura utiliza un gestor de rutas que consulta a Unsplash, un campo de CMS que contiene una URL en lugar de un archivo, y un bloque de atribución en la interfaz. Aquí no se descarga ninguna foto.

Cada paso depende del anterior, así que síguelos en orden.

1. Registra la aplicación y comprende el modo de demostración

Crea una aplicación en tu cuenta de desarrollador de Unsplash y copia la clave de acceso. Lo más importante no es la clave, sino el modo: una aplicación nueva comienza en modo de demostración, y Unsplash limita las aplicaciones de prueba a 50 solicitudes por hora.

Cincuenta por hora está bien para desarrollar, pero es inútil para una tienda en vivo, ya que una sola página que realice una petición al renderizarse puede agotarlos durante tus propias pruebas. El modo de producción aumenta el límite a 1000 peticiones por hora, pero requiere una solicitud y aprobación, y esta última no es automática, sino que depende de seguir las Pautas de la API.

Prepárate para esa diferencia. Desarrolla usando el entorno de prueba, implementa una caché agresiva y solicita el acceso a producción antes de lanzar el sitio, no cuando el tráfico ya haya llegado.

Finaliza este paso con una clave de acceso y una nota clara sobre el modo en el que te encuentras, porque el error que provoca más adelante no se parece en nada a un límite de tasa.

2. Protege la clave de acceso con un Route Handler

La API de Unsplash espera la clave en un encabezado, lo que significa que la petición debe hacerse donde la clave no sea visible. Un componente de cliente no servirá, porque todo lo que importa se envía al navegador.Authorization: Client-ID

El manejador a continuación busca en Unsplash y devuelve solo lo que el front-end necesita: una URL para enlace directo, el texto alternativo, el crédito y la ubicación de descarga para más tarde. Deliberadamente, no devuelve el archivo.

Créalo en app/api/imagery/route.ts:

// app/api/imagery/route.ts
import { NextRequest, NextResponse } from 'next/server'

type UnsplashPhoto = {
  id: string
  urls: { regular: string; small: string }
  alt_description: string | null
  links: { download_location: string }
  user: { name: string; username: string }
}

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get('q')
  const key = process.env.UNSPLASH_ACCESS_KEY

  if (!key || !query) {
    return NextResponse.json({ error: 'Missing key or query' }, { status: 400 })
  }

  const res = await fetch(
    `https://api.unsplash.com/search/photos?query=${encodeURIComponent(query)}&per_page=12`,
    { headers: { Authorization: `Client-ID ${key}` } }
  )

  // Quota is reported in headers on every response, not by a status code.
  if (res.headers.get('X-Ratelimit-Remaining') === '0') {
    return NextResponse.json({ error: 'Rate limited' }, { status: 429 })
  }

  if (!res.ok) {
    return NextResponse.json({ error: 'Unsplash request failed' }, { status: 502 })
  }

  const data = (await res.json()) as { results: UnsplashPhoto[] }

  // Keep the CDN URL, never a copy of the file.
  return NextResponse.json({
    photos: data.results.map((p) => ({
      id: p.id,
      url: p.urls.regular,
      alt: p.alt_description ?? '',
      downloadLocation: p.links.download_location,
      credit: { name: p.user.name, username: p.user.username },
    })),
  })
}

Observa cómo se lee la cuota. Unsplash devuelve el estado de tu límite de tasa en los encabezados y en cada respuesta, en lugar de usar un código de estado; además, un error 403 de Unsplash significa falta de permisos, no una limitación de velocidad.X-Ratelimit-LimitX-Ratelimit-Remaining

Despliega esto y una petición de búsqueda debería devolver una lista de URLs en el dominio images.unsplash.com.

3. Almacena la URL, nunca el archivo

Este paso mantiene la integración dentro de las normas. Añade un campo de texto plano a tu colección del CMS para la URL de la imagen y otro para el crédito, en lugar de usar un campo de imagen que contenga un archivo subido.

La documentación de la API es explícita al indicar que las URLs que devuelve deben ser las que tú insertes, una práctica llamada hotlinking, para que las visualizaciones de las fotos puedan contarse y notificarse al fotógrafo. Copiar el archivo en los recursos de Webflow rompe esa cadena, aunque la licencia por sí sola lo permitiría.

Escribe el registro con el endpoint de creación de elementos, recordando que las claves fieldData son los slugs de los campos, no las etiquetas del Diseñador. Un elemento correcto contiene una URL que puedes pegar en un navegador, sin ningún archivo subido.

4. Renderiza la imagen con su atribución

Vincula la URL almacenada directamente a la fuente del elemento de imagen. Como el archivo reside en la CDN de Unsplash, obtienes su entrega y parámetros de redimensionamiento gratis, y puedes solicitar una versión más estrecha almacenando junto a ella y añadiendo parámetros como urls.raw&w=750&dpr=2, que es el método de ajuste de tamaño que especifica la documentación.

La atribución no es opcional aquí. La licencia describe el crédito como algo apreciado, pero las Pautas de la API exigen que cada aplicación atribuya al fotógrafo y a Unsplash; además, la atribución es una de las pautas que se evalúan cuando una aplicación solicita acceso a producción.

Coloca el crédito cerca de la imagen en lugar de en un pie de página que nadie lee, enlazando el perfil del fotógrafo y Unsplash, con ?utm_source=your_app_name&utm_medium=referral añadido a ambos enlaces como exigen las pautas. Cuando termines este paso, cada foto en la página tendrá una línea visible indicando quién la tomó.

5. Activa el evento de descarga cuando se elija una foto

Las pautas piden una llamada adicional sin efecto visual que es fácil pasar por alto. Cuando tu aplicación descargue una foto, activa una petición GET al endpoint download_location de la foto.

Es un contador, no una descarga. La documentación es clara al decir que es solo para seguimiento y no debe usarse para insertar la foto, así que sigue sirviendo la URL que ya almacenaste.

Añade la llamada en el momento en que alguien elige realmente una foto, por ejemplo, cuando un editor selecciona una para un producto:

// Call this when a person actually chooses a photo, not on every render.
export async function trackSelection(downloadLocation: string) {
  await fetch(downloadLocation, {
    headers: {
      Authorization: `Client-ID ${process.env.UNSPLASH_ACCESS_KEY}`,
    },
  })
  // The response carries a url field, but it is not what you embed.
  // Keep using the urls.* value you already stored.
}

Ejecutarla en cada carga de página inflaría las estadísticas del fotógrafo y agotaría tu límite de tasa. Con esto implementado, la integración cumple con las tres obligaciones de la API que definen la construcción: enlaces directos (hotlinking), atribución y seguimiento de descargas. Lee las directrices completas antes de solicitar el acceso a producción, ya que también cubren aspectos clave sobre confidencialidad y reventa.

¿Por qué fallan las imágenes de Unsplash en un sitio de Webflow?

La mayoría de los fallos se deben a cuatro motivos: un límite de tasa silencioso, un enlace directo roto, falta de atribución al momento de la aprobación y el uso de imágenes de una forma no cubierta por la licencia.

Los dos primeros parecen errores técnicos, mientras que los dos últimos pasan desapercibidos hasta que alguien más los señala:

Las imágenes dejan de cargar tras una ráfaga de pruebas

Causa: El límite del modo demo es de 50 solicitudes por hora, y se alcanza más rápido de lo esperado porque un componente realiza la petición en cada renderizado en lugar de usar caché. Solo las llamadas a la API cuentan para este límite, ya que las solicitudes de archivos de imagen al CDN no lo hacen; por lo tanto, lo que realmente se detiene es la búsqueda que devuelve las URL, no la carga de las fotos en sí.

Solución: Almacena los resultados en caché y guarda la URL elegida en el CMS para que la página se renderice sin llamar a Unsplash. Llama a la API cuando un editor elija una imagen, no cuando un visitante cargue una página. Si realmente estás a escala de producción, solicita acceso de producción, pero considera el patrón de "petición por renderizado" como el verdadero error, ya que los límites de producción son un tope, no una licencia para hacer consultas constantes.

Las imágenes se ven bien en local pero fallan en el sitio publicado

Causa: La imagen se descargó durante el desarrollo y se referenció desde una ruta local o un recurso temporal, por lo que nada funciona una vez que la aplicación se despliega. Es el mismo error que volver a alojar archivos, solo que menos intencional.

Solución: Referencia el urls.regular valor de la respuesta de la API y guarda esa cadena. Una comprobación rápida: abre el registro del CMS y pega el valor del campo en un navegador. Si no carga una foto en el CDN de Unsplash, el registro tiene el valor incorrecto y la página fallará en cuanto salga de tu equipo.

Comprueba esto en todos los registros, no solo en el que falló, porque si una compilación descargó una imagen, probablemente descargó todas, y el resto fallará en cuanto alguien visite esas páginas.

Se rechaza el acceso a producción

Causa: Falta de atribución o atribución incompleta. La aprobación depende de seguir las Directrices de la API, y es fácil pasar por alto la atribución porque la licencia hace que el crédito sea opcional.

Solución: Da crédito al fotógrafo y a Unsplash de forma visible dondequiera que aparezca una foto, incluyendo enlaces a ambos, antes de solicitar el acceso y no después de ser rechazado. Verifica también el disparador de descarga, ya que es la otra directriz que resulta invisible cuando falta y es fácil de omitir en una construcción que, por lo demás, funciona.

Los revisores miran la aplicación en funcionamiento, no tus intenciones, así que coloca el crédito en un lugar visible en una captura de pantalla y mantenlo en todas las superficies que muestren una foto, no solo en la página que esperas que revisen.

La tienda vende algo creado a partir de las fotos

Causa: La licencia permite el uso comercial, pero no la reventa. Vender una foto como impresión, paquete de fondos de pantalla o recurso descargable significa vender la imagen en sí, lo cual no está permitido por la licencia sin una modificación significativa.

Solución: Trata la fotografía de Unsplash como el envoltorio, no como el producto. Úsala para fondos, mosaicos de categorías e imágenes editoriales alrededor de lo que vendes. Si una fotografía debe ser el artículo que se añade al carrito, obtén la licencia de un proveedor de stock cuyos términos cubran la reventa, ya que ningún nivel de cumplimiento de la API cambia lo que permite la licencia.

Este es el único fallo de esta lista con consecuencias fuera de tus propios registros, así que vale la pena solucionarlo antes de lanzar la tienda, en lugar de esperar a que un fotógrafo note que su trabajo está a la venta.

Lo que puedes crear a continuación con Unsplash y Webflow

Cuando las imágenes llegan como datos en lugar de archivos subidos, gestionar la tienda es pan comido: el editor elige una foto desde el buscador en tu propia página de administración, el CMS guarda la URL y el equipo de diseño no tiene que tocar ni un solo panel de recursos.

El mismo controlador puede gestionar cualquier proveedor de medios que decidas pagar más adelante, lo cual es clave si tu catálogo supera lo que ofrece la fotografía gratuita. Si tu tienda también vende en varias regiones, nuestra guía global de comercio electrónico cubre la capa de traducción necesaria para ello.

Para colocar imágenes durante el diseño en lugar de usar una integración por API, consulta la integración de Webflow y Unsplash, que es una vía distinta con sus propias condiciones y no una excepción a las pautas anteriores.

Para una personalización más profunda que va más allá de esa opción, la documentación para desarrolladores de Webflow cubre los controladores de ruta, la API del CMS y el resto del entorno de ejecución de Webflow Cloud.