Referencia de la API JavaScript (V3)

Última actualización: 20. octubre 2026

Esta referencia describe cada método, cada evento y cada ajuste que el motor de frontend V3 pone a disposición en window.Configento, con firma, valor devuelto, casos de error y un breve ejemplo. Está dirigida a desarrolladores de temas de tienda, plugins e integraciones propias. Cómo resolver tareas habituales y migrar desde código Legacy lo muestra la guía Interfaz JavaScript (V3).

Las firmas están escritas en notación TypeScript. Todo funciona también en JavaScript puro.

Ciclo de vida

La página carga https://cloud.configento.app/configento-v3/configento.js (con defer).
El script crea window.Configento, busca una sola vez todos los elementos con data-configento y registra una instancia para cada uno. Su id es el id del elemento o, si no lo tiene, configento-anon-<n>.
Para cada instancia empieza de inmediato la carga del componente (o se usa el componente incrustado, véase component).
En cuanto un componente se ha cargado, su instancia recibe los métodos de abajo. Antes, lanzan Configento instance not ready — await Configento.ready first.
Configento.ready se cumple cuando se han cargado todas las instancias de la página.

Los elementos que llegan a la página después del paso 2 no se reconocen. Una referencia a una instancia sigue siendo válida durante la carga: si obtiene Configento.instances.get(id) antes de ready, el mismo objeto recibe después los métodos reales.

Global: `window.Configento`

Propiedad / método	Tipo	Descripción
`version`	`string`	Versión del motor, p. ej. `3.0.0-alpha.0`
`frontendVersionTag`	`'v3'`	Identificador de la generación del motor. Compruebe este valor, no `version`, si su código solo funciona con una generación.
`ready`	`Promise<void>`	Se cumple cuando se han cargado todas las instancias
`instances`	`ReadonlyMap<string, ConfiguratorInstance>`	Todas las instancias, con el `id` de la instancia como clave
`first()`	`ConfiguratorInstance` o `null`	La primera instancia de la página
`forElement(el)`	`(el) => ConfiguratorInstance` (o `null`); `el` es un `HTMLElement` o un `string`	La instancia de un elemento o selector CSS; también busca hacia fuera (`closest('[data-configento]')`)
`loadAsset(id, opts?)`	`(id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload>`	Lee una configuración guardada; consulte Guardar y cargar
`setModalAdapter(adapter?)`	`(adapter?: ModalAdapter) => void`	Ventana propia para las vistas ampliadas de imágenes; consulte Adaptador de ventana modal
`CloudError`	Clase	Clase de error de `storeAsset()` y `loadAsset()`; consulte CloudError

window.addEventListener('DOMContentLoaded', async () => {
  await Configento.ready;
  const k = Configento.forElement('#product-form');
});

Instancia: `ConfiguratorInstance`

Propiedades (solo lectura):

Propiedad	Tipo	Descripción
`id`	`string`	`id` de la instancia
`componentId`	`string` o `null`	ID del componente
`element`	`HTMLElement`	El elemento con `data-configento`
`config`	`WebshopConfig` o `null`	Los ajustes al cargar, congelados; consulte Integración

Las características se indican por su nombre interno (string) o su ID numérico (CharacteristicRef), y los valores por el campo Valor (string) o su ID numérico (ValueRef). Un nombre desconocido, un valor desconocido o un tipo de dato inadecuado lanza un Error.

Leer

`getValue(characteristic): unknown`

Valor de una característica en la forma en que lo ven también las fórmulas:

Característica	Resultado	Vacío
Selección, botones de radio, lista con imágenes	Campo Valor de la entrada elegida (sin valor: su ID)	`null`
Selección múltiple, casilla de verificación	Lista de valores	`[]`
Campos de entrada	Texto, sin espacios al principio ni al final	`''`
Selección múltiple con cantidades	`{ [ID de valor]: cantidad }`	`{}`
Fórmula, lista de precios, combinación, atributo de producto, servicio web	Resultado del cálculo	`null`

Una característica que una regla oculta siempre devuelve «vacío».

k.getValue('anchura');     // → '120'
k.getValue('accesorios');  // → ['manivela', 'mando_a_distancia']

`getSelections(): SelectionsMap`

La selección actual de todas las características como { [ID de característica]: selección }; consulte Selección. Faltan las características que una regla oculta; los valores bloqueados se eliminan.

`getState(): ConfiguratorSnapshot`

{
  selections: SelectionsMap;                     // como getSelections()
  evaluated: Record<number, number | string | null>;  // resultados de todos los cálculos por ID de característica
  hiddenCharacteristics: number[];               // características ocultadas por reglas
  blacklistedValues: number[];                   // valores bloqueados por reglas
  price: PriceSnapshot;                          // como getPriceBreakdown()
}

Simple consulta: puede llamarse tantas veces como se quiera.

