Cómo integrar WooCommerce con VeriFactu sin duplicar lógica fiscal dentro de WordPress

WooCommerce ofrece un modelo de pedidos muy flexible, y precisamente esa flexibilidad hace peligrosa una integración fiscal basada en suposiciones. Dos tiendas con la misma versión pueden tener numeración de factura, PDF, impuestos y devoluciones completamente diferentes. Además, desde WooCommerce 8.2 HPOS es estable y está habilitado por defecto para nuevas instalaciones, por lo que las extensiones modernas deben trabajar con los objetos y APIs CRUD en lugar de depender de posts y postmeta. Puente VeriFactu adopta ese patrón: el plugin WooCommerce es un adaptador delgado que captura hechos comerciales, llama a preflight, utiliza claves idempotentes y persiste estado normalizado; XML, certificados, hash, clasificación fiscal y transporte permanecen en el motor. El resultado es una integración más fácil de probar, actualizar y reconciliar.

1. WooCommerce debe ser origen comercial, no motor fiscal

El límite arquitectónico más importante es decidir qué sabe cada componente. WooCommerce conoce el pedido: cliente, líneas, impuestos calculados, descuentos, portes, moneda y estados. También puede conocer un número fiscal cuando otra extensión lo ha generado. Lo que no debería decidir es la clasificación fiscal sensible que depende de configuración empresarial y normativa: invoiceType, régimen, operación, claves rectificativas o credenciales AEAT. Replicar esas reglas en PHP dentro de cada tienda aumentaría drift, superficie de seguridad y coste de actualización.

El conector v0.3.0 construye payloads neutrales y delega el mapping al Puente. Esa separación permite que la misma tienda siga usando sus flujos de venta mientras el motor fiscal se versiona de forma central. También facilita soporte: un error de datos puede verse en preflight, un error de transporte en el runtime fiscal y un error de presentación en el renderer PDF. Cada incidencia tiene propietario y evidencia, en lugar de mezclarse en un único plugin difícil de auditar.

2. HPOS cambia dónde están los pedidos, pero CRUD mantiene estable el contrato

High-Performance Order Storage introduce tablas dedicadas para pedidos y direcciones y evita que nuevas tiendas dependan del almacenamiento tradicional en posts. WooCommerce documenta HPOS como estable desde 8.2 y recomienda que las extensiones utilicen sus APIs CRUD. Esto es relevante porque una integración que lee directamente _posts, _postmeta o tablas concretas puede dejar de funcionar cuando cambia la autoridad de almacenamiento. El conector no usa get_post_meta, update_post_meta ni acceso directo a tablas de pedido para su flujo fiscal.

Pedidos y refunds se representan mediante WC_Order y WC_Order_Refund, ambos dentro de la abstracción de pedidos de WooCommerce. El mismo principio se utiliza para guardar recordId, estado, error, última sincronización y huella del payload. Así el código no necesita una rama fiscal para HPOS y otra para legacy. La matriz CI instala el ZIP real y activa HPOS para comprobar el comportamiento, pero también se conserva compatibilidad con la tabla legacy para la columna de estado del administrador.

3. El número de pedido no debe convertirse silenciosamente en número de factura

WooCommerce crea pedidos y permite personalizar su numeración, pero eso no demuestra que el identificador sea la serie y número de una factura expedida. Muchas tiendas utilizan un plugin PDF que asigna números al generar el documento; otras reciben la numeración del ERP; otras sí han decidido que el número de pedido es también número fiscal. El conector obliga a elegir una fuente y prefiere una meta-key explícita de la herramienta de facturación existente cuando esa es la autoridad real.

La opción de usar el número de pedido existe solo cuando el comercio confirma explícitamente que representa su número fiscal. Si no se configura una fuente, invoice_number queda vacío y preflight debe bloquear. La fecha sigue la misma filosofía: puede partir de la creación del pedido, pero existe un punto de extensión para sustituirla por la fecha real de expedición. Este detalle evita que una automatización técnicamente correcta construya registros con una identidad documental equivocada.

4. Mapping y preflight son la barrera antes de cualquier efecto fiscal

El payload ordinario contiene identificadores de origen, número y fecha de factura, descripción, moneda, destinatario, total y líneas de impuestos. Puede incluir varios tipos de IVA. A propósito no admite que WooCommerce inyecte taxCode, regimeKey, operationClass o invoiceType. Esos campos se resuelven con MappingProfile en servidor, donde pueden versionarse por organización o instalación. De esta forma una actualización de reglas no exige desplegar lógica sensible en todas las tiendas.

Preflight ejecuta el contrato antes de issue. Puede descubrir NIF ausente, numeración vacía, mapping incompleto, conversión EUR no disponible o céntimos que no reconcilian. El comportamiento correcto ante esos casos es bloquear sin emitir y mostrar una causa accionable. Para una tienda esto es mejor que aceptar parcialmente y corregir después, porque el equipo puede arreglar el dato comercial o el perfil con la operación todavía sin efecto fiscal. El modo manual permite utilizar preflight como herramienta de onboarding.

5. Idempotencia y reconciliación resuelven el problema de los reintentos

Enviar desde WordPress significa asumir fallos de red, timeouts y ejecuciones asíncronas repetidas. La clave idempotente convierte varios intentos de la misma operación en una sola identidad. Mientras una operación nueva todavía no tiene recordId, los reintentos reutilizan exactamente la misma clave. Cuando recordId ya existe, el contrato cambia: el conector solo consulta GET /v1/fiscal-records/{recordId} para reconciliar y nunca vuelve a POST como consecuencia de un error de sincronización.

