Oracle Fusion API: por qué fallan tus integraciones (y cómo debuguearlas)

El 401 vs 403: token muerto vs permisos insuficientes

Uno de los errores más confusos es recibir un 401 (Unauthorized) cuando creías que tu token era válido. En realidad, Oracle Fusion distingue entre dos cosas: si el token existe y si el usuario tiene permiso para hacer eso.

401 significa que el token expiró, es inválido o la credencial de OAuth está rota. Para debuguearlo: verifica en Oracle Identity Cloud Service que el token siga siendo válido (Oracle tiene tokens con vidas cortas, a veces menos de una hora). Revisa también que el scope del token incluya https://your-fusion-instance.oraclecloud.com.

403 es más común de lo que crees: el token es válido, pero el usuario no tiene rol para acceder a ese recurso. Por ejemplo, puedes leer /fscmService/rest/v2/items pero no tienes permiso para crear. Solución: en Oracle Fusion, ve a Setup > Security > Users, abre el usuario técnico que usa la API, y asigna el rol Functional Administrator o el rol específico que necesites (como Inventory Administrator si integras inventario).

El 400 con mensaje que no dice nada

Recibes: 'Bad Request' o 'Invalid JSON' sin más detalles. Es frustrante porque el JSON se ve correcto. Aquí va lo que realmente pasa:

• Flexfields obligatorios invisibles: Oracle Fusion tiene campos personalizados (flexfields) que no ves en la documentación estándar. El API rechaza el registro porque falta un flexfield requerido. Solución: en Fusion, ve a Setup > Extensibility > Flexfields > Segments, busca tu entidad (por ejemplo, Sueldos o Proveedores) y revisa qué segmentos están marcados como obligatorios. Luego inclúyelos en el payload JSON con la clave exacta: 'Attribute1', 'Attribute2', etc.
• Formato de fecha incorrecto: Oracle espera YYYY-MM-DD para fechas, pero a veces el sistema rechaza si hay zona horaria o milisegundos. Usa siempre '2024-01-15', nunca '2024-01-15T10:30:00Z' a menos que sea explícitamente un timestamp.
• Moneda y decimales: Si integras precios o montos, Oracle es estricto con el formato numérico. Envía 100.50 como número, no como string. Y especifica siempre el código de moneda en un campo aparte (como 'currencyCode': 'MXN').

El clásico 500 que en realidad es una validación

Aquí está el truco sucio: Oracle Fusion devuelve 500 Internal Server Error cuando una validación de negocio falla, no cuando hay un error real del servidor. Ejemplo: intentas crear una factura de proveedor con un proveedor que no existe, y recibes 500 en lugar de 400.

Para encontrar el registro que falló y la razón real, tienes dos caminos:

1. Revisa los logs de Fusion: Ve a Setup > Monitoring > Logs > Integration Cloud (si usas Oracle Integration Cloud) o Logs > REST API Calls. Busca tu request por timestamp y lee el mensaje de error completo — ahí aparece qué validación falló.
2. Usa el ID de transacción: Cada request a Fusion lleva un header X-Oracle-Request-ID. Guarda ese ID y búscalo en Setup > Monitoring > Audit Trail. Eso te muestra exactamente qué pasó en el backend.
3. Prueba en Postman con headers completos: Asegúrate de incluir 'Content-Type': 'application/json' y 'Authorization': 'Bearer [tu-token]'. A veces el error es que falta un header.

Cómo encontrar el registro que falló

Una vez que identificas el error, necesitas localizar el registro en Fusion para corregirlo. Si el error es en un proveedor, ve a Procurement > Suppliers y busca por nombre o código. Si es un item de inventario, ve a Inventory > Items. Usa el nombre o el ID externo que enviaste en el JSON.

Para integraciones más grandes, donde cientos de registros se sincronizan diariamente, esto se vuelve tedioso. Por eso construyo en Hailan un hub de integraciones que conecta tu punto de venta, tienda en línea, WMS o sistema propio con Oracle Fusion o NetSuite. Cada transacción queda registrada en una bitácora con el payload exacto, el error (si hubo), y un link directo al registro en Fusion. Los reintentos automáticos evitan que un error temporal rompa todo, y el panel te muestra en tiempo real qué falló y por qué — sin necesidad de cavar en logs de Oracle.