Integrar complementos de producto

Usa esta referencia para las modificaciones de plantillas del tema, los adaptadores de almacenamiento, las traducciones, POM Composite, Bookings, Subscriptions, los precios por país, los botones de pago y los puntos de extensión PHP específicos de POM.

Modifica las plantillas del escaparate de forma segura

Los formularios clásicos y el bloque Add to Cart with Options de WooCommerce usan las mismas plantillas PHP. Copia únicamente la plantilla necesaria al tema hijo activo conservando su ruta relativa, tal como se indica a continuación:

your-child-theme/woocommerce-product-addons/pom/

Por ejemplo:

your-child-theme/woocommerce-product-addons/pom/addons/checkbox.php

El directorio específico pom evita que se cargue una modificación de una extensión oficial antigua con el formato de solicitud por UUID de POM. Los archivos del tema hijo tienen prioridad sobre los del tema padre; el archivo incluido de POM es la alternativa.

Las plantillas disponibles son product-add-ons.php, group.php, field-start.php, field-end.php y estos archivos bajo addons/: checkbox.php, radiobutton.php, image.php, select.php, choice-list.php, custom-text.php, custom-textarea.php, file-upload.php, custom-price.php, input-multiplier.php y datepicker.php.

Compara la versión del encabezado de una plantilla copiada y las variables declaradas después de cada actualización de POM Tweaks. Conserva:

• los atributos de entrada basados en UUID name y value, así como pom_pao_nonce;
• .pom-pao-priced-control, los atributos de datos de campo y la clase form-control;
• las etiquetas asociadas, las descripciones, aria-describedby y el destino del error de campo;
• el contexto de edición firmado y los contratos de restablecimiento de archivo o fecha;
• el escapado apropiado para cada contexto: esc_html() para texto, esc_attr() para atributos, esc_url() para URL y POM_Tweaks_Product_Addons_Schema::sanitize_description() para HTML de descripción, y wp_kses_post() para HTML de etiqueta de precio aprobado. Las modificaciones de descripción deben conservar la política de formato restringido descrita en Formato de descripciones y desgloses de precios.

Las variables de plantilla son datos de presentación en bruto, no marcado de confianza. $product es un WC_Product; $frontend_model, $context, $field, $addon y $options contienen datos resueltos; $current_value y los valores por defecto contienen valores restaurados o verificados mediante nonce. Nunca imprimas un objeto ni una matriz en bruto, construyas una ruta de plantilla anidada arbitraria ni coloques una URL de archivo previa en una entrada de archivo.

Añade marcado alrededor de las secciones renderizadas

POM proporciona acciones estables alrededor de cada límite de renderizado:

Estas acciones pertenecen al cargador, por lo que modificar una plantilla de control no elimina los puntos de extensión circundantes. POM también emite las acciones oficiales admitidas documentadas en Compatibilidad con los complementos de producto oficiales.

Integra el almacenamiento privado de archivos

POM almacena las subidas locales fuera de la raíz pública de documentos. Un adaptador de almacenamiento de objetos debe implementar la subida, la descarga autorizada, el estado y el borrado como un único ciclo de vida:

No registres rutas temporales, registros privados, nombres de archivo, valores de clientes ni URL firmadas. Las URL de descarga deben ser de corta duración y estar limitadas al objeto; POM comprueba el carrito, el pedido, la clave de invitado o la autorización de gestión antes de solicitar una al adaptador. Mantén las copias de seguridad de la base de datos y del almacén de objetos en el mismo punto de recuperación y prueba el borrado, la restauración, el borrado por privacidad y la separación multisitio.

pom_tweaks_product_addons_file_ttl ajusta la retención de archivos temporales y del carrito entre una hora y 30 días. pom_tweaks_product_addons_download_url_ttl ajusta la duración del enlace generado hasta 30 días. pom_tweaks_product_addons_erase_order_files puede conservar archivos durante el borrado de datos personales solo cuando la tienda tenga un requisito de retención legal documentado.

Abre Tools → Site Health → POM Product Add-Ons para verificar el almacenamiento de subidas. El panel muestra la disponibilidad sin revelar rutas del sistema de archivos ni claves de objeto.

