WooCommerce / Integraciones
Errores de la REST API de WooCommerce: cómo diagnosticarlos
Respuesta corta
Lee el estado HTTP y el campo code de la respuesta JSON. Un 401 con woocommerce_rest_cannot_view o un error de autenticación significa que la petición no se autenticó o que la clave no tiene permiso. Un 404 rest_no_route significa que la URL o la versión de la API son incorrectas, o que la REST API no es accesible en /wp-json/. Un 403 sin código de error de WooCommerce suele venir de un plugin de seguridad, un WAF o el hosting. Un 500 es un error PHP en la tienda. Prueba la misma llamada con curl para separar el cliente de la tienda.
Síntomas
- Una integración (ERP, CRM, app móvil, conector de marketplace) recibe respuestas 401, 403, 404 o 500.
- Funcionaba antes de un cambio de hosting, una migración a HTTPS, una actualización del plugin de seguridad o un cambio de enlaces permanentes.
- Algunos endpoints funcionan y otros fallan.
- Las peticiones son lentas o superan el tiempo con colecciones grandes.
- Los datos que devuelve la API están desactualizados.
Causas más comunes
| Respuesta | Causa típica |
|---|---|
401 woocommerce_rest_cannot_view |
No autenticada, o el usuario o el permiso de la clave no pueden leer el recurso |
401 woocommerce_rest_authentication_error |
Consumer key no válida, firma no válida (OAuth sobre HTTP) o una marca de tiempo incorrecta |
401 con claves válidas que funcionan en otro sitio |
El servidor elimina la cabecera Authorization antes de que llegue a PHP |
403 sin código de WooCommerce |
Un plugin de seguridad, un WAF, ModSecurity o el hosting bloquean la petición |
404 rest_no_route |
Ruta, versión o método incorrectos; REST API no accesible en /wp-json/ |
500 |
Error fatal de PHP al construir la respuesta |
| Timeouts | per_page muy alto, extensiones pesadas que añaden datos, consultas lentas |
Diagnóstico
1. Reprodúcelo con curl
Saca al cliente de la ecuación. Con una clave de solo lectura, en una copia de staging si es posible:
$ curl -s -i -u ck_your_key:cs_your_secret "https://example.com/wp-json/wc/v3/orders?per_page=1"Si curl funciona y la integración no, el problema está en el cliente: URL, método, cabeceras o la forma en que envía las claves. Si curl falla igual, el problema está en la tienda.
2. Lee el estado y el código de error
El cuerpo JSON contiene un code y un message. Un código de WooCommerce o de WordPress (woocommerce_rest_…, rest_…) significa que la petición llegó a WordPress. Un 403 o una página de error en HTML sin ese código significa que respondió algo que está delante de WordPress.
3. Revisa la clave
En WooCommerce → Ajustes → Avanzado → REST API: ¿existe la clave, tiene el permiso correcto (Lectura, Escritura o Lectura/Escritura), a qué usuario pertenece y cuándo se usó por última vez? Una clave cuyo usuario se borró o perdió su rol fallará.
4. Comprueba que la cabecera Authorization llega a PHP
En algunas configuraciones de Apache con CGI/FastCGI, la cabecera Authorization no se pasa a PHP y la autenticación Basic falla sin avisar. La regla de .htaccess que WordPress suele incluir la deja pasar:
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]5. Revisa lo que hay delante de WordPress
Los plugins de seguridad, el WAF del hosting, ModSecurity y las CDN pueden bloquear las peticiones a /wp-json/, métodos concretos (PUT, DELETE) o user agents desconocidos. Sus registros muestran las peticiones bloqueadas con el motivo.
Registros y comprobaciones técnicas
- La respuesta HTTP completa: estado, cabeceras y cuerpo.
- Claves de la REST API de WooCommerce: permiso, usuario, último acceso.
- WooCommerce → Estado → Registros (
fatal-errors) y el log de errores PHP para las respuestas 500. - Registros del plugin de seguridad, del WAF y de la CDN para las respuestas 403.
- Ajustes → Enlaces permanentes: los enlaces simples desactivan las URL
/wp-json/. - Reglas de caché:
/wp-json/no debe cachearse para peticiones autenticadas.
Soluciones
- Usa HTTPS con autenticación Basic, claves con el permiso mínimo necesario y una clave por integración para poder revocarlas por separado.
- Pasa la cabecera Authorization a PHP cuando el servidor la elimina.
- Permite la API en las capas de seguridad para las rutas y métodos concretos que necesita la integración, en lugar de desactivar la protección.
- Usa la ruta y la versión correctas (
/wp-json/wc/v3/…), y?rest_route=solo donde no haya enlaces permanentes amigables. - Pagina con sensatez: valores moderados de
per_page, y filtrado de campos cuando el cliente lo permita. - Arregla los errores PHP detrás de las respuestas 500; a menudo los causan extensiones que añaden datos a las respuestas de la API.
- Excluye
/wp-json/de la caché de páginas y de la CDN para las peticiones autenticadas.
Qué no hacer
- No des a las integraciones claves de administrador con lectura y escritura cuando basta con lectura.
- No pongas claves en JavaScript del lado del cliente ni compartas una misma clave entre sistemas.
- No desactives por completo el plugin de seguridad para que funcione una integración.
- No subas
per_pageal máximo para «ir más rápido»; las respuestas grandes son más lentas y superan el tiempo más a menudo.
Cuándo recurrir a un experto
Recurre a un ingeniero cuando la integración mueve pedidos, stock o pagos y los fallos causan datos incoherentes, cuando el problema está entre el hosting, las capas de seguridad y el cliente, o cuando hay que rediseñar la integración con reintentos, registros y webhooks.
Problemas relacionados
- 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.
- WooCommerce / Errores Error fatal en WooCommerce: guía práctica para resolverlo Lee bien el error fatal (archivo, línea, traza) y relaciónalo con el cambio que lo provocó.
- WooCommerce / Rendimiento Problemas con Action Scheduler en WooCommerce Acciones programadas vencidas, fallidas y atascadas: cómo funciona la cola, por qué se detiene y cómo arreglarlo sin perder trabajo pendiente.
Preguntas frecuentes
¿Por qué la REST API de WooCommerce devuelve 401 woocommerce_rest_cannot_view?
La petición no se autenticó como un usuario con permiso para leer ese recurso. Revisa las claves, su permiso de lectura o escritura, el usuario al que pertenecen y si la cabecera Authorization llega a PHP.
¿Qué significa rest_no_route?
Ninguna ruta REST coincide con la URL y el método. Revisa la versión de la API en la ruta (como /wp-json/wc/v3/), el método HTTP y que la REST API sea accesible: con los enlaces permanentes simples, /wp-json/ no funciona y hay que usar ?rest_route=.
¿Debo enviar las claves de la API en la URL?
Usa autenticación HTTP Basic sobre HTTPS siempre que puedas. Las claves en la URL acaban en los registros del servidor, en proxies y en la analítica. El método por parámetros de URL existe para servidores que eliminan la cabecera Authorization.
¿Por qué las respuestas de la API parecen desactualizadas?
Puede que una capa de caché (una CDN o una caché de páginas) esté cacheando las respuestas de /wp-json/. Las respuestas de la API a peticiones autenticadas nunca deben cachearse.