Configurador de productos headless y guía de API
Un configurador de productos headless separa la lógica de producto de la presentación. Sitios web, tiendas ecommerce, portales de distribuidores, aplicaciones móviles y quioscos pueden ofrecer experiencias distintas mientras un único motor conectado por API controla las opciones válidas, las dimensiones, el contexto de precios, el estado guardado y la identidad transmitida a otros sistemas.
Mercado de ventas · México · MXN · IVA
Seis capas de arquitectura
Asigne responsabilidades de producto, canal y flujo de trabajo
Diez capacidades de API
Cubra la configuración desde el contexto hasta la liberación
Veinte preguntas para evaluar proveedores
Evalúe las afirmaciones API-first con evidencias
Dieciocho preguntas frecuentes detalladas
Resuelva dudas técnicas y comerciales
Definición clara
Un configurador headless ofrece las capacidades de configuración sin depender de una interfaz fija. El servicio recibe el contexto de producto, mercado, idioma, cuenta y canal; crea o recupera una configuración; evalúa los cambios solicitados; y devuelve el estado de referencia, las opciones permitidas, los valores derivados, la validación y la identidad de revisión. Cada canal decide cómo presentar el resultado.
Esto es distinto de una API de producto que solo enumera atributos. Los productos configurables incluyen dependencias, exclusiones, límites dimensionales, valores calculados y, en ocasiones, condiciones de revisión. Si cada frontend reconstruye esas relaciones, la arquitectura parece headless pero su comportamiento queda fragmentado. Un cliente podría crear en un canal un producto que otro canal, el motor de precios o la fábrica rechacen.
Headless aporta valor cuando varias experiencias necesitan el mismo motor de producto o cuando una empresa requiere control completo del frontend. También distribuye responsabilidades: los equipos de canal gestionan accesibilidad, contenido, SEO, rendimiento e interacción; los equipos de plataforma gestionan contratos, versiones, autorización, límites y observabilidad; y los responsables de producto siguen definiendo qué producto es válido y vendible.
Planificador interactivo de arquitectura
Seleccione el modelo de canal, los sistemas responsables de producto y precio, y el resultado comercial final. El planificador identifica las decisiones mínimas que deben convertirse en contratos específicos y pruebas de aceptación.
Modelo de canal
Modelo de responsabilidades
Resultado final
Patrón recomendado
Coloque una capa de orquestación de escaparate entre clientes públicos, servicios de configuración y operaciones comerciales privadas.
Mercado, moneda, cliente, inventario y contexto del carrito
Identidad de línea configurada, comportamiento de reapertura y transferencia de pago
Validez del token de precio y recuperación del estado modificado del producto
Límite explícito entre el estado válido del producto y el precio comercial contextual
Conciliación cuando cambia el contexto de configuración, promoción, impuestos o pago
Una autoridad de precio de transacción final
Línea de carrito configurada, pago e identidad del pedido con reintento seguro
Estado vencido, política de revisión de precios y confirmación del cliente
Acuse de recibo de pedido y conciliación de duplicados
Canal
Comercio electrónico
Responsabilidad
Responsabilidades compartidas con ecommerce
Resultado
Carrito + pedido
Arquitectura de referencia
Las capas pueden ser servicios o responsabilidades separados dentro de un sistema más pequeño. Lo que importa es que la propiedad y los contratos sean explícitos, mientras que cada acción posterior mantenga la misma identidad de configuración.
Propietario
Diseño, interacción, accesibilidad, contenido, localización, puntos de entrada a la cuenta y llamadas a la acción específicas del canal.
Contrato
Consume opciones permitidas, validación, estado visual, estado de precio y acciones de guardar o realizar transacciones.
Evite: Reimplementación de reglas de dependencia en cada interfaz porque la API solo devuelve listas de opciones sin formato.
Propietario
Estado de sesión, valores predeterminados, dependencias, exclusiones, dimensiones, valores derivados, validez e identidad de configuración canónica.
Contrato
Acepta el contexto más los cambios previstos; Devuelve el estado autorizado, las siguientes opciones permitidas, mensajes y revisión.
Evite: Permitir que el cliente declare válida una configuración en lugar de validar cada mutación relevante en el lado del servidor.
Propietario
Fuente de precio, moneda, mercado, grupo de clientes, cantidad, descuentos, responsabilidad fiscal, validez y estado de aprobación.
Contrato
Calcula a partir de la revisión de configuración más el contexto comercial y devuelve líneas explicables o un token de precio.
Evite: Copiar fórmulas en una interfaz, un configurador y una plataforma comercial sin autoridad nombrada ni conciliación.
Propietario
Recursos en tiempo de ejecución, enlaces de escenas, materiales, estados de la cámara, recursos AR opcionales, miniaturas e instantáneas configuradas.
Contrato
Asigna ID de productos estables y estados de configuración a activos visuales versionados e instrucciones de escena deterministas.
Evite: Devolviendo una imagen sin suficiente estado estructurado para reproducir, poner precio o continuar con el producto configurado.
Propietario
Responsabilidades sobre leads, presupuestos, carrito, pedidos, aprobaciones, proyectos, documentos y la posible transferencia a producción.
Contrato
Consume una revisión de configuración aceptada exactamente una vez y devuelve la identidad y el estado del destino duradero.
Evite: Tratar una solicitud caducada como fallida, volver a intentarlo a ciegas y crear clientes potenciales, cotizaciones o pedidos duplicados.
Propietario
Versiones de API, esquemas, credenciales, límites de velocidad, observabilidad, auditoría, publicación de catálogo, migración, desuso y recuperación.
Contrato
Publica el comportamiento admitido y hace que cada solicitud sea rastreable a través de los límites del servicio y el destino.
Evite: Envío de una API privada no documentada cuyo comportamiento cambia cada vez que cambia la interfaz original.
Contrato de la API de configuración
Estas son responsabilidades lógicas, no nombres de endpoints obligatorios. Un contrato puede combinarlos o separarlos, pero los consumidores deben saber qué envían, qué autoridad responde y qué garantía sobrevive a los reintentos, liberaciones y transferencias posteriores.
Solicitud
Mercado, idioma, canal, cuenta o rol y tiempo efectivo
Respuesta
Familias de productos, disponibilidad, puntos de entrada, etiquetas, activos y revisión de catálogo
Garantía
Solo se exponen productos publicados y permitidos para el contexto proporcionado
Solicitud
ID del producto, contexto del canal y plantilla conocida opcional o revisión guardada
Respuesta
ID de configuración, valores predeterminados, estado actual, acciones permitidas, mensajes y conjunto de versiones
Garantía
El estado devuelto es válido o está marcado explícitamente como incompleto con requisitos resolubles
Solicitud
Revisión de configuración más intención del usuario, como cambio de opción, dimensión o cantidad
Respuesta
Estado canónico aceptado, consecuencias, valores permitidos, validación y nueva revisión
Garantía
Los clientes no pueden eludir dependencias, exclusiones o restricciones dimensionales
Solicitud
Revisión de configuración y contexto comercial autorizado
Respuesta
Estado, moneda, líneas, total, procedencia, validez y requisitos de aprobación
Garantía
El resultado identifica su configuración y revisiones de fuente de cálculo.
Solicitud
Revisión de configuración, dispositivo de destino o modo visual y punto de vista solicitado
Respuesta
Manifiestos de activos, vinculaciones de nodos o materiales, transformaciones, capacidad de cámara e instantáneas
Garantía
La escena visible se asigna a la misma selección estructurada utilizada por precio y producción.
Solicitud
Revisión de configuración, identidad permitida, etiqueta y contexto de cliente opcional
Respuesta
Referencia duradera del proyecto, política de recursos compartidos, URL o token de vencimiento y continuación
Garantía
La recarga identifica si la revisión guardada es actual, histórica o necesita migración
Solicitud
Configuración aceptada, resultado de precio o token, contexto de acción de canal y cliente
Respuesta
Referencia de presupuesto, carrito o revisión, además del estado y el enlace de destino
Garantía
Los reintentos no crean duplicados no deseados y el destino conserva la identidad de configuración
Solicitud
Configuración aprobada y estado de versión designado
Respuesta
Estructura de pedido, clase de lista de materiales, archivos, documentos, acuse de recibo de destino o retención de revisión
Garantía
La salida es revisada, atribuible y no puede cambiar silenciosamente después de la publicación.
Solicitud
Acción completada con identidad de evento, objeto y organización
Respuesta
Acuse de recibo, estado de entrega o resultado del procesamiento del suscriptor
Garantía
Los eventos están autenticados, deduplicados, reproducibles por política y observables
Solicitud
Cambio de borrador autorizado, acción de validación, publicación o reversión
Respuesta
Revisiones preliminares y publicadas, objetos afectados, comprobaciones y estado de publicación
Garantía
Las API del cliente no pueden realizar administración de precios o catálogos privilegiados
Respuesta de referencia
Una respuesta útil conecta la identidad del producto, las selecciones aceptadas, los valores derivados, la validez, los siguientes pasos disponibles, el estado comercial y el historial de versiones.
{
"configurationId": "cfg_01J8P4A2",
"revision": 14,
"status": "valid",
"context": {
"product": "pergola_bioclimatic_04",
"market": "NL",
"language": "nl-NL",
"channel": "dealer-web",
"account": "dealer_havenform"
},
"selection": {
"widthMm": 4200,
"projectionMm": 3500,
"roof": "louvered",
"finish": "anthracite",
"sideScreen": true,
"ledLighting": true
},
"derived": {
"postCount": 4,
"roofBays": 2,
"areaM2": 14.7
},
"allowed": {
"projectionMm": { "min": 2500, "max": 5000, "step": 100 },
"finish": ["anthracite", "black", "white", "bronze"]
},
"messages": [],
"commercial": {
"status": "priced",
"priceResultId": "price_7K2",
"currency": "EUR",
"total": "10440.00",
"validUntil": "2026-08-26T23:59:59Z"
},
"versions": {
"api": "2026-08",
"catalogue": "PERG-EU-12.4",
"rules": "rules_perg_8.2",
"price": "DEALER-NL-8",
"visual": "scene_pergola_04@3.2.0"
},
"links": {
"self": "/configurations/cfg_01J8P4A2/revisions/14",
"continue": "/projects/cfg_01J8P4A2",
"snapshot": "/configurations/cfg_01J8P4A2/revisions/14/snapshot"
}
}Patrones de transporte y entrega
REST, GraphQL, webhooks y puentes integrados resuelven diferentes problemas de comunicación. Una arquitectura madura puede utilizar más de uno y al mismo tiempo preservar el mismo producto canónico y la misma identidad de transacción.
Adecuado para
Recursos y comandos claramente definidos para configuraciones, evaluaciones, precios, presupuestos y pedidos.
Ventaja
Semántica HTTP familiar, lecturas almacenables en caché, contratos de operación explícitos y herramientas amplias.
Controle: Evite convertir cada cambio de opción en una mutación de recurso no relacionada sin respuesta de estado canónico.
Adecuado para
Los equipos de canal necesitan acceso escrito a datos de catálogo, configuración y presentación relacionados con diferentes necesidades de campo.
Ventaja
Un esquema sólido, la introspección y la forma de respuesta seleccionada por el cliente pueden admitir diversas interfaces.
Controle: La flexibilidad de consultas no reemplaza los comandos de configuración, la autorización, los límites de costos, la revisión o la protección del flujo de negocios.
Adecuado para
Transiciones de prospectos, cotizaciones, pedidos, catálogos o estados que otros sistemas pueden procesar de forma asincrónica.
Ventaja
Desacopla la respuesta interactiva de destinos más lentos y admite múltiples suscriptores.
Controle: Firmar cargas útiles; defina el comportamiento de ordenamiento, reintento, deduplicación, repetición, mensajes no entregados y conciliación.
Adecuado para
Un lanzamiento de marca más rápido donde el configurador es dueño de su interacción pero el sitio principal proporciona contexto y recibe eventos.
Ventaja
Menos reconstrucción de front-end sin dejar de conectar acciones de identidad, análisis, cambio de tamaño, guardar y transacciones.
Controle: Esto no es completamente headless. Defina el origen entre padres e hijos, el esquema de mensajes, la navegación, el consentimiento y el comportamiento de falla.
Diseño del estado y las revisiones
Un cliente envía el cambio previsto. El servicio de configuración aplica reglas y devuelve el estado aceptado más las consecuencias. La interfaz no se convierte en un motor de reglas alternativo.
Las mutaciones hacen referencia a la revisión del estado en la que se basaron. Si otro actor o proceso cambió el proyecto, la API lo rechaza o lo concilia deliberadamente en lugar de sobrescribirlo silenciosamente.
Los productos, opciones, componentes, activos, fuentes de precios, configuraciones y resultados utilizan identificadores duraderos. Las etiquetas, los pedidos y las traducciones pueden cambiar sin interrumpir los proyectos guardados.
Un resultado puede depender de la aplicación, catálogo, reglas, precio, activo, documento y contratos de integración. Capture el conjunto relevante para que el estado pueda explicarse más adelante.
El contrato distingue estados válidos, incompletos, inválidos, que requieren revisión, sin precio y no disponibles. Un precio faltante nunca debe convertirse en cero y una advertencia no debe convertirse en una aprobación.
Las configuraciones guardadas declaran si se vuelven a abrir exactamente, migran a un nuevo catálogo, permanecen como de solo lectura o requieren revisión. La política es una decisión de producto, no un efecto secundario accidental de la API.
Modelo de seguridad de la API
Headless amplía el número de consumidores y operaciones expuestas. La autorización debe seguir los límites de organización, objeto, propiedad y acción, mientras que los controles de recursos y flujo de trabajo confidencial protegen más que las credenciales por sí solas.
Compruebe la organización, la cuenta, el proyecto y el acceso a la configuración en cada solicitud de objeto, no solo al iniciar sesión.
Devuelve sólo los campos permitidos para el rol; El margen del distribuidor, los costos internos y las notas de producción no deben filtrarse a través de esquemas amplios.
Separar la configuración pública de la administración de precios, publicación de catálogos, exportaciones y acciones de flujo de trabajo privilegiado.
Carga útil vinculada, dimensiones, costo de consulta, trabajo de renderizado, tamaño de archivo, tasa de solicitudes, recuento de sesiones y operaciones comerciales costosas.
Proteja la creación de cotizaciones, el pago, la invitación, la búsqueda de precios de cuenta y los grandes flujos de exportación contra el abuso de scripts.
Mantenga tokens de servicio privados en el lado del servidor, alcance los permisos, rote secretos y distinga las identidades del navegador, la fuerza laboral y el servicio.
Validar solicitudes y respuestas ascendentes contra contratos explícitos; Nunca confíe en las API integradas simplemente porque son internas.
Mantenga un inventario de endpoints y eventos con responsables, versiones, exposición, clases de datos, consumidores y fechas de retirada.
Secuencia de implementación
Comience con autoridad comercial y una porción vertical real. Un inventario largo de endpoints creado antes de que el producto canónico y el resultado estén claros generalmente crea más trabajo de integración, no una plataforma reutilizable.
Nombra los viajes de los clientes, las identidades, los mercados y los resultados comerciales finales. Headless es una elección de arquitectura, no un requisito en sí mismo.
Para catálogo, reglas, estado, precio, activos, cliente, carrito, pedido y producción, nombre el sistema propietario del valor aceptado.
Definir ID estables y revisiones antes de las formas de los endpoints. Incluya el estado de configuración, el contexto, la procedencia y el comportamiento histórico.
Describa las llamadas necesarias para iniciar, cambiar, validar, fijar precios, guardar, reabrir y realizar transacciones para cada canal y condición de falla.
Utilice API legibles por máquina y esquemas de carga útil, ejemplos, modelos de error, permisos, límites y política de ciclo de vida.
Conecte un producto real desde la interfaz de usuario del canal a través de reglas, precio, estado guardado y un destino. No pruebe la arquitectura únicamente con datos simulados.
Defina tiempos de espera, reintentos, idempotencia, concurrencia, falla parcial, reproducción de eventos y conciliación antes de las pruebas de carga o interrupción.
Objeto de prueba, autorización de propiedad y función más límites de carga útil, costo de consulta, latencia y falla de dependencia.
Hacer que los controles de proveedores y consumidores formen parte de las autorizaciones; probar configuraciones históricas y confirmaciones de destino.
Supervisar objetivos de servicio, seguimientos, errores, retrasos de eventos, uso de esquemas y obsolescencias. Publique rutas de migración antes de eliminar el comportamiento.
Patrones de fallo de arquitectura
El error rara vez es el protocolo en sí. Falta autoridad, identidad débil, reglas duplicadas, reintentos inseguros o un contrato que describe la sintaxis pero no el significado comercial.
La API expone productos y opciones, pero no permite transiciones, valores derivados ni validación autorizada.
Control necesario: Devuelve el estado evaluado canónico y las consecuencias de cada mutación de configuración.
El sitio web, el portal de distribuidores y la aplicación móvil ocultan o desactivan opciones de manera diferente, creando una verdad específica del canal.
Control necesario: Mantenga la validación autorizada en el servicio y devuelva permisos listos para presentación y datos de mensajes.
Cada solicitud transfiere el catálogo completo, todos los activos, campos comerciales privados y estados no relacionados.
Control necesario: Diseñe recursos limitados, permisos de campo, límites de paginación o consultas y carga de activos por etapas.
Un cliente envía etiquetas seleccionadas y espera un total sin revisión de configuración, contexto de cuenta o identidad de origen.
Control necesario: Calcular a partir de ID canónicos, revisión del estado exacto y contexto comercial explícito.
Un tiempo de espera de la red hace que el cliente vuelva a enviar y cree múltiples clientes potenciales, cotizaciones, líneas de carrito o pedidos.
Control necesario: Defina comandos comerciales idempotentes, identidad de acción duradera y conciliación de destino.
El navegador informa un error pero ningún equipo puede seguir la solicitud en la configuración, los precios y los servicios de destino.
Control necesario: Propagar identidad de correlación, eventos estructurados, temporización de servicio y códigos de error procesables.
Un campo de respuesta o un comportamiento cambia y silenciosamente interrumpe uno de varios equipos de canales independientes.
Control necesario: Publicar reglas de compatibilidad, uso del consumidor, aviso de obsolescencia, ejemplos de migración y puertas de eliminación.
La documentación omite las reglas del organización, los límites de tarifas, el ciclo de vida, la autorización o el estado histórico porque el primer consumidor compartió conocimientos tribales.
Control necesario: Trate cada contrato como un producto independiente con propietarios, ejemplos, límites y evidencia de aceptación.
Evaluación de proveedores API-first
Pregunte a cada proveedor sobre un producto, canal y resultado real. Exija esquemas, ejemplos, límites, demostraciones de fallas y evidencia versionada en lugar de aceptar "API disponible" como respuesta completa.
¿Qué servicios son realmente API-first y qué capacidades requieren la propia interfaz del proveedor?
¿Puede la API devolver las siguientes opciones permitidas, las consecuencias de las reglas y la validación, no solo los atributos del producto?
¿Qué es el objeto de configuración canónico y qué revisiones lo identifican completamente?
¿Cómo se representan los estados incompletos, no válidos, que requieren revisión, no disponibles y sin precio?
¿Pueden los sitios web, distribuidores, dispositivos móviles y salas de exposición compartir proyectos guardados sin compartir campos no autorizados?
¿Qué sistema posee el precio de lista, cuenta, mercado, descuento, impuestos y transacción final?
¿Cómo se detectan y resuelven los cambios simultáneos en una configuración guardada?
¿Se pueden reabrir las configuraciones históricas después de cambios de catálogo, regla, precio o activo?
¿Qué contratos REST, GraphQL, webhook, SDK o puente integrado están disponibles y documentados?
¿Están OpenAPI, esquema GraphQL, esquema JSON, ejemplos y modelos de error disponibles para comprobaciones automatizadas?
¿Cómo se versionan, desaprueban, miden para su uso y, finalmente, eliminan los contratos?
¿Qué límites de latencia, disponibilidad, carga útil y velocidad se aplican a cada llamada interactiva?
¿Qué sucede en el canal cuando los servicios de configuración, precios, activos o destino no están disponibles?
¿Cómo se protegen las operaciones de creación contra duplicados después de reintentos del cliente o tiempos de espera de destino?
¿Cómo se manejan las firmas de webhooks, los pedidos, los reintentos, la reproducción y los casos de mensajes no entregados?
¿Cómo se aplican y prueban los permisos de organizaciones, objetos, propiedades y funciones?
¿Qué tokens pueden existir en un navegador y qué credenciales deben permanecer en una capa del lado del servidor?
¿Pueden los seguimientos conectar una acción del cliente con los registros de configuración, precio, cotización, carrito, pedido y destino?
¿Qué contrato de consumidor, carga, seguridad y pruebas de extremo a extremo se incluyen en la evidencia de liberación?
¿Quién es el propietario de la accesibilidad frontend, SEO, análisis, actualizaciones y soporte cuando la experiencia está personalizada?
Referencias principales de arquitectura
Estas fuentes definen descripciones de API ampliamente utilizadas, validación de carga útil, esquemas de consulta, seguridad de API, comercio headless y principios componibles. No definen las reglas ni la propiedad de su producto; esos siguen siendo requisitos específicos del negocio.
El estándar independiente del lenguaje para describir las capacidades de la API HTTP para que las personas y el software puedan comprender un servicio sin leer su código fuente.
La especificación de esquema JSON publicada actualmente para describir y validar la estructura y las restricciones de la instancia JSON.
El recurso oficial GraphQL explica su esquema fuertemente tipado, respuestas predecibles, introspección y modelo de consulta.
El Proyecto de seguridad API de OWASP cubre la autorización de objetos y propiedades, el consumo de recursos, los flujos sensibles, el inventario y el consumo inseguro de API.
La documentación oficial headless de Shopify muestra cómo las capacidades comerciales pueden ofrecer experiencias web, de aplicaciones y otras experiencias personalizadas de escaparates a través de una API.
La Alianza MACH describe una arquitectura abierta, componible y conectada a través de API transparentes, capacidades headless y componentes que evolucionan de forma independiente.
Preguntas frecuentes sobre configuradores de productos headless
Continuar la arquitectura
Defina el límite de API entre el estado de configuración gobernado, las definiciones de productos aceptadas, los eventos de subprocesos digitales y los gemelos operativos sincronizados.
Abrir guíaSepare la federación humana, las identidades de servicio, la membresía de organizaciones, los roles y la autorización de objetos en canales headless.
Abrir guíaAsigne propiedad de CRM, ERP, comercio electrónico, PIM, precios, cotizaciones, BOM y análisis en todo el flujo de trabajo.
Abrir guíaTraiga un canal y un producto reales