Usar Product Add-Ons con los Bloques y la Store API

Usa esta referencia cuando el escaparate utiliza el bloque Add to Cart with Options de WooCommerce, los bloques de Carrito y Pago, o un cliente headless. El navegador envía la intención del cliente; POM resuelve la publicación actual, las condiciones, la disponibilidad y el precio en el servidor.

Requisitos previos

• Activa Product Add-Ons en Settings → POM Tweaks → E-Commerce → Products.
• Publica un grupo asignado o una definición específica de producto en un producto público.
• Mantén inactiva la extensión oficial WooCommerce Product Add-Ons mientras POM gestione el escaparate.
• Conserva el Nonce o Cart-Token de WooCommerce devuelto para el carrito actual al realizar solicitudes directas a la Store API.

Usar los Bloques de WooCommerce

1. Ve a Appearance → Editor y abre la plantilla de producto individual utilizada por la tienda.
2. Añade o conserva el bloque Add to Cart with Options de WooCommerce.
3. Guarda la plantilla y abre un producto asignado.
4. Completa sus campos de complementos obligatorios y añádelo al carrito.
5. Abre los bloques de Carrito y Pago y confirma que cada etiqueta y valor aceptados aparezcan debajo del producto.

No se requiere un bloque de campo de Product Add-Ons independiente. Los formularios de producto Clásico y de Bloques ejecutan la misma validación y el mismo cálculo de precios en el servidor. Un producto que requiere configuración enlaza a su página de producto en lugar de usar un atajo AJAX de añadir al carrito desde el archivo.

Descubrir el modelo público de producto

Lee un producto antes de renderizar un formulario headless:

GET /wp-json/wc/store/v1/products/123

La respuesta usa extensions.pom-tweaks-product-addons:

La configuración pública actual usa schema_version: 6. Trata la versión del esquema como una señal de compatibilidad, no como una identidad de entidad. Usa los UUID de contexto, campo y opción como identidades; las etiquetas son texto de visualización traducido y nunca deben enviarse como identificadores.

El modelo público incluye la configuración efectiva para el producto o variación, idioma, moneda, zona de país, generación de publicación, condiciones, programaciones y disponibilidad de opciones reutilizables actuales. No expone la configuración privada de otras zonas ni los totales de capacidad sin restricciones. Vuelve a solicitarlo antes del envío cuando una página haya permanecido abierta mucho tiempo o cuando el cliente cambie el contexto de mercado.

La misma representación pública está disponible directamente:

GET /wp-json/pom-tweaks/v1/product-add-ons/products/123

Esa respuesta directa no es almacenable en caché porque las programaciones y la capacidad compartida pueden cambiar sin editar el producto.

Mantener ligeras las solicitudes del catálogo

Para un catálogo que solo necesita descubrimiento, solicita el resumen de la extensión:

GET /wp-json/wc/store/v1/products?per_page=100&_fields=id,name,extensions.pom-tweaks-product-addons.has_addons,extensions.pom-tweaks-product-addons.summary

El resumen informa de la versión del esquema, un configuration_version opaco y los recuentos de contextos, campos, campos configurables y opciones. Compara la versión opaca solo por igualdad; no la analices ni la uses como ID de registro. Obtén el producto individual antes de renderizar su formulario.

Si una colección no necesita Product Add-Ons, omite extensions de _fields, por ejemplo _fields=id,name,prices. POM omite entonces la resolución de Product Add-Ons para esas filas. Solicitar extensions, el espacio de nombres POM completo o configuration devuelve la representación publicada completa.

Los modelos públicos se separan por sitio, producto, versión de configuración, idioma, moneda, versión del esquema y modo de opciones ocultas. POM elimina la cabecera Last-Modified de WooCommerce, propia solo del producto, cuando se seleccionan datos de Product Add-Ons, porque un grupo compartido puede cambiar sin editar cada producto asignado.

Añadir un producto configurado al carrito

Publica los valores UUID del modelo actual en el endpoint normal de WooCommerce:

POST /wp-json/wc/store/v1/cart/add-item

{
  "id": 123,
  "quantity": 2,
  "pom_product_addons": {
    "context-uuid": {
      "single-choice-field-uuid": "option-uuid",
      "checkbox-field-uuid": ["first-option-uuid", "second-option-uuid"],
      "text-field-uuid": "Customer value",
      "custom-price-field-uuid": "12.50"
    }
  }
}

Para un producto variable, id es el ID de variación publicada seleccionada. Incluye los datos de variación normales de WooCommerce cuando esa versión de la Store API lo requiera.

No envíes un precio de complemento calculado. El servidor rechaza la solicitud completa cuando contiene identificadores desconocidos, campos inactivos, opciones no disponibles, precios definidos por el cliente no válidos o campos obligatorios ausentes. Nada se añade parcialmente.

Los clientes escritos para la extensión oficial pueden en su lugar enviar addons_configuration con los ID de campo numéricos y los índices posicionales de opción devueltos por las API compatibles con la oficial. No envíes a la vez pom_product_addons y addons_configuration en una misma solicitud.

Leer los datos del carrito

