Casi todos los fallos de la API de WooCommerce relacionados con envíos vienen de cuatro sitios: credenciales sin permisos de escritura, la Legacy API desactivada, un servidor que bloquea las peticiones PUT, o datos del transportista en un formato que la API no acepta. Ninguno es un bug de WooCommerce. Por eso mismo los tickets rebotan durante días entre tu tienda y el transportista sin que ninguno de los dos encuentre nada roto.
Aquí tienes cómo saber en cuál de los cuatro casos estás, y cómo una conexión API gestionada elimina la mayoría de ellos.
Un caso del foro de soporte de WooCommerce ilustra bien el patrón. Un comerciante encontraba pedidos marcados como "Completado" mientras esos mismos paquetes seguían parados en el panel del transportista. El transportista culpaba a WooCommerce, WooCommerce culpaba al transportista, y el comerciante estuvo dos semanas en medio. Lo resolvió el log. Todos los cambios de estado apuntaban al mismo sitio:
woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php → update_itemWooCommerce no actualiza sus propios pedidos a través de su REST API. Si un cambio de estado llega por update_item, lo ha enviado un sistema externo. Toda escritura en la REST API de WooCommerce es una petición autenticada que viene de fuera de la tienda, así que la pregunta nunca es "¿está roto WooCommerce?" sino "¿qué integración ha enviado esto y por qué?". Empieza por los logs de webhooks salientes de tu proveedor y normalmente tendrás la respuesta en minutos.
Hazlas en este orden. En la mayoría de casos el fallo desaparece en el tercer paso.
WooCommerce > Ajustes > Avanzado > Legacy API. Tiene que activarlo una cuenta de administrador.
WooCommerce > Ajustes > API > Claves/Apps. Abre la clave existente y cambia el permiso.
Muchos hostings permiten GET y POST pero bloquean PUT. Para devolver los datos de seguimiento hacen falta los tres.
Comprueba que los webhooks estén activos en WooCommerce > Ajustes > Avanzado > WebHooks, e introduce la URL base como https://www.tutienda.es.
Si usas WooCommerce versión 9, necesitas la extensión oficial Legacy REST API de WooCommerce para que la conexión funcione. Ojo: esa extensión no es compatible con HPOS, así que comprueba qué sistema de almacenamiento de pedidos usa tu tienda antes de instalarla.
Cloudflare y los firewalls de servidor suelen bloquear el tráfico de integraciones sin devolver un error útil. Las IPs de ShippyPro son dinámicas, así que no hay una lista fija que autorizar. Crea en su lugar una regla que permita el tráfico con el User Agent "ShippyPro".
Producto y Recursos
Importa los pedidos de WooCommerce, genera etiquetas de Correos, SEUR y MRW y devuelve el seguimiento desde un solo panel.
Explora la plataforma →Reintenta los pedidos fallidos, corrige los datos del destinatario y reasigna transportista sin intervención manual.
Descubre la automatización →Mantén el seguimiento coherente en todos los transportistas, para que el estado del pedido coincida con la realidad.
Descubre Track & Trace →Autenticación, endpoints y eventos de webhook para conectar tus propios sistemas de forma directa.
Consulta la documentación →Conecta tu tienda una sola vez y deja que la integración se encargue de credenciales, reintentos y seguimiento.
Antes de tocar nada, separa los dos tipos de fallo. Un 401 significa que las credenciales fueron rechazadas. Un 403 significa que son válidas, pero el usuario asociado no puede hacer esa operación. Tratar un problema de permisos como uno de credenciales es la razón por la que hay equipos generando clave tras clave sin que cambie nada.
| Error | Qué está pasando en realidad | Solución |
|---|---|---|
| The consumer key is not valid (HTTP 401) | Credenciales rechazadas o revocadas | Crea una conexión de WooCommerce nueva con la opción "Use Consumer and Secret Keys" activada |
| CURL error 28: operation timed out after 60001 ms | Tu hosting llegó a ShippyPro pero no recibió respuesta en 60 segundos | Vuelve a intentar la conexión más tarde |
| Params.from_address.country: must be at most 2 characters long | País de origen guardado con el nombre completo en lugar del código | Ponlo en formato ISO (ES, IT, DE) en WooCommerce > Envíos > ShippyPro Live Shipping Rates |
| Missing parameter app_name | La URL de autorización no incluye app_name | Regenera la conexión para que app_name aparezca en la URL |
| /wc-auth/v1/authorize was not found on this server | La dirección de la tienda es incorrecta | Revisa la dirección de la tienda guardada en el perfil de WooCommerce |
| Los pedidos se importan con la dirección equivocada | El campo de dirección de envío está vacío | ShippyPro importa la dirección de envío de WooCommerce y solo usa la de facturación cuando la primera está vacía |
ShippyPro clasifica los mensajes de error de los transportistas en cinco tipos y asocia a cada uno una descripción y una solución, de forma que una etiqueta fallida te dice qué hacer y no solo que algo ha salido mal. Si trabajas directamente con la API, la sección API de tu cuenta guarda el histórico de llamadas fallidas en View API Errors, y un Status igual a 2 en la respuesta de Ship indica que la llamada salió pero la etiqueta no se creó.
Las peticiones de envío que acaban en timeout devuelven un 500 aunque la etiqueta sí se haya creado. Para evitarlo, envía la llamada Ship con el parámetro Async en true. Recibes al momento una respuesta OK con un número de pedido y luego recuperas la etiqueta con GetLabelURL o mediante el webhook Order Shipped, cuando el transportista la haya generado.
Los dos enfoques funcionan, y WooCommerce ofrece además una shipping method API para plugins que añaden sus propias tarifas. La diferencia está en cómo fallan, y eso es lo que conviene valorar antes de dedicarle horas de desarrollo.
| Criterio | Llamadas API directas al transportista | Conexión gestionada |
|---|---|---|
| Autenticación | Credenciales y lógica de refresco distintas por transportista | Una sola conexión, credenciales gestionadas de forma centralizada |
| Recuperación de etiquetas fallidas | Manual, cuando alguien se da cuenta | Auto-Retry, o un flujo con disparador "Pedido con error" |
| Datos de destinatario erróneos | Corregir y reenviar a mano, pedido a pedido | La acción Autofix recipient info corrige y reintenta la etiqueta |
| Añadir un transportista | Un proyecto de integración nuevo cada vez | Activación desde la biblioteca de integraciones |
| Dónde aparecen los fallos | En tus logs, si alguien los mira | En una vista de Errores propia, con la solución documentada |
El coste de una integración propia casi nunca es el primer desarrollo. Es el mantenimiento: un transportista cambia un campo obligatorio, una dirección supera el límite de caracteres, un timeout tumba un lote de etiquetas a las once de la noche. Una conexión gestionada absorbe ese tipo de problema, y sigues pudiendo usar la API directa para lo que sea realmente a medida.
Cuando una llamada falle, guarda el status code y el mensaje, y deja fuera la consumer secret. No pases nunca secretos en la URL ni amplíes los permisos de un usuario solo para que desaparezca un error. Si un rol más amplio lo arregla, has confirmado que es un problema de permisos, no lo has resuelto.
No lo hace WooCommerce. Es una integración externa que envía una escritura por REST API. Revisa los logs de webhooks salientes de tu proveedor de envíos para localizar la llamada.
Una consumer key no válida o revocada, o una cabecera Authorization que no llega a destino porque la petición no viaja por HTTPS.
Normalmente la Legacy API está desactivada, la clave API es de solo lectura, o el servidor bloquea PUT. Comprueba esos tres puntos antes de mirar el código.
Un CURL error 28 indica que no llegó respuesta en 60 segundos: inténtalo más tarde. Para las peticiones de etiqueta por API, usa la llamada Ship con el parámetro Async en true para que la petición no expire.
Artículos relacionados
Los cinco tipos de API que más peso tienen en una tienda online, incluida la de envíos.
Leer más →Comparativa de automatización, acceso API y cobertura de transportistas españoles.
Leer más →Qué hacer cuando el envío falla después de generar la etiqueta, sin saturar a atención al cliente.
Leer más →Guías prácticas sobre gestión de transportistas, automatización y postventa.
Ver los recursos →Prueba ShippyPro gratis durante 14 días. Sin tarjeta de crédito.