«Headless» se usa como si desacoplar tu escaparate del backend de commerce fuera siempre la decisión correcta. No lo es. Pero cuando sí lo es —una app móvil a medida, un sitio centrado en el contenido donde el CMS dirige la experiencia, un quiosco en tienda física o un escaparate con patrones de interacción que ninguna plantilla puede expresar— necesitas un backend que trate su API como un producto de primera clase, y no como una idea de última hora acoplada a un monolito. Dirora está construido así: las mismas operaciones que dan vida al panel de administración y al escaparate por defecto se exponen a través de una API REST limpia, de modo que puedes componer el commerce en cualquier superficie que estés creando.
Esta guía está escrita para el ingeniero que sopesa esa decisión. Cubriremos cómo se organiza la API, cómo funcionan la autenticación y la multitenencia, los bloques prácticos de construcción (catálogo, carrito, pago, webhooks) y —igual de importante— cuándo no deberías optar por headless y sí apoyarte en el escaparate integrado.
Qué significa realmente «API-first» aquí
API-first es un compromiso arquitectónico, no una etiqueta de marketing. Significa que cada capacidad se diseña primero como un endpoint de la API, y las interfaces de usuario son consumidoras de ese mismo contrato. En la práctica, esto te da tres propiedades que importan cuando construyes sobre una plataforma:
Paridad. Si el administrador puede hacerlo, tu integración también. Nunca te quedas bloqueado porque una función «solo existe en la interfaz».
Estabilidad. Como los propios front-ends de la plataforma dependen de la API, los cambios que rompen compatibilidad también nos salen caros a nosotros, lo que alinea nuestros incentivos con los tuyos.
Componibilidad. Puedes adoptar una sola pieza (por ejemplo, datos de producto de solo lectura para un sitio de marketing) sin rehacer el pago, y crecer hacia más partes de la API con el tiempo.
Bajo el capó, Dirora ejecuta un backend en Go de alto rendimiento detrás de esa API, así que los endpoints con muchas lecturas —listados de productos, búsqueda, páginas de colección— se mantienen rápidos bajo carga. Si te interesa cómo está estructurada la plataforma por dentro, hemos escrito sobre cómo construimos nuestra arquitectura de microservicios y cómo gestionamos la multitenencia.
Cuándo merece la pena el headless y cuándo no
Optar por headless te da control total sobre la capa de presentación. También te traspasa responsabilidades que el escaparate integrado gestiona gratis: renderizado en el servidor para el SEO, optimización de imágenes, datos estructurados, caché, accesibilidad y la larga cola de casos límite del carrito y el pago. Sé honesto sobre el intercambio.
El headless suele merecer la pena cuando: vas a lanzar una app móvil nativa; ya operas una plataforma de contenido y quieres integrar el commerce en ella; tienes requisitos de diseño o de interacción que un tema realmente no puede cumplir; o estás integrando el commerce en un producto existente donde el escaparate es solo una superficie más entre muchas.
El headless suele ser la decisión equivocada cuando: quieres una tienda atractiva, rápida y compatible con el SEO, y recurres al headless principalmente por «flexibilidad». El escaparate por defecto de Dirora ya incluye renderizado en el servidor, optimización automática de imágenes y datos estructurados, y el Editor Visual de Temas te permite personalizarlo a fondo —diseño de arrastrar y soltar, vista previa en vivo, historial de deshacer/rehacer y 41 widgets de escaparate— sin tocar la API en absoluto. Si no necesitas un front-end a medida, no lo construyas. También puedes combinar ambos enfoques: usa el escaparate estándar para tu tienda y recurre a la API solo para superficies satélite como una app o una integración con un partner.
Autenticación y multitenencia
Las peticiones autenticadas usan tokens de tipo bearer, y cada petición se limita a un único tenant, de modo que los datos de una tienda quedan aislados de los de otra. Los endpoints públicos de solo lectura —listados de productos, páginas de colección— están diseñados para llamarse sin autenticación, que es justo lo que quieres para un escaparate que muestra datos del catálogo a visitantes anónimos. Las operaciones de escritura y cualquier cosa específica del cliente requieren un token.
Trata las credenciales como tratarías cualquier secreto: mantén los tokens del lado del servidor en el servidor, nunca incluyas claves con privilegios en los paquetes del lado del cliente y usa los endpoints públicos de lectura para todo lo que se ejecute en el navegador. Si estás creando un front-end que además necesita escribir (añadir al carrito, hacer pedidos), enruta esas llamadas a través de tu propio backend-for-frontend para que las credenciales sensibles nunca salgan de tu infraestructura.
El catálogo: productos, colecciones y búsqueda
El lado de lectura es donde empiezan la mayoría de los proyectos headless. Puedes obtener productos con sus variantes, imágenes, precios y estado de inventario, y paginar por colecciones con filtrado. Como estos endpoints son públicos y compatibles con la caché, encajan bien con páginas generadas de forma estática o renderizadas en el servidor que necesitan ser rápidas e indexables.
Unas cuantas notas prácticas. La multidivisa y el multiidioma son de primera clase: si tu tienda vende en varios mercados, solicita el idioma y la divisa que necesitas en lugar de convertir en el cliente, para que los precios y los textos sean coherentes con lo que cobrará el pago. Si estás poblando un catálogo para desarrollar contra él, el importador de productos por CSV puede traer un catálogo existente desde Shopify, Etsy, Big Cartel, Gumroad o Sellfy, que es una forma más rápida de conseguir datos realistas que crear fixtures a mano. Y si la búsqueda es central en tu experiencia, usa el endpoint de búsqueda en lugar de traerlo todo y filtrar en el cliente.
Carrito, pago y pagos
El flujo de carrito y pago puede dirigirse de forma programática: crear un carrito, añadir y actualizar líneas de artículo, aplicar descuentos y avanzar hasta el pago tanto para clientes invitados como registrados. Los pagos se procesan a través de Stripe, así que una implementación headless hereda las mismas capacidades que el escaparate estándar: tarjetas a tarifas estándar sin recargo, Apple Pay, Google Pay y compra ahora y paga después con Klarna y Clearpay, con PayPal también disponible. Los abonos llegan en un plazo de dos a siete días.
Un dato en torno al cual conviene diseñar: Dirora no cobra comisiones por transacción en ningún plan. Lo único que se lleva es una pequeña comisión de plataforma que disminuye a medida que creces: un 1,5 % en el plan gratuito Starter, un 0,75 % en Pro, un 0,25 % en Business y un 0 % en Enterprise. En una implementación headless donde ya estás invirtiendo tiempo de ingeniería, merece la pena comprobar exactamente qué se lleva una plataforma de cada pedido antes de comprometerte; desglosamos las normas del sector en qué porcentaje se llevan las plataformas de ecommerce.
Webhooks: reaccionar a eventos en tiempo real
Sondear una API para averiguar si ha ocurrido algo es un desperdicio y es lento. Los webhooks lo invierten: te suscribes a eventos —pedido creado, pago completado, inventario bajo y similares— y Dirora envía una petición a tu endpoint cuando ocurren. Así es como mantienes sincronizados un sistema de almacén, un CRM, una herramienta de contabilidad o un proveedor de fulfilment sin un flujo constante de peticiones.
Construye tu receptor de forma defensiva. Verifica la firma del payload para actuar solo ante eventos genuinos, responde rápido (haz el trabajo pesado de forma asíncrona tras confirmar la recepción) y haz que los manejadores sean idempotentes: las redes reintentan, y no quieres que una entrega duplicada cree dos envíos. Si prefieres usar un conector existente en lugar de escribir tu propio receptor, el directorio de integraciones y el creciente ecosistema de apps ya cubren muchas herramientas habituales.
Límites de tasa, rendimiento y salida a producción
El acceso a la API está incluido en todos los planes con límites de tasa razonables; las integraciones de gran volumen en Enterprise pueden acordar techos más altos. Diseña como si los límites existieran incluso cuando estés lejos de alcanzarlos: cachea las lecturas del catálogo, aplica retroceso y reintentos ante errores transitorios y agrupa en lotes cuando la API lo permita. Te mantiene con buen comportamiento ahora y te ahorra una reescritura cuando crezca el tráfico.
Dos cosas más que los equipos headless suelen subestimar. Primero, el rendimiento es tarea tuya una vez que eres dueño del front-end: el escaparate por defecto de la plataforma viene optimizado de fábrica, pero los Core Web Vitals de tu app a medida corren de tu cuenta, así que nuestras notas sobre optimización del rendimiento de la tienda aplican directamente. Segundo, los dominios y el SSL siguen necesitando gestión: Dirora admite dominios personalizados con SSL automático, y si vas a apuntar un front-end headless a un subdominio o al dominio raíz, nuestra guía de dominios personalizados y SSL recorre la parte de DNS.
Una recomendación pragmática
La mayoría de las tiendas no necesitan ser headless, y recurrir a ello por defecto cambia semanas de ingeniería por una flexibilidad que quizá nunca uses. El patrón más sólido que vemos es el híbrido: usa el escaparate estándar con SSR para tu tienda principal —rápido, indexable y mantenido por nosotros— y recurre a la API para las superficies que realmente lo necesitan, como una app móvil, un quiosco o una integración con otro producto. Así la API se gana su sitio justo donde el código a medida aporta valor, y la plataforma se encarga de las partes que son iguales para todos. Si todavía estás decidiendo dónde construir, nuestra comparativa honesta de plataformas es un buen punto para valorarlo.
Preguntas frecuentes
¿Necesito optar por headless para construir sobre la API de Dirora?
No. La API está disponible en todos los planes y puedes usarla junto al escaparate estándar —para una app móvil, una integración o una sincronización de datos— sin sustituir tu front-end. El headless completo (aportar tu propio escaparate) es una opción, no un requisito.
¿Qué puede hacer realmente la API de Dirora?
Como Dirora es API-first, la API refleja el administrador: leer datos del catálogo (productos, variantes, colecciones, búsqueda), dirigir carritos y pago, y suscribirse a eventos de webhook para pedidos, pagos e inventario. Si una capacidad existe en el panel, está diseñada para ser accesible a través de la API.
¿Un escaparate headless seguirá siendo bueno para el SEO?
Puede serlo, pero el SEO pasa a ser tu responsabilidad. El escaparate integrado de Dirora incluye renderizado en el servidor, datos estructurados y optimización de imágenes por defecto; un front-end a medida tiene que implementarlos por su cuenta. Si el SEO es una prioridad y no tienes una razón concreta para ir headless, el escaparate estándar suele ser la opción más segura.
¿Hay comisiones por transacción en los pedidos gestionados vía API?
No. No hay comisiones por transacción en ningún plan, tanto si un pedido se realiza a través del escaparate estándar como de tu propio front-end headless. Lo único que se lleva es una pequeña comisión de plataforma que baja del 1,5 % en el plan gratuito al 0 % en Enterprise.
¿Cómo mantengo sincronizados los sistemas externos con mi tienda?
Usa webhooks. Suscríbete a eventos como pedido creado, pago completado e inventario bajo, y envíalos a tu almacén, CRM o herramienta de contabilidad. Verifica la firma, responde rápido y haz que tus manejadores sean idempotentes para que las entregas reintentadas no provoquen acciones duplicadas.