Esta regla evita una clase peligrosa de bug: interpretar un timeout de respuesta como si el servidor no hubiera recibido el registro y crear otro. Incluso un fallo retryable durante reconciliación conserva la identidad existente. Los estados normalizados y _pv_last_error permiten reflejar que se necesita revisar o reintentar sin mentir sobre lo ocurrido. Una reconciliación posterior satisfactoria puede limpiar el error y devolver el semáforo a verde sin crear una factura adicional.

6. Refund es un evento comercial; la rectificativa es una decisión fiscal separada

Cuando WooCommerce lanza woocommerce_order_refunded, el conector puede construir una operación neutral asociada a WC_Order_Refund. Cada refund obtiene una clave de idempotencia propia y necesita que la factura original tenga recordId. También necesita su propio número fiscal de rectificativa. El importe y los signos se preservan tal como vienen del refund, pero la tienda no decide si corresponde R1, R2, R3, R4 o R5 ni la modalidad de rectificación.

Esas decisiones se delegan a refund_profile_id server-side. La automatización de refunds está desactivada por defecto para evitar que un comercio que todavía no ha definido numeración o tratamiento rectificativo empiece a fiscalizar devoluciones. En onboarding se prueba una devolución representativa, incluidas las parciales cuando formen parte del negocio. El estado agregado del pedido puede volverse rojo si el refund queda bloqueado, aunque la factura principal esté aceptada, porque ambas operaciones necesitan atención independiente.

7. QR y textos pertenecen a presentación, no a una segunda emisión desde el PDF

No existe un único plugin PDF estándar en WooCommerce. Por eso integrar directamente la lógica fiscal con un proveedor concreto crearía una dependencia innecesaria. El conector v0.3.0 guarda un contrato neutral de presentación y expone funciones, filtro y acción para que el renderer consuma la URL, QR y textos asociados al registro. La presentación procede del motor fiscal y el plugin PDF se limita a renderizar, sin recalcular ni reinterpretar reglas.

Este diseño también separa reimpresión de emisión. Descargar otra vez una factura, enviarla por email o regenerar su PDF no debe crear un nuevo registro. Durante la prueba se comprueba que la presentación se asocia al recordId correcto, que aparece en los documentos previstos y que los fallos del renderer no cambian el estado fiscal. Si la tienda utiliza varios documentos o proveedores PDF, el diagnóstico decide qué hooks son fiables antes de comprometer compatibilidad.

8. Automatizar después de probar el modo manual reduce el radio de fallo

El conector permite configurar qué estados WooCommerce disparan envío automático, pero no es obligatorio empezar así. En una implantación nueva es más seguro validar un pedido, enviar manualmente, refrescar estado y comprobar PDF. Después puede activarse un estado de automatización representativo y observar Action Scheduler, reintentos y reconciliación. Los refunds tienen su interruptor independiente. Esta progresión permite detectar una condición de negocio inesperada antes de que afecte a un volumen grande de pedidos.

Action Scheduler se utiliza cuando está disponible y WP-Cron actúa como fallback para evitar HTTP fiscal dentro del hook síncrono. Los errores retryable tienen hasta cinco intentos con backoff; los errores de validación quedan bloqueados. La operación no cambia de identidad durante ese ciclo. También existe un fallback operativo por CSV/XLSX si una actualización de WooCommerce rompe temporalmente el conector, lo que desacopla continuidad fiscal del ciclo de releases de la tienda.

9. Una prueba útil cubre errores, no solo el pedido feliz

El smoke mínimo debe incluir una factura ordinaria válida, un preflight bloqueado por dato ausente, un reintento técnico con la misma idempotencia, reconciliación de un recordId existente y un refund cuando el comercio utilice devoluciones. También conviene probar varias tasas de IVA, descuentos, portes y la generación del PDF. Si la tienda vende en divisas, se añade un caso de conversión correcta y otro donde falta la tasa para confirmar que preflight bloquea.

La matriz del producto ya valida el ZIP real en combinaciones de WordPress 6.5/WooCommerce 8.2/PHP 7.4, WordPress 7.0.4/WooCommerce 11.0.1/PHP 8.2 y WordPress 7.1/WooCommerce 11.1/PHP 8.3, con HPOS y escenarios de factura/refund. Esa evidencia no sustituye el QA de la tienda concreta: tema, checkout, plugins fiscales, multimoneda, suscripciones, ERP y renderer PDF pueden introducir condiciones que no existen en una instalación limpia.

10. Conector preparado y AEAT producción son estados diferentes

Una tienda puede tener el plugin instalado, mapping validado, pruebas aceptadas y automatización técnicamente preparada sin estar habilitada para producción fiscal. Mantener esa distinción es importante tanto por seguridad como por evolución normativa. El certificado y las credenciales sensibles permanecen fuera de WooCommerce y la contratación comercial no puede saltarse el gate técnico/regulatorio. El equipo puede completar todo el trabajo reversible antes de decidir una activación productiva.

En el momento del go-live se revisan de nuevo norma vigente, identidad fiscal, certificado, configuración, evidencia, rollback y autorización explícita. Esta regla evita convertir un despliegue de WordPress en una decisión regulatoria implícita. También facilita soporte: una actualización de plugin puede probarse sin cambiar producción, y una revisión normativa puede bloquear el gate sin obligar a desinstalar la integración ya preparada. Es la misma filosofía que separa ecommerce, adaptación y motor fiscal durante todo el ciclo.