Usar la compatibilidad oficial de WooCommerce Product Add-Ons

Usa esta referencia cuando un cliente de catálogo, una integración PHP, una automatización o un webhook existentes esperen los contratos públicos de WooCommerce Product Add-Ons 8.4.1. POM expone estos contratos únicamente mientras la extensión oficial esté inactiva.

Elegir el contrato correcto

No actives ambos motores de tienda al mismo tiempo. Cuando WooCommerce Product Add-Ons esté activo, POM deja las rutas oficiales, las clases de fachada, los datos de compatibilidad de la Store API, los hooks, el manejo de formularios, los precios y los metadatos del pedido en manos de esa extensión.

Rutas REST y campos nativos del producto

Las rutas de compatibilidad requieren un administrador o un gestor de tienda:

Las rutas v1 conservan los valores escalares heredados observables, los valores de imagen en blanco, la presencia de claves de opción y los errores de validación. Las rutas v2 conservan el esquema de grupo oficial y los valores predeterminados. Las escrituras oficiales utilizan la misma validación y almacenamiento de POM que la API de gestión de POM.

Las respuestas de gestión de grupos individuales y de producto nativo incluyen un ETag seguro. Envíalo en If-Match al actualizar o eliminar. El cuerpo oficial permanece sin cambios; la cabecera añade protección de concurrencia. Una escritura obsoleta devuelve HTTP 409 y una escritura sin condición previa devuelve HTTP 428.

El esquema oficial de grupos globales solo puede representar asignaciones a todos los productos y a categorías. POM omite de la colección de grupos globales un grupo asignado únicamente a productos con nombre o a reglas avanzadas en lugar de describirlo incorrectamente. Sus campos efectivos siguen apareciendo en el campo nativo addons de ese producto y en el modelo público de producto de POM.

Funcionalidades de WooCommerce

Cuando la versión de WooCommerce instalada proporcione la API de funcionalidades (Abilities), POM registra:

• woocommerce-product-addons/get-product-add-ons
• woocommerce-product-addons/get-global-add-on-groups

Las funcionalidades son de solo lectura y usan los mismos permisos, resolución efectiva de productos, formas de campos oficiales y límites de visibilidad de grupos que sus equivalentes oficiales.

Identidades numéricas estables

POM usa UUID internamente y en su límite nativo de la Store API. Las respuestas de compatibilidad conservan además identidades enteras:

• Los ID de campos de Product Add-On permanecen estables en el REST de producto nativo, el REST de compatibilidad, las funcionalidades, los datos de compatibilidad de la Store API, las filas addons del carrito, _pao_ids, el REST de pedidos y los webhooks.
• Los ID de grupos globales siguen siendo enteros en su propio espacio de nombres oficial.
• Las opciones conservan los índices posicionales oficiales; no reciben un ID numérico separado.
• Las asignaciones tienen ámbito de sitio en multisitio. Los ID retirados no se reutilizan.

Los ID importados se reservan antes de guardar. Un ID numérico que ya pertenezca a otro UUID se rechaza en lugar de vincularse por etiqueta o reasignarse silenciosamente. Clonar crea nuevos UUID y asignaciones numéricas; conservar o vincular un UUID existente mantiene su asignación establecida.

Antes de cambiar un catálogo actualizado que ya contenía definiciones de POM, ejecuta la inspección legacy-ids descrita en Migrar desde WooCommerce Product Add-Ons.

Entrada y salida de compatibilidad de la Store API

Un cliente de la Store API compatible con el oficial puede enviar addons_configuration con ID de campos numéricos e índices posicionales de opciones. Un cliente nativo de POM envía pom_product_addons con UUID. No mezcles ambas propiedades en una misma solicitud.

Los elementos de carrito aceptados exponen el resultado compatible con el oficial extensions.addons.addons_data además del resultado de POM. Las integraciones PHP de confianza que pasan un array oficial cart_item_data['addons'] directamente a WC_Cart::add_to_cart() conservan las etiquetas, los valores, los tipos de precio, el precio del carrito y los metadatos del pedido admitidos. Ese array es información de confianza creada por el servidor, no un formato seguro para la entrada sin depurar del navegador.

Fachada PHP

Comprueba una clase antes de llamarla:

if (class_exists('WC_Product_Addons_Helper')) {
    $addons = WC_Product_Addons_Helper::get_product_addons($product_id);
}

La fachada carga una clase solo cuando PHP la solicita por primera vez.

WC_Product_Addons_Helper admite la resolución oficial de productos y padres, grupos globales, comportamiento de prioridad y exclusión, prefijos, ayudantes de visualización de precios y de modo de impuestos, comprobaciones de obligatoriedad y descripción, datos de restricciones, comprobaciones de tamaño de carga, ayudantes de fechas, valores predeterminados, generación de ID numéricos, productos con precio clonado, imágenes de marcador de posición y enlaces permanentes de carrito editables.

WC_Product_Addons_Groups, WC_Product_Addons_Global_Group y WC_Product_Addons_Product_Group admiten lecturas oficiales de grupos. Sus métodos admitidos de creación, actualización y eliminación usan la validación de POM, la protección de relaciones y la persistencia.

WC_Product_Addons_Display admite la detección de opciones, el texto y las URL de los botones de bucle, las decisiones de añadir al carrito mediante AJAX, las decisiones de productos agrupados, la carga de recursos de POM y los enlaces permanentes de edición del carrito. Construirlo no registra un conjunto duplicado de hooks de WooCommerce.

