Migração de Token UUID para JWT no Salesforce Commerce Cloud: o que ainda importa saber

O Salesforce descontinuou o formato de token UUID para Clientes de API no Commerce Cloud Account Manager a partir de 15 de junho de 2023. Na prática, isso significa que qualquer Cliente de API ainda configurado com token UUID passou (ou deveria ter passado) a usar o formato JWT — automaticamente ou por ação manual da equipe responsável pela integração.

Se você lidera arquitetura de e-commerce em Salesforce Commerce Cloud e herdou integrações antigas, vale revisar esse ponto agora: Clientes de API criados antes da mudança podem carregar configurações legadas, código que valida o token pelo formato antigo, ou documentação interna desatualizada. Este artigo cobre o que mudou, quem foi afetado, e como validar e migrar um Cliente de API de UUID para JWT.

O que mudou na autenticação de Clientes de API

Antes da deprecação, o Commerce Cloud Account Manager suportava dois formatos de token de acesso para Clientes de API: UUID e JWT. A partir de 15 de junho de 2023, o Salesforce deixou de suportar o formato UUID. Clientes de API que continuassem operando com esse formato passaram a apresentar falhas de autenticação — um risco direto para qualquer fluxo que dependa de chamadas autenticadas contra a API do Commerce Cloud (OCAPI, Data API, integrações de terceiros).

O cronograma anunciado foi direto:

• A partir de 15/06/2023: o formato UUID deixou de ser suportado para Clientes de API.

• A partir de 15/06/2023: todos os Clientes de API ainda configurados com UUID foram convertidos para o formato JWT.

Ou seja, mesmo quem não migrou manualmente teve o token convertido — mas isso não elimina o risco de quebra em código que dependia de características específicas do formato antigo (mais sobre isso adiante).

Quem é afetado por essa mudança

O impacto recai sobre qualquer cliente Commerce Cloud com aplicações de Cliente de API configuradas para usar token de acesso no formato UUID. Isso inclui:

• Integrações de terceiros (ERPs, PIMs, plataformas de pagamento) autenticadas via Client Credentials.

• Scripts internos de automação que chamam OCAPI/Data API.

• Ferramentas de CI/CD ou monitoramento que autenticam contra o Account Manager.

Para um tech lead, o ponto relevante não é só "o token mudou de formato" — é mapear todos os Clientes de API sob sua responsabilidade e confirmar que nenhum deles carrega dependência oculta do formato UUID.

Como verificar e migrar um Cliente de API para JWT

O processo de verificação e migração é feito diretamente no Account Manager:

1. Faça login no Account Manager.

2. Acesse Cliente de API. A página lista todos os Clientes de API existentes.

3. Filtre pela opção de formato de token, selecione UUID e liste os Clientes de API que ainda usam esse formato.

4. Clique em um Cliente de API com UUID para abrir sua página de configuração.

5. Role até o final da página e altere o Formato de Token de Acesso para JWT.

6. Clique em Salvar e repita o processo para cada Cliente de API identificado no filtro.

Esse é um procedimento operacional simples — o risco real não está no clique, está no código que consome o token.

O trade-off técnico: o que pode quebrar depois da migração

Na maioria dos casos, trocar o formato de token para JWT não exige nenhuma alteração no código do Cliente de API. O problema aparece em uma situação específica, mas comum em integrações mais antigas: código que valida o token verificando seu comprimento (length) como parte da lógica de autenticação.

Tokens UUID têm um padrão de tamanho previsível. Tokens JWT não. Se alguma rotina de validação — de um middleware de integração, um script de monitoramento ou um wrapper de autenticação customizado — ainda checa o comprimento do token como critério de validade, essa checagem vai falhar depois da migração, mesmo que a autenticação em si esteja correta.

Esse é o tipo de dívida técnica silenciosa: funciona até o dia em que o token muda de formato e a chamada começa a falhar sem uma causa óbvia no log. Vale revisar esse ponto antes de fechar a migração como concluída, especialmente em integrações que ninguém no time atual escreveu originalmente.

Testando a migração

Para validar o comportamento de autenticação com os dois formatos de token antes e depois da migração, existe uma coleção Postman pública com os cenários de UUID e JWT lado a lado:

Coleção Postman — UUID vs JWT (Github)

Rodar essa validação em ambiente de sandbox antes de tocar produção é a forma mais direta de confirmar que nenhuma integração downstream depende de premissas do formato antigo.

Conclusão

A deprecação do token UUID no Commerce Cloud Account Manager já está em vigor desde junho de 2023, e o Salesforce migrou automaticamente os Clientes de API remanescentes para JWT. O risco que sobra não é de configuração — é de código legado que assume características do formato antigo. Mapear os Clientes de API sob sua responsabilidade, revisar validações de token por comprimento e testar a autenticação em sandbox é o suficiente para fechar esse ponto sem surpresas em produção.