Errores NetSuite: cómo debuggear INVALID_LOGIN, permisos y OAuth sin adivinar

El problema real con los errores de autenticación en NetSuite

Cuando construyo integraciones entre sistemas y NetSuite, los errores de autenticación son los que más tiempo roban. No es que NetSuite sea complicado — es que la documentación oficial te deja saltando entre cinco páginas distintas y los logs no te dicen dónde está el verdadero problema. INVALID_LOGIN_ATTEMPT suena a contraseña mala, pero puede ser permisos. INSUFFICIENT_PERMISSION te aparece cuando el integration record no tiene scope. Y OAuth 2.0 vs token son dos mundos que parecen iguales pero funcionan distinto.

Lo que he aprendido es que hay un orden lógico para debuggear en lugar de probar al azar. Empecemos.

Paso 1: Valida que la autenticación básica funcione (token o usuario/contraseña)

Antes de pensar en permisos, confirma que el login mismo es válido. Si usas autenticación por token (la clásica), necesitas:

• Usuario y contraseña correctos en el request.
• Token válido (generado en tu usuario de NetSuite, en Manage Tokens).
• El token no está expirado ni revocado.

Para verificar, haz un call simple — por ejemplo, a GET /services/rest/record/v1/employee/1 con headers de autenticación básica. Si te devuelve 401, aquí está el problema. Si te devuelve 200 o 400, la autenticación pasó — el error está en otra parte.

Si usas OAuth 2.0, el flow es distinto: primero obtienes un access_token (que expira), luego lo usas en el header. Si expira, necesitas refrescar. Muchos debuggean mal aquí — ven un 401 y piensan que el usuario está mal, pero es que el token OAuth expiró hace 30 minutos.

Paso 2: Verifica el Integration Record y sus scopes

Aquí es donde 8 de cada 10 integraciones fallan silenciosamente. El integration record es el que define QUÉ permisos tiene tu aplicación en NetSuite. Si no está bien configurado, aunque tu usuario tenga permisos, la integración no los hereda.

Ve a Setup > Integrations > Manage Integrations y busca el tuyo. Verifica:

• Está habilitado (status = Enabled).
• Scopes asignados: ¿Tienes rest.suiteql, rest.record.v1, etc.? Si necesitas leer empleados, asegúrate de que hay scope para ello.
• Token/OAuth activado: Si usas token, ¿está habilitado en la pestaña Tokens? Si usas OAuth, ¿están las URIs de redirect correctas?

Si cambias scopes, el token existente sigue siendo válido, pero la integración no puede hacer más de lo que sus scopes permiten. Muchos generan un token nuevo sin cambiar scopes y se preguntan por qué sigue fallando.

Paso 3: Valida los permisos del usuario (rol y permisos específicos)

Una vez que la autenticación funciona, NetSuite pregunta: ¿qué puede hacer este usuario en este endpoint? Aquí entra el rol. Ve a Setup > Users/Roles > Manage Roles y busca el rol asignado a tu usuario de integración.

Ejemplo: si tu integration hace GET a /employees, el rol necesita permiso de lectura en Employee. Parece obvio, pero muchos usan un rol genérico que no lo tiene. Crea un rol dedicado para la integración con solo los permisos que necesita — es más seguro y más fácil de debuggear.

Paso 4: Lee los logs de autenticación reales

NetSuite tiene un log de intentos fallidos. Ve a Setup > Logs > Authentication o Setup > Logs > API Usage (si tienes SuiteAnalytics). Ahí ves qué usuario, qué hora, qué error exacto. Es más preciso que lo que devuelve el API.

El checklist final antes de lanzar

Cuando todo falla, recorre esto en orden:

1. ¿El usuario de integración existe y no está deshabilitado?
2. ¿El token es válido o el OAuth refrescó correctamente?
3. ¿El integration record está enabled y tiene los scopes correctos?
4. ¿El rol tiene permisos en el registro/endpoint que consultamos?
5. ¿El IP está permitido (si hay restricciones)?

Una vez que todo está verde, la integración debería fluir. El verdadero ahorro de tiempo es no adivinar — validar cada capa por orden.

Si tu punto de venta, tienda en línea o WMS necesita hablar con NetSuite (u Oracle Fusion) y no quieres armar esto a mano cada vez, en Hailan construyo un hub de integraciones que maneja todo esto — autenticación, reintentos automáticos, bitácora por transacción, y un panel donde ves exactamente qué falló y por qué. Así no pierdes horas debuggeando.