WC_Product_Addons_Html_Generator existe para la detección de características, pero el renderizador de entrada heredado addon-* no es compatible. Los formularios de POM usan nombres de campo UUID y validación del servidor; emitir nombres de entrada oficiales crearía un formulario inseguro. Las llamadas no admitidas a la fachada emiten _doing_it_wrong() y devuelven WP_Error cuando el tipo de retorno oficial lo permite; los métodos HTML no devuelven marcado.

Hooks PHP oficiales admitidos

POM emite los hooks admitidos de Product Add-Ons 8.4.1 únicamente en rutas de ejecución equivalentes. La extensión oficial es la única propietaria cuando está activa, por lo que una devolución de llamada no se ejecuta dos veces.

Hooks de resolución y de ayuda:

• get_product_addons_product_terms, get_parent_product_addons_fields, get_product_addons_fields, get_product_addons, product_addons_field_prefix;
• addons_add_to_cart_text, addons_add_to_cart_url, wc_pao_restriction_data, woocommerce_addons_cloned_product_with_filtered_price;
• woocommerce_pao_date_input_timezone_reference, woocommerce_product_addons_cart_permalink, woocommerce_product_addons_no_image_select_placeholder_src, woocommerce_product_addons_show_num_chars.

Hooks de tienda y de recursos:

• woocommerce_product_addons_start, woocommerce_product_addons_end, wc_product_addon_start, wc_product_addon_options, wc_product_addon_end;
• woocommerce_addons_product_page_container_classes, woocommerce_product_addons_price_raw, woocommerce_product_addons_price, woocommerce_product_addons_option_price_raw, woocommerce_product_addons_option_price;
• woocommerce_addons_add_product_price_to_value, woocommerce_product_addons_image_swatch_size, woocommerce_product_addons_show_grand_total, woocommerce_pao_reset_date_link, woocommerce_pao_reset_file_link, woocommerce_pao_script_dependencies, woocommerce_price_trim_zeros.

Hooks de validación, carrito, importación y pedido:

• woocommerce_product_addons_validate_value, woocommerce_validate_posted_addon_data, woocommerce_product_addon_cart_item_data, woocommerce_product_addon_reorder_cart_item_data, woocommerce_product_addon_reorder_disable_validation;
• woocommerce_product_addons_add_to_cart_product_types, woocommerce_product_addons_adjust_price, woocommerce_product_addons_update_product_price, woocommerce_addons_add_cart_price_to_value, woocommerce_product_addons_get_item_data, woocommerce_product_addons_upload_dir;
• woocommerce_product_addons_import_data, woocommerce_product_addons_display_editing_in_order_button, woocommerce_product_addons_editing_in_order_validate, woocommerce_product_addons_editing_in_order_form, woocommerce_product_addons_editing_in_order;
• woocommerce_product_addons_get_order_item_price, woocommerce_addons_add_order_price_to_value, woocommerce_product_addons_order_line_item_meta.

Las devoluciones de llamada reciben las formas oficiales de campos o de filas de carrito. Son código de aplicación de confianza y deben devolver el tipo documentado y conservar las claves obligatorias. POM sigue validando los valores del navegador contra la definición actual respaldada por UUID.

Compatibilidad de REST de pedidos y webhooks

Los pedidos conservan una entrada de metadatos de elemento de línea visible por cada complemento aceptado, además de la evidencia interna compatible _pao_ids y _pao_total. Las respuestas REST de pedidos nativas de WooCommerce y los webhooks usan la misma forma orientada al cliente.

POM también conserva estas incorporaciones de webhook establecidas:

• una clave de metadatos de línea que contenga un importe en euros entre paréntesis recibe el valor numérico addon_price;
• el metadato de pedido checkout_delivery_type se copia al type de nivel superior;
• el metadato de pedido checkout_table_code se copia al table_id de nivel superior.

Por ejemplo, los metadatos cuya clave es Sauce (2€) conservan key y value y reciben "addon_price": 2. Las filas históricas de pedidos no se recalculan a partir de las definiciones actuales de producto.

Verificar la compatibilidad

1. Lee un producto simple y una variación a través del REST nativo de WooCommerce, el REST de compatibilidad, la funcionalidad y WC_Product_Addons_Helper::get_product_addons().
2. Confirma que los mismos ID de campo aparecen en el REST del producto, los datos de compatibilidad de la Store API, las filas del carrito, _pao_ids, el REST del pedido y un webhook.
3. Actualiza un grupo con su If-Match actual y luego repite la solicitud obsoleta y confirma que recibe 409 sin cambiar el registro.
4. Confirma que un grupo de solo productos con nombre se omite de la colección global pero aparece en el campo resuelto addons de ese producto.
5. Registra una devolución de llamada temporal para un hook admitido y confirma que se ejecuta una vez en su flujo equivalente.
6. Activa la extensión oficial en un entorno controlado y confirma que la fachada de POM, las rutas oficiales, las funcionalidades y el comportamiento de la tienda permanecen inactivos.

Resolución de problemas

• Clase o ruta ausente: confirma que el ajuste de POM está habilitado, que WooCommerce está activo y que la extensión oficial está inactiva.
• Método de fachada no admitido: traslada la integración a un ayudante admitido o a la API de gestión de POM en lugar de depender del HTML de administración heredado o de la inyección de solicitudes.
• Grupo global ausente: su ámbito de solo producto o avanzado no puede representarse mediante el esquema global oficial; resuelve el producto o usa la API de POM.
• Colisión de ID de compatibilidad: inspecciona y reconstruye el registro de ID con ámbito de sitio antes de reintentar; no edites los ID manualmente.

Relacionado: API REST de gestión, Store API y Blocks y Referencia de integración.