API de belleza para e-commerce headless
API de belleza para e-commerce headless: dónde encaja en una arquitectura composable
Si tu tienda corre sobre un stack composable, una API de belleza no es un plugin: es un servicio más. Dónde ubicar el perfil, el render y la recomendación sin romper el front.
Los equipos de e-commerce de belleza que migraron a un stack composable suelen descubrir lo mismo: los plugins de tienda que antes resolvían todo ya no aplican. Cuando el front es un framework propio y el catálogo vive en un servicio aparte, cada capacidad nueva entra como servicio. Una API de belleza para e-commerce headless sigue esa misma lógica: en lugar de instalar una extensión en la plataforma, llamas a un endpoint, recibes JSON y decides tú cómo se ve y dónde aparece.
Este artículo ordena las decisiones de arquitectura: qué capa hace qué, qué corre en el servidor y qué en el navegador, dónde guardar el perfil de belleza y cómo manejar errores sin romper la página de producto.
Las tres capas de una experiencia de belleza
Antes de dibujar la integración, conviene separar tres funciones que a menudo se confunden en una sola "solución de belleza".
Capa de perfil: entender al cliente
El cliente envía una selfie y recibe un perfil de belleza estructurado: tono y subtono de piel, tipo y condición de la piel, atributos de cabello y un nivel de confianza por campo. Es una respuesta JSON, no una interfaz. Eso es exactamente lo que necesita un front headless: el dato llega limpio y el equipo decide si se muestra como tarjeta, como paso de un quiz o como atributo invisible que alimenta otra cosa. El análisis de piel y cabello por selfie ocupa esta capa.
Una aclaración importante para el brief de producto: el perfil describe atributos visibles de una foto. No diagnostica, no trata ni sustituye a un profesional. Los textos del front deberían reflejar eso.
Capa de visualización: ver el producto aplicado
Aquí vive la prueba virtual de maquillaje. Tiene dos formas y la elección es arquitectónica, no estética. La API por foto recibe una imagen y el producto (labial o base) y devuelve la imagen renderizada, con las paletas calibradas a los productos reales de la marca dentro de un proyecto. El SDK de navegador, en acceso anticipado desde septiembre de 2026, corre en el dominio de la marca y cubre trece productos —labial, base, rubor, polvo facial, corrector de ojeras, sombra, máscara de pestañas, cejas, delineador, bronceador, contorno, iluminador y delineador de labios— más un Full Look combinado, en modo ao vivo por cámara o modo foto, con cualquier color #RRGGBB.
La diferencia práctica: la API por foto es una llamada servidor a servidor y sirve en cualquier canal, incluido WhatsApp o un CRM. El SDK es código en el cliente y el render ocurre localmente en el navegador, sin subir la imagen. El Full Look y los once productos adicionales existen solo en el SDK.
Capa de recomendación: convertir el perfil en SKU
Un perfil sin catálogo es un dato bonito sin acción. MaIA Beauty Advisor es la capa que lee el perfil y recomienda los productos de la propia marca en WhatsApp, páginas de producto y chat. No es self-serve: se entrega como proyecto junto con el equipo de B4A, porque depende de cómo esté modelado tu catálogo.
API de belleza para e-commerce headless: el diagrama mínimo
Un patrón que funciona bien en stacks composable:
- BFF (backend for frontend) como intermediario. El navegador nunca habla directo con la API de belleza. Tu BFF guarda la clave de API, agrega contexto (cliente logueado, moneda, región) y normaliza la respuesta.
- Un endpoint propio por caso de uso. En lugar de exponer el JSON crudo, publica
/perfily/try-onen tu propio dominio. Así puedes cambiar proveedor, cachear o mockear sin tocar el front. - El front consume tu contrato, no el del proveedor. Esto evita que un campo nuevo en la respuesta rompa el componente de React o el template de Vue.
- El catálogo manda. El mapeo entre el perfil y los SKU vive en tu capa de datos, junto al stock y al precio, no dentro del componente visual.
El SDK de navegador es la excepción deliberada a la regla 1: corre en el cliente por diseño, autohospedado por la marca, y por eso el equipo de front conserva control total del empaquetado y del CSS.
Decisiones que conviene cerrar antes del primer sprint
Dónde vive el perfil
Tres opciones y ninguna es universal. En la sesión (rápido, se pierde al cerrar el navegador). En la cuenta del cliente (permite reusar el perfil en email, app y tienda). En el CRM como atributos de segmentación. Lo habitual es sesión más cuenta, con sincronización al CRM cuando el cliente está logueado. Define desde el inicio la política de retención de la imagen y del perfil, y decláralo en el aviso de privacidad.
Consentimiento como componente, no como letra chica
En headless el consentimiento es un componente reutilizable: una pantalla previa a la cámara, con texto claro sobre qué se envía y qué se guarda, y un estado persistido. Hacerlo una sola vez evita que cada canal lo implemente a su manera.
Degradación elegante
¿Qué muestra la página de producto si la llamada falla o el cliente niega la cámara? La respuesta no puede ser una pantalla en blanco. Define el fallback: selector de tonos clásico, guía de color, formulario corto. La experiencia de belleza es un acelerador de decisión, no un requisito para comprar.
Confianza por campo en la lógica del front
Cada campo del perfil viene con un nivel de confianza. Úsalo: cuando la confianza es baja, muestra dos opciones de tono en vez de una, o pide una segunda foto con mejor luz. Esa regla pertenece a tu capa de negocio y debe ser configurable sin redeploy.
Cómo empezar sin comprometer el roadmap
La ventaja del modelo self-serve es que el equipo técnico puede probar antes de que exista un proyecto formal: creas una cuenta, compras créditos y obtienes una clave de API en la documentación. Un desarrollador puede tener una llamada real respondiendo en un entorno de staging en una tarde, con una selfie de prueba y curl.
Un plan razonable: sprint 1, llamada desde el BFF y contrato propio; sprint 2, componente de front con consentimiento y fallback; sprint 3, persistencia del perfil y primer uso en recomendación o en email. Recién después se discute la capa de advisor y el catálogo completo.
¿Vas a integrar belleza en un stack composable? Crea tu cuenta y tu clave de API para probar la respuesta real, o habla con el equipo si necesitas la capa de recomendación conectada a tu catálogo.
Preguntas frecuentes
¿Qué cambia al integrar una API de belleza en un stack headless frente a una plataforma tradicional?
En una plataforma tradicional sueles instalar una extensión con interfaz incluida; en headless recibes JSON y construyes la interfaz tú. Eso da control total sobre el diseño y el lugar donde aparece la experiencia, a cambio de más trabajo de front.
¿La clave de API puede ir en el navegador?
No. La recomendación es llamar la API desde tu backend o BFF y exponer un endpoint propio al front. El SDK de navegador es distinto: corre en el cliente por diseño y es autohospedado por la marca, en acceso anticipado concedido por cuenta.
¿El try-on por API renderiza un look completo?
No. La API por foto renderiza labial y base sobre la imagen enviada. Los trece productos y el Full Look existen solo en el SDK de navegador, como vista previa local en modo ao vivo por cámara o modo foto.
¿Dónde debería guardar el perfil de belleza del cliente?
Depende del caso: en sesión para una experiencia puntual, en la cuenta del cliente para reusarlo entre canales y en el CRM para segmentar. Lo más común es combinar sesión y cuenta, con una política de retención declarada en el aviso de privacidad.
¿El análisis por selfie sirve para evaluar condiciones de la piel desde el punto de vista médico?
No. MaIA Scan describe atributos visibles de una foto, como tono, subtono, tipo y condición aparente de la piel. No diagnostica, no trata ni reemplaza la consulta con un profesional.