`getPriceBreakdown(): PriceSnapshot`

{ total: number; currency: string; priceIncludesTax: boolean }

total ya está convertido al tipo impositivo y a la moneda de la tienda (data-configento-tax-rate, data-configento-currency).

`getSummary(opts?): string`

Opción	Predeterminado	Efecto
`format`	`'text'`	`'html'` devuelve `<dl><dt>Característica</dt><dd>Valor</dd>…</dl>`
`includePrices`	`false`	Recargo detrás del valor
`separator`	`'; '`	Separador en formato de texto

Contiene solo las características visibles. Si el componente muestra la referencia combinada en el resumen, aparece al final.

k.getSummary({ format: 'html', includePrices: true });

`getCombinedSku(): string`

Referencia del producto configurado a partir de los números de artículo de los valores elegidos, unidos con -, p. ej. CL-W-GR-TXT. Por cada característica, en el orden del componente: el número de artículo del valor elegido (en una selección múltiple, el primero disponible) o, si no, el de la característica. Las partes vacías se omiten y las características ocultas no cuentan. '' si nada lleva número de artículo. Si no está vacía, figura también como _combined_sku en cada payload de pedido.

`getAssetPayload(): AssetPayload | null`

La configuración como JSON, ordenada por nombres internos: la misma forma que finalize().payload, pero sin comprobación. null mientras no haya nada seleccionado. Además de las características contiene _component_title, _locale, si procede _combined_sku y, en componentes con Captcha, altcha.

`getHeaderValue(opts?): string | null`

La misma configuración codificada en Base64 (apta para UTF-8): la forma que los plugins de tienda pasan al carrito y que Legacy tenía en el campo configurator1-header. Con opts.assets (resultado de storeCombinedImage() como { type: 'imgData', id, url, file }) se añade la lista de imágenes de la que, por ejemplo, el plugin de Magento lee la imagen del carrito.

Modificar

Método	Firma	Para
`selectValue`	`(characteristic, value) => void`; `value` puede ser `null`	Selección, botones de radio, lista con imágenes. `null` vacía la selección.
`toggleValue`	`(characteristic, value) => void`	Casilla de verificación, selección múltiple, lista con imágenes con selección múltiple
`setText`	`(characteristic, text: string) => void`	Campos de entrada
`setQuantity`	`(characteristic, value, quantity: number) => void`	Selección múltiple con cantidades; las cantidades negativas pasan a 0
`resetSelection`	`(characteristic) => void`	Todos los tipos de datos; después, las reglas pueden volver a preseleccionar la característica
`setProductAttributes`	`(attributes: Record<string, string>) => void`	Sustituye los valores de los atributos de producto, p. ej. tras un cambio de variante. También se puede llamar antes de `ready`.
`showLanguageSelect`	`() => void`	Vuelve a mostrar la selección de idioma (solo con `languageSelect` y varios idiomas); la selección se conserva

Cada cambio actúa como una entrada del cliente: reglas, fórmulas y precio se recalculan; después siguen change y, si el precio cambia, price.

Finalizar

`finalize(): Promise<FinalizeResult>`

Comprueba toda la configuración como un clic en el botón de acción y muestra los errores en la característica.

{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // solo con ok
  priceTotal: number;
  summary: string;               // texto, 1024 caracteres como máximo
  combinedImage?: string;        // PNG como URL de datos si el componente tiene una imagen combinada
}

finalize() no envía nada y después dispara el evento finalize.

Guardar y cargar

Método	Firma	Descripción
`storeAsset`	`() => Promise<{ id: string; url: string }>`	Guarda la configuración. `id` es la clave del enlace profundo y `url`, la dirección del archivo JSON guardado.
`Configento.loadAsset`	`(id, { instance? }) => Promise<AssetPayload>`	Lee una configuración guardada. Sin `instance`, se usa la primera.
`restoreFromAssetJson`	`(payload) => void`	Traslada a la instancia una configuración leída
`storeCombinedImage`	`() => Promise<{ id: string; url: string }>` (o `null`)	Guarda la imagen de producto combinada para el carrito o el pedido; `null` si el componente no tiene ninguna

Si alguien abre la página de producto con ?dl=<id> (o ?configento_asset=<id>), V3 restaura por sí mismo la configuración en el primer configurador. Para otros parámetros u otro configurador, llame usted mismo a loadAsset() y restoreFromAssetJson().

const { id } = await k.storeAsset();
const enlace = new URL(location.href);
enlace.searchParams.set('dl', id);

storeAsset() y loadAsset() necesitan los ajustes de la tienda (ID de cliente, token). Por eso, en la vista previa del admin lanzan CONFIG_MISSING. El configurador no repite por sí mismo las subidas fallidas; de lo contrario se crearían entradas duplicadas.

Grupos y asistente