Usa complementos de producto dentro de POM Composite

Cuando ambas mejoras modernas están activadas, un componente seleccionado de POM Composite puede exponer los campos de complemento de producto actuales de su producto o variación. El constructor envía la intención por UUID y el servidor resuelve la definición completa antes de cotizar y añadir la configuración.

El composite es el propietario de los precios finales de la línea principal y de las líneas de componentes. Product Add-Ons proporciona una instantánea validada y un recargo para el componente real; el composite incluye ese importe una sola vez y evita que el ajuste de precio normal de Product Add-Ons lo cargue de nuevo.

Las subidas de archivos no son compatibles dentro de la solicitud JSON del composite. Los multiplicadores de personas y bloques de Bookings tampoco están disponibles allí, porque los valores autoritativos de la reserva están ausentes de la solicitud de cotización. Un componente configurado directamente con cualquiera de esos requisitos no puede guardarse; un componente descubierto dinámicamente no está disponible y es rechazado por los servicios de cotización y carrito.

Las integraciones de contenedores PHP pueden inspeccionar pom_tweaks_product_addons_component_contract y llamar a pom_tweaks_product_addons_prepare_component. Conserva la instantánea devuelta y el total del servidor. Los clientes remotos deben usar el endpoint de cotización de POM Composite en lugar de invocar hooks de PHP.

Para consultar el flujo completo de construcción, cotización, carrito y pedido, consulta Construir productos de POM Composite.

Bookings, Subscriptions e integraciones de precios

• Los multiplicadores de personas y de bloques o noches de WooCommerce Bookings se aplican solo cuando sus ajustes de campo están activados. Las tarifas fijas siguen siendo cargos de línea únicos.
• WooCommerce Subscriptions usa la política de cargo guardada para las fases inicial, de cambio, recurrente y de renovación. Las renovaciones históricas conservan su instantánea aceptada y la evidencia de precio.
• All Products for WooCommerce Subscriptions usa su plan seleccionado y la decisión wcsatt_discount_addons. Los importes de complemento protegidos quedan fuera de una modificación de plan cuando el contrato oficial lo exige.
• Name Your Price se convierte en la base de producto autoritativa antes de los ajustes de Product Add-Ons, incluidos los porcentajes.
• pom_tweaks_product_addons_resolved_rate puede adaptar una tasa de servidor verificada para una integración de divisa o de precios dinámicos. La vista previa del navegador necesita una integración de cliente coincidente; una tasa suministrada por el navegador nunca es autoritativa.
• pom_tweaks_product_addons_charge_context, pom_tweaks_product_addons_order_charge_context y pom_tweaks_product_addons_coupon_discount_amount adaptan sus decisiones de servidor acotadas documentadas.

Cuando Country pricing zones está activo, las tarifas fijas, las tarifas por tramos, los precios de opciones reutilizables y los límites de precio definidos por el cliente pueden tener valores por zona. Las tarifas porcentuales siguen siendo globales y usan la base regional actual del producto o de la reserva. Las respuestas públicas exponen solo la zona aplicada y las revisiones.

Mantén Price Based on Country Pro inactivo después de que POM asuma el control. Revisa las comprobaciones de salud del sitio de precios por país antes del cambio; POM falla de forma segura cuando dos proveedores podrían convertir el mismo complemento.

Para los cambios de país del cliente, la evidencia de la Store API, las renovaciones y la verificación de extremo a extremo, consulta Comprar con precios por zona de país y Comprobar la salud y compatibilidad de las zonas de país.

Comportamiento del pago y del flujo de compra

Los botones exprés de la página de producto de Stripe, PayPal Payments, WooPayments y WooPay se ocultan cuando el producto requiere su formulario configurable. Los métodos de pago siguen disponibles en el carrito y en el pago. La opción de añadir al carrito por AJAX en el archivo se sustituye por un enlace a la página de producto para los productos configurables.

Los pedidos repetidos usan las reglas del catálogo actual, salvo que una renovación de suscripción conserve explícitamente su instantánea histórica. Consulta Persistencia de carrito y pedidos para la edición del carrito, la edición de pedidos, los reembolsos, las renovaciones y Order again.

