HPOS en WooCommerce: cómo migrar los pedidos sin romper plugins

HPOS en WooCommerce (High-Performance Order Storage, almacenamiento de pedidos de alto rendimiento) cambia el sitio donde la tienda guarda los pedidos. Desde la versión 8.2 viene activado en las instalaciones nuevas, pero muchas tiendas que llevan años vendiendo siguen con el sistema antiguo, a menudo porque algún plugin no lo admite o porque nadie ha querido arriesgarse a cambiarlo. Aquí explicamos qué cambia por dentro, cómo funciona la sincronización entre los dos sistemas y cómo plantear la migración con un entorno de pruebas para que los plugins sigan funcionando.

Qué es HPOS y qué cambia en las tablas de pedidos

Hasta la llegada de HPOS, WooCommerce guardaba cada pedido como una entrada de WordPress, en la misma tabla que las páginas y los artículos del blog. Los datos del pedido (importes, direcciones, método de pago, notas internas) iban a una tabla genérica de metadatos, una fila por dato. Funciona, pero con muchos pedidos esa tabla crece sin parar y las consultas para buscar o filtrar pedidos se vuelven lentas, porque tienen que cruzar muchísimas filas.

HPOS mueve los pedidos a tablas propias, diseñadas para ellos:

• wc_orders, con los datos principales del pedido: estado, importes, cliente y fechas.
• wc_order_addresses, con las direcciones de facturación y envío.
• wc_order_operational_data, con datos internos que WooCommerce usa para gestionar el pedido.
• wc_orders_meta, con los metadatos que añaden los plugins.

Delante de cada nombre va el prefijo de tablas de tu instalación. Para quien gestiona la tienda el cambio apenas se ve: la pantalla de pedidos se parece mucho a la anterior, aunque cambia su dirección dentro del administrador, así que los marcadores y enlaces internos a pedidos concretos pueden dejar de funcionar. Para el código que lee o escribe pedidos, el cambio afecta a todo lo que hace.

Por qué HPOS puede romper plugins y código a medida

Un plugin que trata los pedidos con las funciones públicas de WooCommerce (carga el pedido como objeto y lee o guarda sus datos con los métodos del propio pedido) funciona igual con un sistema que con otro, porque WooCommerce decide por dentro de qué tabla leer. Los problemas aparecen con el código que va por su cuenta:

• Lee o actualiza datos del pedido con las funciones de metadatos de WordPress pensadas para entradas.
• Busca pedidos con consultas de entradas filtradas por el tipo shop_order.
• Lanza consultas SQL directas contra las tablas de entradas y metadatos.
• Añade columnas, filtros o cajas a la pantalla de pedidos con hooks que solo existen en la pantalla antigua.

Con HPOS activo, ese código puede leer datos desactualizados o escribir en una tabla que WooCommerce ya no consulta. Muchas veces ni siquiera da error. El pedido se guarda, pero el número de seguimiento, el campo de factura o la marca de enviado al ERP se quedan en un sitio donde nadie los lee.

Imagina una tienda con un conector propio que marca cada pedido como exportado al ERP guardando un metadato con la función de WordPress. Tras activar HPOS, el conector ya no encuentra esa marca y vuelve a enviar pedidos que ya estaban exportados. Para detectar un fallo así hace falta una prueba completa en un entorno de copia que incluya la comprobación en el ERP.

Modo de compatibilidad y sincronización entre tablas

WooCommerce permite tener los dos sistemas en paralelo. En los ajustes avanzados, apartado de características, eliges qué almacenamiento manda (el de alto rendimiento o el antiguo, basado en entradas de WordPress) y puedes activar el modo de compatibilidad, que mantiene sincronizadas las tablas nuevas y las antiguas. El texto exacto de cada opción puede variar un poco según la versión y el idioma del administrador.

Cómo funciona en la práctica:

• Solo una de las dos fuentes es la principal. La otra recibe una copia de cada cambio.
• Al activar la sincronización por primera vez, los pedidos pendientes se copian por lotes en segundo plano, mediante tareas programadas. En una tienda con un histórico largo tarda un rato.
• Mientras queden pedidos sin sincronizar, WooCommerce no te deja cambiar el almacenamiento principal.
• Con la sincronización activa puedes volver al almacenamiento antiguo si algo falla, porque las dos tablas tienen los mismos datos.

La sincronización tiene un coste: cada escritura de pedido se hace dos veces. Tiene sentido como etapa de transición, mientras compruebas que todo funciona y conservas la vuelta atrás. Cuando la tienda lleva un tiempo estable con HPOS, lo normal es desactivarla.

En tiendas con muchos pedidos, la sincronización también se puede lanzar desde la línea de comandos con WP-CLI, lo que permite controlar mejor cuándo se ejecuta y no depender de las tareas programadas.

Cómo revisar qué plugins son incompatibles con HPOS