Método	Firma	Descripción
`getGroups`	`() => GroupInfo[]`	Grupos mostrados, en orden; faltan los ocultados por reglas
`getActiveGroup`	`() => ActiveGroup` (o `null`)	Grupo mostrado; `null` con Sin grupos o con un solo grupo
`setActiveGroup`	`(ref, opts?: { validate?: boolean }) => Promise<boolean>`; `ref` es `number` o `string`	Cambia por ID o nombre interno. Hacia delante comprueba cada paso del camino (`validate: false` lo omite) y consulta el step guard. `true` si ha cambiado de paso.
`nextGroup`	`() => Promise<boolean>`	Como Siguiente
`prevGroup`	`() => Promise<boolean>`	Como Atrás, sin comprobación
`setStepGuard`	`(guard, opts?: { backward?: boolean }) => void`; `guard` es `StepGuard` o `null`	Comprobación propia antes del cambio

type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string };
type ActiveGroup = GroupRef & { total: number };

type StepGuard = (step: { from: GroupRef; to: GroupRef; direction: 'forward' | 'back' | 'jump' })
  => boolean | void | Array<{ characteristic: number | string; message: string }>
   | Promise<boolean | void | Array<{ characteristic: number | string; message: string }>>;

key es el nombre interno del grupo definido en el editor, e index, la posición entre los grupos mostrados. El step guard se ejecuta después de la comprobación integrada, de forma predeterminada solo hacia delante. false retiene el paso sin mensaje; una lista lo retiene y muestra cada mensaje en la característica (código de error guard). Mientras haya una promesa pendiente, Siguiente y Atrás quedan bloqueados. Si el guard lanza un error, el paso cambia de todos modos.

Además, una regla de error con «Ejecutar cuando» asistente y Tipo de error Error retiene el paso al que pertenece.

Eventos

on(event, callback) devuelve una función para darse de baja. Los listeners siguen suscritos aunque la instancia se vuelva a conectar internamente (por ejemplo, cuando llegan más tarde valores de un servicio web).

Evento	Cuándo	Contenido
`change`	Tras cada cambio de la selección	`{ selections: SelectionsMap }`, como `getSelections()`
`price`	Cuando cambian el precio total, la moneda o la base impositiva; una vez justo después de cargar	`{ total, currency, priceIncludesTax, delta }`; `delta` respecto al precio anterior
`finalize`	Cuando `finalize()` ha terminado	`FinalizeResult`
`error`	Cuando aparecen errores en la característica	`{ errors: ValidationError[] }`
`group`	Tras cada cambio del grupo mostrado, no al mostrarlo por primera vez	`{ from, to, direction }`; `to` es un `GroupRef`, `from` un `GroupRef` o `null`

onChange(callback) es la forma antigua de on('change', …) sin contenido y se eliminará.

Tipos de datos

Selección

SelectionsMap es { [ID de característica]: selección }; según el tipo de dato, una selección es:

`kind`	Campos	Características
`single`	`valueId` (`number` o `null`), `qty?: number`	Selección, botones de radio, lista con imágenes
`multi`	`valueIds: number[]`, `qtys?: { [ID de valor]: number }`	Casilla de verificación, selección múltiple
`text`	`value: string`	Campos de entrada
`quantities`	`quantities: { [ID de valor]: number }`	Selección múltiple con cantidades
`files`	`files: Array<{ id, folder, type, … }>`	Subida de archivos
`captcha`	`payload: string`	Captcha

ValidationError

{ characteristicId: number; altTitle: string; code: string; message: string }

message ya está traducido al idioma del configurador. code es uno de: required, pattern, range, length, numeric, integer, gt-zero, gte-zero, email, url, zip, phone, iban, bic, vat, code, alpha, alphanum, data, lowercase, uppercase, rule (regla de error), guard (step guard).

CloudError

storeAsset() y loadAsset() se rechazan con un Configento.CloudError: code, retryable y, en los errores HTTP, status.

`code`	Significado	`retryable`
`NO_SELECTIONS`	Todavía no se ha seleccionado nada	no
`CONFIG_MISSING`	Sin ajustes de tienda (vista previa del admin) o sin instancia	no
`HTTP_4XX`	Rechazado, p. ej. por el token o el dominio	no
`HTTP_5XX`	Error del servidor	sí
`BAD_RESPONSE`	Respuesta inesperada	no
`NETWORK`	Sin conexión, CORS, certificado	sí
`NOT_FOUND`	La configuración guardada no existe	no

try {
  await k.storeAsset();
} catch (err) {
  if (!(err instanceof Configento.CloudError)) throw err;
  if (err.retryable) programarNuevoIntento();
}

Integración: atributos y JSON

Cada ajuste se indica como atributo en el elemento con data-configento o como clave en el atributo JSON data-configento-config. Si están ambos, prevalece el JSON.

