Este guia explica como converter um componente de integração existente, que atualmente utiliza autenticação legada via /login (AppKey + Token + SankhyaID), para o novo modelo OAuth2, utilizando o endpoint /authenticate, sem a necessidade de criar um novo componente de integração.
A conversão preserva:
- Os clientes já configurados
- Os tokens existentes
- O histórico da solução
1. Visão geral da conversão
A conversão permite que o mesmo componente de integração passe a operar temporariamente em modo híbrido, suportando simultaneamente:
- Autenticação legada (
/login) - Nova autenticação OAuth2 (
/authenticate)
Isso garante uma migração segura, gradual e sem impacto imediato para as integrações em produção.
2. Pré-requisitos
Antes de iniciar a conversão, verifique se:
- Você possui permissão de edição da solução
- O componente de integração utiliza atualmente AppKey
- O componente está ativo
Nenhuma ação precisa ser realizada nos ambientes dos clientes neste momento.
3. Acessando o componente de integração
- Acesse a Área do Desenvolvedor
- Navegue até Soluções
- Selecione a solução desejada
- Abra o Componente de Integração existente
Componente de Integração Legado
Fluxo visual: Minhas Soluções → Lista de Soluções → Detalhe da Solução → Lista de Componentes → Componente de Integração. Detalhe do componente de integração antes da conversão, exibindo apenas AppKey (Sandbox e Produção). Caso o botão Gerar novas chaves não seja exibido, limpe o cache do navegador e tente novamente.
4. Iniciando a conversão para OAuth2
Na tela do componente de integração, será exibido o botão:
“Gerar novas chaves”
Este botão indica que o componente pode ser convertido para o novo modelo de autenticação.
Passos:
- Leia atentamente as instruções exibidas
- Clique em Gerar novas chaves para criar as chaves para autenticação OAuth2**
- Visualize as novas credencias na tela após o processamento
Botão "Gerar novas chaves"
Botão de migração destacado, com texto explicativo informando que não será criado um novo componente.
5. Visualização das credenciais OAuth2
Após a realização do procedimento de Gerar novas chaves:
- O sistema apresentará:
client_idclient_secret
- As credenciais OAuth2 passam a coexistir com:
- AppKey (Produção)
- AppKey (Sandbox)
Importante:
- Ambos os métodos de autenticação funcionam em paralelo
- Nenhuma integração existente é interrompida
Componente de Integração Após Gerar as Novas Credenciais
Tela exibindo AppKey (fluxo legado) + client_id + client_secret ativos simultaneamente. As chaves são geradas tanto para ambiente de Produção quanto ambiente de Sandbox.
6. Atualizando sua aplicação para OAuth2
Com as credenciais OAuth2 disponíveis:
- Atualize sua aplicação para autenticar via endpoint /authenticate
- Veja a documentação completa da autenticação OAuth2 clicando aqui
- Utilize:
client_idclient_secret- O Token fornecido pelo cliente (mesmo
tokenque já é utilizando no /login) é o que deverá ser utilizado como X-Token no novo método de autenticação /authenticate
Recomendamos iniciar os testes em Sandbox antes de aplicar em Produção.
7. Boas práticas recomendadas
- Migre primeiro clientes de menor impacto
- Utilize Sandbox para validação completa
- Registre internamente a data da conversão para avaliar o comportamento após a migração
8. Checklist final de conversão
Antes de concluir, valide:
-
client_ideclient_secretgerados - Aplicação autenticando via
/authenticate - Testes realizados em Sandbox
- Testes realizados em Produção
- Autenticação legada inativada (opcional, mas recomendada)