By
·
5 minute read
¿Tu API falla en Adobe Commerce? Desde problemas de tokens "401 Unauthorized" hasta crípticos "500 Internal Server Errors", esta es la guía definitiva para depurar integraciones REST en Magento 2.
Cuando la "Potencia" se Detiene
.svg)
Adobe Commerce (anteriormente Magento 2) es ampliamente reconocido como la plataforma de comercio electrónico más flexible del mercado. Sin embargo, esa flexibilidad tiene un precio: la rigurosidad.
Para los desarrolladores que construyen integraciones —ya sea conectando un ERP, un PIM o una plataforma de automatización de envíos como ShippyPro—, la API REST de Magento puede ser implacable. Una sola coma faltante en un payload JSON o una Lista de Control de Acceso (ACL) mal configurada pueden detener tu sincronización de datos en seco.
A diferencia de otras plataformas que podrían devolver un mensaje de error útil como "Email inválido", Magento a menudo devuelve códigos de estado genéricos que te dejan adivinando.
En esta guía completa, iremos más allá de las definiciones básicas. Deconstruiremos la lógica detrás de los errores de API más frecuentes de Magento, exploraremos los logs del servidor que necesitas vigilar y proporcionaremos correcciones arquitectónicas permanentes para mantener tus integraciones estables.
¿Empezando una nueva integración? Si estás configurando tu conexión por primera vez, sigue nuestra guía paso a paso sobre cómo conectar Magento 2 a ShippyPro.
El "401 Unauthorized" (La Trampa del Token)
.svg)
Este es el obstáculo más común para las nuevas integraciones. Envías una solicitud válida, pero Magento se niega a procesarla.
La Causa Raíz: Tokens de Admin vs. Integración
Magento ofrece múltiples métodos de autenticación. Un error común es usar el endpoint de Admin Token (POST /V1/integration/admin/token) para aplicaciones externas.
- El Problema: Los Tokens de Admin están diseñados para sesiones humanas. Por defecto, caducan después de 4 horas. Si tu script tiene un token "hardcoded" generado ayer, fallará hoy.
- El Síntoma: Tu integración funciona perfectamente durante las pruebas pero falla durante la noche.
La Solución Permanente: Crear una Integración
No aumentes el tiempo de vida del token de administrador (es un riesgo de seguridad). En su lugar, genera un Bearer Token permanente.
- Inicia sesión en tu Panel de Admin de Magento.
- Navega a System > Extensions > Integrations.
- Haz clic en Add New Integration.
- Ponle un nombre (ej. "Conexión ERP") e introduce tu contraseña.
- Paso Crucial: Haz clic en la pestaña API a la izquierda y selecciona los recursos exactos que esta app necesita (ej. "Sales", "Catalog"). No des acceso completo de administrador a menos que sea necesario.
- Guarda y haz clic en Activate.
- Magento mostrará un Access Token.
Resultado: Usa este token en tu cabecera API (Authorization: Bearer <token>). Nunca caduca.
El "404 Not Found" (El Fantasma del Enrutamiento)
Estás mirando la documentación Swagger de Adobe Commerce. El endpoint /V1/products/{sku} definitivamente existe. Sin embargo, cuando lo llamas, obtienes un 404.
La Causa Raíz: Ámbito de la Vista de Tienda (Store View Scope)
Magento 2 tiene una arquitectura multi-tienda. Soporta múltiples sitios web, tiendas y vistas (idiomas) en una sola instalación.
Cuando llamas a la raíz /rest/V1/..., Magento intenta adivinar qué tienda quieres. Si tu configuración es compleja, o si intentas acceder a datos específicos de una tienda (como una descripción de producto traducida), el endpoint raíz fallará.
La Solución: Enrutamiento Explícito
Define siempre el ámbito (scope) en tu estructura de URL.
❌ La Solicitud Ambigua:
GET https://mitienda.com/rest/V1/products/123
✅ La Solicitud Explícita (Tienda por Defecto):
GET https://mitienda.com/rest/default/V1/products/123
✅ La Solicitud Explícita (Ámbito Global):
GET https://mitienda.com/rest/all/V1/products/123
Nota: Usa /all/ cuando quieras valores a nivel de sistema (como precio base). Usa /default/ (o un código específico como /es/) cuando quieras valores específicos del escaparate.
El "400 Bad Request" (El Bibliotecario Estricto)
Un error 400 significa que el servidor recibió tu solicitud pero la rechazó porque los datos no coincidían con el esquema esperado.
Culpables Comunes en Magento 2
- Errores de Sintaxis JSON: Una coma final al final de un objeto JSON es válida en JavaScript pero inválida en JSON estricto. El parser de Magento la rechazará.
- Campos "Requeridos" Faltantes: Si intentas crear una entidad Cliente pero omites los campos email o lastname, la API lanza un 400.
- Incongruencia de Tipo de Atributo: Enviar una cadena "10" a un campo definido como integer o float puede causar errores de validación en modo estricto.
La Solución: Usa tu Swagger Local
No confíes en la documentación online genérica. Magento genera documentación basada en tu instancia específica, incluyendo tus atributos personalizados.
Ve a: https://tu-dominio-magento.com/swagger
Esta página interactiva te muestra el esquema JSON exacto que tu tienda requiere. Prueba tu payload allí primero. Si funciona en Swagger, funcionará en tu código.
El "500 Internal Server Error" (La Caja Negra)
Este es el error más temido porque la respuesta de la API te da cero información. Generalmente solo dice {"message": "Internal Server Error"}.
La Causa Raíz
Un error 500 significa que PHP falló (crasheó). Esto podría deberse a:
- Agotamiento de Memoria: Intentaste cargar 5.000 productos en una sola llamada, golpeando el límite de memoria de PHP.
- Conflicto de Plugin de Terceros: Un "Observer" o "Plugin" activado por tu acción de guardar en la API tiene un bug.
- Bloqueo de Base de Datos: Otro proceso está bloqueando la fila que intentas actualizar.
La Solución: El Comando "Tail"
No puedes depurar un error 500 desde el cliente API (Postman/Insomnia). Debes ir al servidor.
- Conéctate por SSH a tu servidor Magento.
- Navega al directorio raíz.
- Ejecuta este comando para ver los logs en tiempo real:
tail -f var/log/exception.log var/log/system.log - Dispara la llamada a la API de nuevo.
- Analiza: La terminal mostrará el "stack trace". Busca líneas como Uncaught Error: Call to a member function... o SQLSTATE[HY000]: General error. Esto te dice exactamente qué archivo y número de línea causó el fallo.
Matriz de Solución de Problemas (Troubleshooting)
FAQ: Preguntas Frecuentes
¿Por qué mi token de API caduca cada 4 horas?
Esta es la configuración de seguridad predeterminada para tokens de Usuario Admin. Magento asume que un humano ha iniciado sesión. Para evitar esto en scripts automatizados, crea una Integración en el menú del sistema. Las integraciones usan lógica OAuth y proporcionan tokens que no caducan a menos que se revoquen manualmente.
¿Cómo filtro pedidos por fecha en la API?
Magento usa searchCriteria. Para filtrar por fecha, no puedes simplemente añadir ?date=today. Debes construir una cadena de consulta definiendo el campo, el valor y el tipo de condición (como mayor que gt o from).
¿Puedo usar la API para reindexar datos?
Técnicamente sí, pero es peligroso. Disparar una reindexación completa vía API durante horas de alto tráfico puede bloquear tablas de la base de datos y ralentizar el checkout para los clientes. La mejor práctica es dejar que los cron jobs internos de Magento manejen la indexación ("Update on Schedule").
Conclusión: Convierte la Caja Negra en una Casa de Cristal
Depurar Magento requiere paciencia y las herramientas adecuadas. Al pasar de tokens de administrador a integraciones y monitorear tus logs de excepciones, puedes transformar una "caja negra" en un sistema transparente y fiable.
¿Necesitas automatizar tus envíos de Magento sin dolores de cabeza?
Conecta tu tienda a ShippyPro y deja que nuestra integración preconstruida maneje el trabajo pesado.
ShippyPro es el software de envío completo para el comercio online y offline. Con las funciones Label Creator, Track & Trace, Easy Return y Analytics, nuestro software simplifica sus operaciones de envío. ShippyPro se integra con más de 180 transportistas y 80 canales de venta, por lo que es compatible con una amplia gama de productos y casos de uso.