Atributo	Clave JSON	Valor
`data-component-id`	`componentId`	ID del componente; obligatorio
`data-configento-customer`	`customer`	ID de cliente
`data-configento-token`	`token`	Token de la tarjeta HTML5 (V3 Beta)
`data-configento-token-endpoint`	`tokenEndpoint`	Dirección que emite tokens de corta duración (plugins de tienda)
`data-configento-cloud-base-url`	`cloudBaseUrl`	`cloud.configento.app`
`data-configento-asset-base-url`	`assetBaseUrl`	Host de las configuraciones guardadas (plugins de tienda)
`data-configento-tax-rate`	`taxRate`	Tipo impositivo de la tienda en porcentaje
`data-configento-currency`	`currency`	Código de moneda, p. ej. `EUR`
`data-configento-currency-rates`	`currencyRates`	Tipos de cambio como JSON, p. ej. `{"CHF": 0.94}`
`data-configento-locale`	`uiLocale`	Idioma, p. ej. `de_DE`
`data-configento-content-locale`	`contentLocale`	Idioma distinto solo para los textos del componente
`data-configento-embed-mode`	`embedMode`	`storefront` (predeterminado con atributos) o `admin-preview`
`data-configento-price-mount`	`priceMount`	Selector CSS para el precio total
`data-configento-summary-mount`	`summaryMount`	Selector CSS para el resumen
`data-configento-summary-open`	`summaryOpen`	Resumen desplegado o plegado al principio
`data-configento-combined-image-mount`	`combinedImageMount`	Selector CSS para la imagen de producto combinada
`data-configento-language-select`	`languageSelect`	Selección de idioma antes del configurador
`data-configento-language-select-title`	`languageSelectTitle`	Texto sobre la selección de idioma
`data-configento-languages`	`languages`	Idiomas ofrecidos, separados por comas (JSON: lista)
`data-configento-min-height`	`minHeight`	Altura reservada durante la carga, p. ej. `640px`
`data-configento-min-height-keep`	`minHeightKeep`	Mantener la altura también después de la carga
`data-configento-wizard-nav`	`wizardNav`	`full`, `buttons` o `none`
`data-configento-component-json`	`component`	El propio componente, tal como lo devuelve `GET /api/v3/components/{id}`
–	`productAttributes`	Valores de los atributos de producto, p. ej. `{"anchura": "120"}`

Los atributos de sí/no aceptan true/false, 1/0, yes/no o el atributo sin valor para «sí». Los valores desconocidos dejan el valor predeterminado y generan una advertencia en la consola.

Visualización al integrar mediante atributos: en el modo storefront, el configurador no muestra ni el precio total ni el resumen, porque la tienda tiene los suyos. Con price-mount y summary-mount los coloca donde quiera. Si un selector no encuentra ningún elemento, esa parte no aparece en ningún sitio, en lugar de duplicarse en el configurador. summary-open solo funciona junto con summary-mount; allí el resumen empieza desplegado de forma predeterminada.

Adaptador de ventana modal

interface ModalAdapter {
  openOverlay(args: { title: string; container: HTMLElement; onClose: () => void }): { close(): void };
}

El configurador rellena container después de que openOverlay retorne. Su adaptador lo inserta en una ventana propia y llama a onClose() cuando el cliente la cierra. El configurador llama a close() cuando cierra la ventana por sí mismo (p. ej. tras la selección). Establezca el adaptador en cuanto exista window.Configento y antes de que se abra una ventana; setModalAdapter() sin argumento restablece la ventana integrada.

Script de compatibilidad

https://cloud.configento.app/configento-v3/configento-compat.js, cargado antes de configento.js, traslada los objetos globales del motor Legacy (Justselling_Configento_App_*, CONFIGENTO_PRODUCT.setPrice, los eventos configentoUpdate…InDom…) a esta interfaz. Qué asume en detalle y cómo reescribir el código antiguo se explica en la guía, en Migrar desde Legacy.

Versiones y compromisos

Configento.version sigue el Semantic Versioning. Hasta la versión 3.0.0 aún pueden cambiar los textos de error y pequeños detalles; los métodos y tipos de datos de esta página se mantienen. A partir de 3.0.0: las correcciones de errores cambian la última cifra, las nuevas funciones la del medio, y solo una nueva primera cifra rompe el código existente, con instrucciones de migración.

Confíe en los métodos, eventos y tipos de datos de esta página, no en las clases CSS ni en la estructura DOM del configurador. Solo son estables los atributos data-configento-char-id, data-configento-group-id y data-configento-group-key.

Próximos pasos

Interfaz JavaScript (V3): guía con ejemplos
Integración fragmento HTML
Subidas y enlaces profundos
Motor de frontend: Legacy o V3

← Todos los artículos Prueba gratuita 14 días