Migración de Token UUID a JWT en Salesforce Commerce Cloud

Salesforce descontinuó el formato de token UUID para Clientes de API en Commerce Cloud Account Manager a partir del 15 de junio de 2023. En la práctica, esto significa que cualquier Cliente de API que aún estuviera configurado con token UUID pasó (o debería haber pasado) a usar el formato JWT, ya sea de forma automática o mediante acción manual del equipo responsable de la integración.

Si lideras arquitectura de e-commerce en Salesforce Commerce Cloud y heredaste integraciones antiguas, conviene revisar este punto ahora: los Clientes de API creados antes del cambio pueden tener configuraciones heredadas, código que valida el token según el formato antiguo, o documentación interna desactualizada. Este artículo cubre qué cambió, a quién afectó y cómo validar y migrar un Cliente de API de UUID a JWT.

Qué cambió en la autenticación de Clientes de API

Antes de la deprecación, el Commerce Cloud Account Manager soportaba dos formatos de token de acceso para Clientes de API: UUID y JWT. A partir del 15 de junio de 2023, Salesforce dejó de dar soporte al formato UUID. Los Clientes de API que continuaran operando con ese formato empezaron a presentar fallos de autenticación, un riesgo directo para cualquier flujo que dependa de llamadas autenticadas contra la API de Commerce Cloud (OCAPI, Data API, integraciones de terceros).

El cronograma anunciado fue directo:

• A partir del 15/06/2023: el formato UUID dejó de ser soportado para Clientes de API.

• A partir del 15/06/2023: todos los Clientes de API que aún estaban configurados con UUID fueron convertidos automáticamente al formato JWT.

Es decir, incluso quienes no migraron manualmente tuvieron el token convertido, pero eso no elimina el riesgo de rotura en código que dependía de características específicas del formato antiguo (más sobre esto más adelante).

Quién se ve afectado por este cambio

El impacto recae sobre cualquier cliente de Commerce Cloud con aplicaciones de Cliente de API configuradas para usar token de acceso en formato UUID. Esto incluye:

• Integraciones de terceros (ERP, PIM, plataformas de pago) autenticadas vía Client Credentials.

• Scripts internos de automatización que llaman a OCAPI/Data API.

• Herramientas de CI/CD o monitorización que autentican contra el Account Manager.

Para un tech lead, lo relevante no es solo "el token cambió de formato", sino mapear todos los Clientes de API bajo su responsabilidad y confirmar que ninguno arrastra una dependencia oculta del formato UUID. Un fallo de autenticación silencioso en producción no es solo un problema operativo: también es una brecha de seguridad en e-commerce si algún endpoint queda expuesto por una validación mal implementada durante la transición.

Cómo verificar y migrar un Cliente de API a JWT

El proceso de verificación y migración se realiza directamente en el Account Manager:

1. Inicia sesión en el Account Manager.

2. Accede a Cliente de API. La página lista todos los Clientes de API existentes.

3. Filtra por la opción de formato de token, selecciona UUID y obtén el listado de los Clientes de API que aún usan ese formato.

4. Haz clic en un Cliente de API con UUID para abrir su página de configuración.

5. Desplázate hasta el final de la página y cambia el Formato de Token de Acceso a JWT.

6. Haz clic en Guardar y repite el proceso para cada Cliente de API identificado en el filtro.

Este es un procedimiento operativo sencillo. El riesgo real no está en el clic, está en el código que consume el token.

El trade-off técnico: qué puede romperse después de la migración

En la mayoría de los casos, cambiar el formato de token a JWT no requiere ninguna modificación en el código del Cliente de API. El problema aparece en una situación específica, pero común en integraciones más antiguas: código que valida el token verificando su longitud (length) como parte de la lógica de autenticación.

Los tokens UUID tienen un patrón de tamaño predecible. Los tokens JWT no. Si alguna rutina de validación (un middleware de integración, un script de monitorización o un wrapper de autenticación personalizado) todavía verifica la longitud del token como criterio de validez, esa verificación fallará después de la migración, aunque la autenticación en sí sea correcta.

Este es el tipo de deuda técnica silenciosa: funciona hasta el día en que el token cambia de formato y la llamada empieza a fallar sin una causa obvia en el log. Vale la pena revisar este punto antes de dar la migración por cerrada, especialmente en integraciones que nadie del equipo actual escribió originalmente.

Cómo probar la migración

Para validar el comportamiento de autenticación con ambos formatos de token, antes y después de la migración, existe una colección Postman pública con los escenarios de UUID y JWT lado a lado:

Colección Postman, UUID vs JWT (GitHub)

Ejecutar esta validación en un entorno de sandbox antes de tocar producción es la forma más directa de confirmar que ninguna integración downstream depende de premisas del formato antiguo.

Conclusión

La deprecación del token UUID en Commerce Cloud Account Manager está vigente desde junio de 2023, y Salesforce migró automáticamente los Clientes de API restantes a JWT. El riesgo que queda no es de configuración, es de código heredado que asume características del formato antiguo. Mapear los Clientes de API bajo tu responsabilidad, revisar validaciones de token por longitud y probar la autenticación en sandbox es suficiente para cerrar este punto sin sorpresas en producción.

Si esta migración expuso otras dependencias heredadas en tu arquitectura de Salesforce Commerce Cloud, o si quieres revisar la integración antes de darla por resuelta, vale la pena agendar una conversación con Develoci para discutir el caso específico de tu entorno.