Los plugins pueden declarar si son compatibles con HPOS. Si alguno de los activos se declara incompatible, WooCommerce lo avisa en la misma pantalla de características, enlaza a la lista de plugins afectados y no deja activar el nuevo almacenamiento hasta resolverlo.

Esa lista es un buen punto de partida, aunque se queda corta:

• Un plugin que no declara nada puede no aparecer como incompatible y aun así leer pedidos por su cuenta.
• El código a medida que esté en el tema, por ejemplo en functions.php, no declara compatibilidad de ninguna forma.
• Los conectores con ERP, almacén o facturación pueden funcionar bien en la tienda y fallar en el sistema externo.

Para cada plugin de la lista, comprueba si hay una versión más reciente que ya declara compatibilidad, si el autor sigue manteniéndolo o si toca sustituirlo. En el código propio, busca funciones de entradas y metadatos de WordPress aplicadas a pedidos, consultas directas a la base de datos y referencias al tipo shop_order. Si aparecen muchas, suele ser buen momento para pasar ese código a un plugin a medida escrito sobre las funciones públicas de WooCommerce. En la guía sobre plugin comprado o código a medida en WooCommerce contamos dónde debe vivir ese código.

Plan para activar HPOS en WooCommerce con un entorno de pruebas

Si lo activas directamente en producción, el primer aviso de un plugin roto suele llegar de un cliente. El orden que proponemos para activar HPOS en WooCommerce es este:

• Haz una copia completa de la tienda real, archivos y base de datos, en un entorno de pruebas con los mismos plugins y versiones.
• En esa copia, desactiva los correos a clientes y apunta pasarelas de pago, ERP y transportistas a sus entornos de prueba.
• Actualiza WooCommerce, el resto de plugins y el tema, y comprueba que todo funciona antes de tocar HPOS.
• Resuelve los plugins incompatibles y el código propio que hayas localizado.
• Activa el modo de compatibilidad con el almacenamiento antiguo como principal y espera a que se sincronicen todos los pedidos.
• Cambia el almacenamiento principal a HPOS, con la sincronización todavía activa, y pasa la batería de pruebas.
• Repite los mismos pasos en producción en un momento de poca actividad, con una copia de seguridad reciente.
• Mantén la sincronización mientras vigilas registros y procesos externos, y desactívala cuando no aparezcan incidencias.

Qué probar después de activar HPOS

La lista de pruebas debería estar escrita antes del cambio, con el resultado esperado de cada una:

• Una compra completa con cada método de pago activo.
• Un pedido con cupón y otro con varias líneas y un envío especial.
• Cambios de estado manuales desde el administrador, incluida una cancelación.
• Un reembolso parcial.
• La búsqueda y los filtros de la pantalla de pedidos, también los que añaden plugins.
• Facturas, etiquetas de envío y números de seguimiento.
• La exportación al ERP o al almacén, comprobando en el sistema externo que no se duplica ningún pedido.
• Suscripciones o pedidos recurrentes, si los usas.
• Informes de ventas, comparando las cifras de un mismo periodo antes y después del cambio.

Si la tienda está conectada a un ERP, la exportación es la prueba que más importa: un pedido duplicado en facturación cuesta bastante más de arreglar que un fallo visible en la tienda. En integración ERP y ecommerce explicamos cómo diseñamos esas conexiones para que un pedido repetido se detecte.

Cuándo esperar antes de migrar a HPOS

Las tiendas existentes pueden seguir, de momento, con el almacenamiento antiguo, así que no hace falta forzar el cambio en mal momento. Conviene esperar si un plugin del que depende la operativa no es compatible y no tiene sustituto, si estás entrando en temporada alta o si no dispones de un entorno de pruebas donde ensayar.

Si decides esperar, revisa las notas de versión de WooCommerce por si cambian los planes para el almacenamiento antiguo, y aprovecha cualquier desarrollo nuevo que toque pedidos para escribirlo ya compatible con HPOS.

Checklist antes de migrar a HPOS

• Versión actual de WooCommerce y almacenamiento activo (si la tienda se creó con la 8.2 o posterior, puede que ya use HPOS).
• Lista de plugins incompatibles y una decisión para cada uno: actualizar, sustituir o reescribir.
• Inventario del código propio, en el tema o en plugins a medida, que lea o escriba pedidos.
• Conexiones externas que trabajan con pedidos: ERP, almacén, facturación y automatizaciones.
• Entorno de pruebas actualizado, con correos y pasarelas desconectados.
• Lista de pruebas con el resultado esperado de cada una.
• Ventana de cambio en producción y copia de seguridad recién hecha.
• Una persona encargada de vigilar registros y pedidos los días siguientes.

Si prefieres no hacerlo solo, la migración a HPOS encaja dentro del mantenimiento WooCommerce: revisamos plugins y código, preparamos la copia de pruebas y hacemos el cambio con la vuelta atrás preparada.