Una integración WooCommerce–ERP es fiable cuando cada dato tiene una fuente maestra, los eventos pueden repetirse sin duplicar, los errores quedan en cola y existe conciliación diaria. Conectar la API no basta: hay que definir cuándo nace un pedido, quién reserva stock, cómo se tratan pagos, devoluciones, impuestos y facturas, y qué ocurre si uno de los sistemas está caído.
Definir sistemas maestros
| Dato | Maestro recomendado habitual |
|---|---|
| Producto/SKU | ERP o PIM |
| Precio | ERP, PIM o motor comercial |
| Stock disponible | ERP/WMS |
| Pedido web | WooCommerce al originarse |
| Factura | ERP |
| Pago | Pasarela con conciliación ERP |
| Cliente | Regla definida según B2C/B2B |
| Envío | ERP/WMS o plataforma logística |
No deben existir dos sistemas autorizados a cambiar el mismo dato sin una regla que lo resuelva.
Identificadores
Utilice claves estables:
- SKU único.
- ID de variación.
- ID externo de cliente.
- Número de pedido web.
- ID de transacción.
- Número de factura ERP.
- Lote de sincronización.
Los nombres no son identificadores. Un cambio de descripción no debe crear un producto nuevo.
API y webhooks
WooCommerce ofrece una REST API para leer y escribir productos, pedidos y otros recursos. Los webhooks notifican eventos a una URL.
Patrón recomendado:
- El webhook informa del evento.
- El receptor valida la firma y registra el evento.
- Una cola desacopla el procesamiento.
- Un worker consulta el detalle por API.
- Se transforma y envía al ERP.
- Se confirma el resultado.
- La conciliación detecta ausencias.
No se confía solo en el webhook: puede fallar o desactivarse tras errores repetidos. La reconciliación periódica es obligatoria.
Seguridad
- Claves por integración y entorno.
- Mínimo privilegio.
- HTTPS.
- Secretos en gestor, no en código.
- Rotación.
- IP o controles adicionales cuando proceda.
- Logs sin secretos.
- Validación de payload.
- Protección contra replay.
- Parcheado de WordPress y plugins.
La documentación oficial muestra claves con permisos de lectura y escritura; deben concederse solo si el flujo lo necesita.
Pedidos y estados
Se mapea cada estado:
| WooCommerce | ERP | Acción |
|---|---|---|
| pending | pendiente | no reservar o regla específica |
| processing | confirmado | reservar/preparar |
| completed | expedido/cerrado | cerrar según proceso |
| cancelled | cancelado | liberar |
| refunded | devolución/abono | flujo financiero |
| failed | fallo | no preparar |
El mapeo se adapta a la pasarela y la logística. No se factura por un estado ambiguo.
Idempotencia
Cada evento tiene una clave compuesta —tienda, pedido, tipo y versión—. Si llega dos veces, la segunda operación actualiza o se ignora, nunca crea otro pedido.
Los reintentos tras un timeout consultan primero si la operación ya existe.
Stock
Definir:
- Stock físico.
- Reservado.
- Disponible para venta.
- Seguridad.
- Backorder.
- Múltiples almacenes.
- Kits y variaciones.
La tienda debe recibir el disponible, no necesariamente el físico. La frecuencia depende de la rotación y el riesgo de sobreventa.
Se realiza conciliación por SKU y alertas por diferencias.
Precios y promociones
Decidir dónde viven tarifas, cupones, impuestos y redondeos. El ERP recibe el desglose suficiente para reproducir el total.
Las promociones complejas pueden registrarse como descuento con trazabilidad. No se recalcula en el ERP de forma que cambie lo cobrado.
Impuestos
Se prueban B2C/B2B, territorios, exenciones, tipos, portes y descuentos. La localización fiscal y las obligaciones de factura deben validarse.
WooCommerce calcula la venta; el ERP debe aceptar o validar según el diseño, sin generar diferencias silenciosas.
Clientes y privacidad
Para la venta como invitado se evita crear duplicados por cada variante del correo. Se define una regla de matching y cuándo actualizar los datos.
La integración minimiza datos, controla roles y contratos y aplica conservación. El marketing no se activa automáticamente por comprar.
Facturas
El ERP suele numerar y emitir. El enlace devuelve número, PDF o estado a WooCommerce o al área de cliente. Las rectificativas y devoluciones se relacionan con el original.
No se edita una factura emitida por un cambio en el pedido; se aplica el flujo fiscal correcto.
Pagos
El pedido, la transacción y la liquidación son objetos distintos. Se concilian:
- Importe del pedido.
- Cobro.
- Comisión.
- Devolución.
- Contracargo.
- Liquidación bancaria.
Un webhook de pedido no prueba que el dinero esté liquidado.
Envíos y devoluciones
El ERP/WMS envía transportista, tracking, bultos y estado. Las devoluciones generan autorización, recepción, inspección, abono y reposición según la condición.
No se repone stock al solicitar la devolución; se hace al recibir y validar.
Gestión de errores
La cola de errores muestra:
- Evento.
- Pedido/SKU.
- Causa.
- Reintentos.
- Última respuesta.
- Propietario.
- Acción.
Los errores permanentes —por ejemplo, un SKU inexistente— no se reintentan indefinidamente. Se corrige el dato y se reprocesa.
Observabilidad
Métricas:
- Pedidos sincronizados.
- Latencia p95.
- Errores por causa.
- Reintentos.
- Diferencias de stock.
- Pedidos sin factura.
- Pagos sin pedido.
- Webhooks inactivos.
- Duplicados evitados.
Las alertas deben ser accionables.
Pruebas
- Pedido invitado y cliente.
- Variaciones.
- Cupón.
- Varios impuestos.
- Pago fallido.
- Reembolso parcial.
- Cancelación.
- Stock simultáneo.
- Webhook duplicado.
- ERP caído.
- WooCommerce caído.
- Cambio de SKU.
- Devolución.
Plan de implantación
Días 1–30
Maestros, estados, impuestos, arquitectura y seguridad.
Días 31–60
API, webhooks, colas, idempotencia y pruebas.
Días 61–90
Piloto, conciliación, alertas y producción.
Errores frecuentes
- Sin fuente maestra.
- Usar nombres como clave.
- Confiar solo en webhooks.
- Reintentar sin idempotencia.
- Sin cola de errores.
- Actualizar stock físico.
- Recalcular promociones.
- Facturar antes de un pago válido.
- Reponer antes de recibir la devolución.
- Sin conciliación diaria.
Checklist
- Maestros.
- Identificadores.
- Estados.
- Idempotencia.
- Stock disponible.
- Precios e impuestos.
- Clientes y privacidad.
- Facturas y pagos.
- Errores y alertas.
- Conciliación y reversión.
Preguntas frecuentes
¿API o plugin?
Depende del alcance. Un plugin puede acelerar, pero debe demostrar seguridad, mantenimiento, idempotencia y soporte.
¿Son suficientes los webhooks?
No. Deben complementarse con consulta y conciliación.
¿Quién debe controlar el stock?
Normalmente el ERP/WMS. WooCommerce recibe la disponibilidad calculada.
Fuentes oficiales consultadas
- WooCommerce REST API.
- WooCommerce Webhooks.
- WooCommerce Developer REST API.
- WooCommerce: trabajo con webhooks.
Summum Sistemas puede diseñar la integración, las colas, la conciliación y la monitorización.