Crea un enlace firmado de compra directa

Usa un enlace firmado cuando un cliente deba recibir un producto, un texto de complemento y un importe seleccionados por el comerciante desde un sitio web, un correo o un documento. POM Product Add-Ons debe estar activado y la extensión oficial inactiva. El producto y su configuración de complemento deben estar ya publicados y poder comprarse.

Crea el enlace con WP-CLI en la tienda de destino:

wp pomtweaks product-add-ons purchase-link --url=https://example.test --product=124 --values='{"123-0":"Custom project","123-1":"150"}'

Aquí 124 es una variación concreta del producto 123. Para un producto simple, usa su propio ID. Las claves son UUID de campo o nombres de campo de compatibilidad exactos; se acepta un prefijo opcional addon-. Los valores de selección y casilla usan UUID de opción. Los valores numéricos siguen el método de precio configurado del campo: un multiplicador de entrada de 150 a una tasa de 1 añade 150 en la divisa de la tienda. No divide automáticamente ese importe entre los pagos de la suscripción.

El comando imprime una URL completa. Cópiala sin cambios en el enlace del sitio externo. Abre el pago después de añadir el producto seleccionado y deja los demás artículos del carrito en su lugar. El comprador no necesita una sesión de carrito previa ni un inicio de sesión de administrador. La firma viaja en la URL y no depende del sitio web de origen. Los formularios configurables normales siguen requiriendo su nonce habitual.

• --quantity=1 es el valor por defecto; solo se aceptan enteros positivos.
• --expires=<timestamp> acepta una marca de tiempo Unix UTC futura. Omitirlo, o pasar 0, no crea caducidad basada en tiempo.
• Los enlaces son reutilizables. Cualquiera que tenga uno puede usarlo; no son específicos de un cliente ni de un solo uso.
• Editar el producto firmado, los valores, la cantidad o la caducidad invalida el enlace. POM también vuelve a validar las reglas actuales del catálogo y rechaza en el momento de la entrada un precio cotizado cambiado, una configuración seleccionada, una divisa, una clase de impuesto o unas condiciones de suscripción modificadas. Genera un enlace nuevo después de esos cambios.
• La configuración añadida no tiene acción de edición en el carrito. Los impuestos, envíos, descuentos, comprobaciones de stock y reglas de pago normales del pago siguen aplicándose.
• La URL está firmada, no cifrada. No incluyas información sensible del cliente en los valores de campo.
• Los enlaces pertenecen a las claves de firma del sitio emisor. Rotar la sal de autenticación de WordPress invalida los enlaces existentes; no hay ningún comando de revocación de enlaces individuales.
• Excluye de las cachés de página y de CDN las solicitudes que contengan pom_pao_buy, incluidas las cachés que de otro modo ignorarían los parámetros de consulta. POM marca las respuestas gestionadas como no almacenables en caché una vez que WordPress se carga.

Las integraciones PHP de confianza pueden llamar a POM_Tweaks_Product_Addons_Purchase_Links::create($product_or_variation_id, $values, $quantity, $expires). Devuelve la URL o WP_Error. Mantén la emisión detrás de la autorización propia de la integración y resuelve los importes en el servidor; nunca expongas un endpoint público sin firmar que firme precios arbitrarios enviados. Las subidas y los campos dependientes de reservas no son compatibles con este formato de enlace.

Para verificar un enlace, ábrelo en una sesión de navegador nueva desde una página externa. Confirma la variación, el texto, el importe y la programación de suscripción en el pago. Altera un carácter del token y confirma que la solicitud se rechaza sin añadir una línea.

Proporciona un precio base de propuesta de confianza

El filtro PHP pom_tweaks_product_addons_base_price recibe la alternativa del catálogo y los datos de confianza del artículo del carrito antes de la fijación de precios nativa de complementos. Devuelve una base numérica no negativa cuando una cotización propiedad del servidor sustituya la base del catálogo o incluya un artículo sin coste. La base resuelta pasa a formar parte de la instantánea nativa del carrito y del pedido. Las reglas de base de Booking, Name Your Price y específicas del contenedor conservan su propia precedencia.

