O criador de integração oferece suporte a tipos de autorização padrão, incluindo chaves da API, tokens do portador, nome de usuário, senha e OAuth 2.0. No entanto, com base nas necessidades e fluxos de trabalho de sua Organização, a autorização padrão pode não ser suficiente. É por isso que o criador de integração também oferece suporte a um tipo de integração personalizada, a integração apenas autenticação, que funciona com as soluções de autenticação e autorização da sua Organização.
Este artigo contém os seguintes tópicos:
- Sobre a autorização personalizada
- Configuração de autorização personalizada
- Teste de autorização personalizada
Sobre a autorização personalizada
A integração apenas autenticação personalizada solicita um token e sua validade, que então são passados aos dados ou à integração principal para autorização para fazer a solicitação dos dados.
No geral, o fluxo de autorização personalizada é o seguinte:
- Solicitação de autorização. A integração apenas autenticação configurada solicita ao servidor a permissão para recuperar um token de acesso. Se o servidor autenticar a solicitação (vinda do Agentes de IA - Avançado), a autorização será concedida para a recuperação do token de acesso e, se disponível, o respectivo prazo de validade.
- Gerenciamento do token. Após o servidor responder com o token de acesso, a integração armazena duas informações importantes: o próprio parâmetro do token e seu parâmetro expiresIn, que determina a validade do token.
- Transmissão do token para a integração de dados. Esses dois parâmetros (token e expiresIn) são passados para a próxima etapa, que é a integração de dados. O token é usado para autenticar solicitações subsequentes feitas pela integração de dados. O token é definido e gerenciado internamente, e nunca é exposto aos dados da sessão ou conversa.
- Solicitação de autorização personalizada para dados. Com o token de acesso implementado, a integração de dados agora tem autorização para recuperar os dados necessários, que são usados para enriquecer a conversa.
O fluxograma abaixo ilustra o fluxo de autorização personalizado.
Configuração de autorização personalizada
Você configura a autorização personalizada como parte do processo normal de criação de uma integração no criador de integração.
Como configurar a autorização personalizada no criador de integração
- No menu principal, clique em Integrações da API.
- No canto superior direito, clique em Adicionar integração.
- Na janela Adicionar integração,
- no campo Nome da integração, dê um nome descritivo à sua integração.
- (Opcional) No campo Descrição, insira uma descrição da integração que ajude você a lembrar para que serve.
- Selecione Configurar como uma integração "apenas autenticação".
- Clique em Salvar.
- Na barra lateral esquerda, em Cenários, passe o mouse sobre Falha, selecione o menu de opções (
) e Apagar. Para autorização personalizada, você precisa apenas de cenários de sucesso. Não é possível apagar cenários de fallback.
- Na página Cenários de sucesso, crie dois parâmetros da sessão (clicando no botão +) com os detalhes a seguir:
- token
- Chave: token (deve ser escrito exatamente assim).
- Consulta: insira um valor que defina o token. Por exemplo: acesso.dados_token.
- expiresIn
- Chave: expiresIn (deve ser escrito exatamente assim).
-
Consulta: insira um valor que defina a validade do token. Por exemplo: dados.expiram_em.
A validade do token pode não fazer parte da resposta dos seus dados. Nesse caso, é possível codificar um valor (em segundos) de sua escolha. Por exemplo: 3600
Recomendamos definir uma validade de token. Se você se deparar com um erro ao testar, esse é o tempo que você precisará esperar antes que um novo token seja emitido. Sem validade, o token é definido indefinidamente, o que significa que você não poderá emitir um novo durante a solução do problema.
- token
- Continue criando a integração normalmente. Para obter ajuda, consulte Explicação sobre o criador de integração.
- Na barra lateral esquerda, em Ambientes, selecione um ambiente (por exemplo, Produção).
- Na aba Autorização, no campo de lista suspensa Tipo de autorização, selecione Personalizado.
- No campo de lista suspensa Integração de autorização da API, selecione a integração apenas autenticação personalizada criada acima.
- Selecione a aba Cabeçalhos e clique em Adicionar cabeçalho.
- Preencha os seguintes campos:
- Chave: Autorização
-
Valor: Portador {{apiToken}} (deve ser escrito exatamente assim)
- Clique em Salvar.
Teste de autorização personalizada
Após configurar sua integração apenas autenticação personalizada, recomendamos testá-la. Para obter ajuda, consulte Testar funcionalidade.
Solução de problemas de statusCode: nulo
Além disso, ao testar sua integração, você pode se deparar com uma mensagem "statusCode: nulo", conforme a imagem abaixo:
Primeiro, verifique novamente se sua integração apenas autenticação personalizada foi configurada corretamente, de acordo com as etapas acima.
Em seguida, anote onde o erro está ocorrendo. Se estiver na integração de autenticação, é provável que algo não esteja configurado corretamente ou a URL para a qual você está fazendo a solicitação pode estar errada. Nesse caso, recomendamos consultar os engenheiros, que podem fornecer mais informações sobre o problema.
Se você seguiu as etapas acima e ainda está encontrando esse erro, aguarde até o token expirar e tente novamente.
Caso tenha tentado todas essas etapas de solução de problemas e a integração continuar não funcionando, entre em contato com seu CSM para obter assistência adicional.