WooCommerce / Integraciones
Problemas de integración en WooCommerce: REST API, webhooks y sistemas externos
Las integraciones fallan en los bordes: autenticación, red, timeouts, reintentos y mapeo de datos. La dificultad es que cada lado solo ve la mitad de la conversación, así que el diagnóstico empieza juntando las dos mitades.
Respuesta corta
En la REST API, lee el código de error exacto de la respuesta: woocommerce_rest_cannot_view o un 401 apuntan a la autenticación o a los permisos de la clave, un 403 a una capa de seguridad, un 500 a un error PHP en la tienda. En los webhooks, abre el registro de entregas del webhook en WooCommerce: códigos de respuesta, timeouts y fallos repetidos. WooCommerce desactiva un webhook tras varias entregas fallidas seguidas.
Recursos técnicos
Guías sobre integraciones
- WooCommerce / Integraciones Errores de la REST API de WooCommerce: cómo diagnosticarlos Lee el código de estado y el código de error de la respuesta: autenticación, permisos, rutas, capas de seguridad y errores del servidor fallan cada uno de una forma.
- WooCommerce / Integraciones Webhooks de WooCommerce que fallan: cómo diagnosticarlos Registros de entrega, códigos de respuesta, firmas y por qué WooCommerce desactiva un webhook tras varias entregas fallidas seguidas.
Problemas concretos
Fallos de integración habituales
Errores de autenticación de la REST API
401 y woocommerce_rest_cannot_view: claves, permisos, HTTPS, cabeceras eliminadas.
Entregas de webhooks que fallan
Timeouts, respuestas no 2xx, webhooks desactivados, firmas que no se validan.
Problemas de sincronización con el ERP
Pedidos o stock desincronizados, duplicados, actualizaciones parciales.
Problemas de sincronización con el CRM
Clientes y pedidos que no llegan al CRM, o que llegan dos veces.
Timeouts de APIs externas
Llamadas a terceros que ralentizan o rompen el checkout y la administración.
Colas de sincronización en segundo plano
Tareas de integración atascadas en Action Scheduler.
Junta las dos mitades de la conversación
Un problema de integración suele verse distinto desde cada lado. El ERP dice «la tienda devolvió un error»; los registros de la tienda no muestran nada. O la tienda dice «webhook entregado» y el sistema receptor asegura que nunca lo procesó. El diagnóstico alinea ambos lados para el mismo pedido o la misma petición, por hora e identificador.
| Síntoma | Dónde mirar |
|---|---|
| El cliente de la API recibe 401/403 | Permisos de la clave, cabeceras de autenticación que llegan a PHP, reglas de seguridad |
| El cliente de la API recibe 500 | Registros PHP y fatal-errors de la tienda a esa hora |
| Webhook «no recibido» | Registro de entregas del webhook en WooCommerce, código de respuesta, duración |
| Los datos llegan dos veces | Reintentos sin idempotencia, webhooks duplicados, varias tareas de sincronización |
| Checkout lento o con fallos | Llamadas externas síncronas durante la petición del checkout |
Construye integraciones que se puedan depurar
Las integraciones fáciles de diagnosticar comparten unos rasgos: cada petición se registra con un identificador, los fallos se reintentan con límites, las operaciones son idempotentes para que los reintentos no dupliquen datos y el trabajo pesado o lento se ejecuta en segundo plano, no dentro de la petición de un cliente.
Preguntas frecuentes
¿Por qué la REST API de WooCommerce devuelve 401?
Causas habituales: claves API incorrectas o revocadas, claves sin permiso de lectura o escritura, cabeceras de autenticación eliminadas por el servidor o un proxy, y autenticación básica enviada por HTTP sin cifrar. El código de error del cuerpo de la respuesta acota la causa.
¿Por qué se desactivó mi webhook de WooCommerce?
WooCommerce desactiva un webhook tras varias entregas fallidas consecutivas: respuestas fuera del rango 2xx o timeouts. Arregla el endpoint receptor y vuelve a activar el webhook. El registro de entregas muestra cada intento fallido.
¿Cómo verifico que un webhook de WooCommerce es auténtico?
Cada entrega incluye una cabecera X-WC-Webhook-Signature: un HMAC-SHA256 del cuerpo de la petición codificado en base64, calculado con el secreto del webhook. Calcúlalo en el lado receptor y compáralos.
$ describe el problema
¿Tienes un problema con WooCommerce?Solicita un diagnóstico.
Cuéntanos qué falla, qué ha cambiado últimamente y cómo afecta al negocio. Revisamos cada solicitud y te recomendamos el siguiente paso.
Nunca envíes contraseñas, claves API ni datos de tarjetas a través del formulario.