Los elementos de carrito aceptados exponen los resultados de POM en extensions.pom-tweaks-product-addons. La respuesta puede incluir:

• has_addons, flat_fee_total y la charge_context de compra actual;
• el economic_result aplicado por el servidor y el regional_context acotado;
• un edit_token vinculado a la sesión y un edit_url seguro.

Los clientes compatibles con la oficial también reciben extensions.addons.addons_data. Los raw_prices de la Store API siguen siendo cadenas enteras con la precisión de precio bruto anunciada por WooCommerce.

Una tarifa plana se cobra una vez por línea del carrito. WooCommerce distribuye esa tarifa de línea entre la cantidad cuando presenta un precio unitario. Los importes basados en cantidad y en porcentaje se escalan con la cantidad del producto. La variación seleccionada proporciona el precio base autoritativo para los cálculos de porcentaje.

Editar un elemento del carrito

El edit_url del elemento del carrito restaura sus selecciones que no son de archivo en el formulario del producto. Los navegadores no pueden rellenar de nuevo un campo de archivo local, por lo que un archivo obligatorio debe seleccionarse otra vez.

Un cliente headless puede editar de forma atómica mediante:

POST /wp-json/wc/store/v1/cart/extensions

Usa el espacio de nombres pom-tweaks-product-addons-edit-item. Su objeto data acepta edit_token, el id de producto o variación, los quantity y variation opcionales, y bien pom_product_addons o addons_configuration. Una edición obsoleta o no válida deja la línea original del carrito sin cambios.

Subir un archivo desde un cliente headless

La solicitud JSON de añadir al carrito no puede contener bytes de archivo.

1. Envía una solicitud multiparte file a POST /wp-json/pom-tweaks/v1/product-addons/files.
2. Envía el nonce REST de WordPress actual, el nonce de la Store API o el Cart-Token.
3. Lee el file_id opaco de la respuesta correcta.
4. Envía ese file_id como valor del campo de archivo en pom_product_addons, usando la misma identidad de carrito.

POM vuelve a comprobar la propiedad, el campo activo, el nombre de archivo, la extensión, el tipo MIME detectado, el tamaño y la configuración actual. Nunca acepta una URL pública ni una ruta del sistema de archivos como nueva selección de archivo.

Límites operativos

La entrada sobredimensionada o excesivamente anidada se rechaza como una sola operación; nunca se trunca. Los valores predeterminados importantes son:

El límite efectivo de archivos también está acotado por la configuración de PHP, WordPress y multisitio. Las solicitudes de tamaño rechazadas usan HTTP 413 cuando corresponde; los límites de frecuencia de sesión usan HTTP 429.

Las tiendas medidas pueden ajustar la matriz de límites acotados con pom_tweaks_product_addons_operational_limits. Mantén el callback en un plugin del sitio y prueba el límite previsto más un valor por encima de él. Reducir un límite del modelo efectivo por debajo de una configuración existente hace que las nuevas compras de complementos no estén disponibles hasta que se reduzca la configuración; las instantáneas históricas de los pedidos siguen siendo legibles.

pom_tweaks_product_addons_limit_rejected proporciona metadatos de rechazo seguros para la privacidad con fines de monitorización. Excluye valores de clientes, nombres de archivo, URL, cuerpos de solicitud, ID de usuario, ID de sesión y direcciones IP.

Verificar la integración

1. Envía una selección válida y otra incompleta; confirma que la solicitud incompleta no añada ninguna línea.
2. Añade el mismo producto dos veces con valores diferentes y confirma que las líneas permanezcan separadas.
3. Cambia la cantidad y confirma que una tarifa plana se mantenga una vez por línea mientras los ajustes por unidad se escalan.
4. Repite con dos variaciones y confirma que cada variación seleccionada proporcione su propia base y capacidad de compra.
5. Completa un pago de Bloques y compara el carrito, la línea del pedido, la respuesta REST del pedido y los valores del webhook.
6. Sube un archivo permitido, envía su file_id y confirma que otra sesión de carrito no pueda usar ese identificador.
7. Edita una línea del carrito con su token actual, vuelve a intentar con el token obsoleto y confirma que la segunda solicitud no cambie nada.

Resolución de problemas

• Campos ausentes: confirma que el grupo y las opciones reutilizables estén publicados, que el producto coincida con la asignación y que la plantilla contenga Add to Cart with Options.
• Selección rechazada después del renderizado: vuelve a obtener el producto; puede haber cambiado una publicación, condición, programación, capacidad, idioma, moneda o país.
• ID de archivo rechazado: confirma que la subida y la solicitud del carrito usen el mismo nonce o Cart-Token y que el campo siga permitiendo el tipo detectado.
• Vista previa del cliente y precio del carrito diferentes: usa el resultado del servidor. Las vistas previas del navegador son orientativas.
• Datos de extensión ausentes en una colección: comprueba _fields; omitir extensions omite intencionadamente la resolución de Product Add-Ons.

Relacionado: Persistencia del carrito y del pedido, Campos y precios del escaparate y Compatibilidad con el Product Add-Ons oficial.