Usa este filtro solo con datos preparados por una integración de servidor autorizada. No copies en los datos del carrito una base o un indicador de descuento suministrados por el navegador. Los ajustes de precio normales deben seguir usando las definiciones de campo o pom_tweaks_product_addons_resolved_rate.

Traduce las cadenas orientadas al cliente

Los grupos y las opciones reutilizables siguen siendo una única configuración estructural compartida. POM registra únicamente los nombres de grupo, nombres de campo, descripciones, marcadores de posición, etiquetas de opción locales y nombres y descripciones de opciones reutilizables orientados al cliente.

• Con POM Translate, ve a Translations → Other translations → Defaults.
• Con Polylang, ve a Languages → Translations y usa el grupo POM Product Add-Ons.

Cada identidad de cadena contiene el UUID de la entidad y el campo semántico. Por lo tanto, dos registros pueden compartir el mismo texto de origen y aun así tener traducciones diferentes. Editar el texto de origen mantiene las traducciones vinculadas a esa identidad semántica; clonar crea nuevos UUID y nuevas entradas de traducción.

POM Translate tiene prioridad cuando ambos proveedores contienen un valor; el valor de Polylang específico de la identidad es la alternativa. Los precios, las asignaciones, la disponibilidad y los UUID no cambian entre idiomas.

Con Polylang, el producto y los términos del idioma por defecto son la fuente estructural canónica. Las traducciones heredan las asignaciones directas y de taxonomía, los campos específicos del producto y las exclusiones, salvo que el producto traducido tenga una modificación completa explícita en Product data → Add-Ons.

Mantén el descubrimiento de asignaciones

El índice de asignaciones de ámbito del sitio descubre grupos candidatos sin escanear todos los grupos en cada solicitud de producto. Las reglas completas de inclusión, exclusión, AND y OR siguen ejecutándose para esos candidatos.

Inspecciónalo:

wp pomtweaks product-add-ons assignment-index --url=https://example.test

Reconstruye la copia derivada cuando el informe diga que no es válida:

wp pomtweaks product-add-ons assignment-index --url=https://example.test --rebuild

El comando no edita grupos, asignaciones de productos, términos ni opciones reutilizables. En multisitio, ejecútalo por separado para cada --url o --blog_id previsto.

Verifica una integración

1. Modifica un control del tema hijo, confirma que los formularios clásico y de bloque lo usan, elimina después el archivo y confirma que vuelve la alternativa incluida.
2. Registra una acción de renderizado de POM y confirma que se ejecuta una vez alrededor del límite previsto.
3. Sube, descarga, borra, restaura y elimina un archivo privado a través del ciclo de vida completo del adaptador.
4. Configura un componente de Composite con un complemento con precio y confirma que el recargo se incluye una sola vez.
5. Compara un producto de Bookings, un carrito inicial de suscripción y una renovación usando los multiplicadores y las políticas de cargo previstos.
6. Cambia de idioma y confirma que las etiquetas cambian mientras los UUID, las asignaciones y los precios permanecen estables.
7. Cambia de zona de país y confirma que los importes fijos cambian mientras las tarifas porcentuales usan la base regional del producto.
8. Ejecuta dos veces la inspección del índice de asignaciones y confirma que su suma de comprobación permanece estable cuando las asignaciones no cambian.

Solución de problemas

• Modificación del tema ignorada: confirma que el archivo está bajo woocommerce-product-addons/pom/, que el tema hijo está activo y que la extensión oficial está inactiva.
• Recargo duplicado en un contenedor: usa el contrato de preparación de componentes y conserva su instantánea devuelta en lugar de ejecutar dos veces la fijación de precios normal de línea.
• Texto sin traducir: confirma que la cadena está registrada bajo la identidad correcta y que la solicitud usa el idioma previsto.
• Error de salud del adaptador de archivos: mantén las subidas no disponibles hasta que la subida, la descarga autorizada y el borrado confirmado funcionen todos.
• Resultado de asignación obsoleto: inspecciona el índice derivado y reconstrúyelo solo si la validación informa de que no es válido.

Relacionado: Campos y precios del escaparate, Comprobaciones de salud y compatibilidad y Compatibilidad con los complementos de producto oficiales.