OpenAPI
O conector de OpenAPI permite integrar o Power Omni a qualquer (API) que siga o padrão OpenAPI. Através dele, a IA deixa de apenas "conversar" e passa a "executar tarefas" em sistemas externos.
Criação e Identificação do Conector
A criação do Conector ocorre no Portal de Administração (Artefatos > Conectores).
Clique em "Criar" e selecione o tipo "Conector OpenAPI".
Selecione o Projeto do seu Power Omni.
Nome: Identificador interno para gestão no painel. Use nomes claros como "API de Gestão de Estoque" ou "Integração CRM".
Descrição: Este campo é lido pela Inteligência Artificial. Descreva detalhadamente o que este conector faz.
Dica: Quanto melhor a descrição, mais assertiva será a IA ao decidir usar esta ferramenta durante uma conversa.
Autenticação (Segurança)
Para que o Power Omni acesse dados externos, ele precisa se identificar com segurança perante a API de destino.
Tipo de Autenticação:
Anonymous (Sem Autenticação): Usado apenas para APIs que não exigem chaves de acesso.
API Key: Você define o (Header) — geralmente
X-API-KEYouAuthorization— e insere o valor da chave.
Importar conexão existente: Utilize esta opção caso já tenha criado a conexão em outro momento e deseje reutilizá-la.
Criar Nova Conexão: Utilize caso seja a primeira vez configurando a API.
Definição do Schema (OpenAPI)
O Schema é o mapa técnico da API. Ele diz à IA quais "portas" (endpoints) estão abertas, quais informações ela deve enviar e o que ela receberá de volta.
Método de Importação Automático (Via URL)
URL de Especificação: Neste campo, você insere o link direto para o arquivo de especificação da API (Ex:
https://api.suaempresa.com/v1/swagger.json).Botão Buscar Especificação: Ao clicar neste botão, o Power Omni busca a especificação OpenAPI automaticamente.
Método de Importação Manual
Como usar: Você deve copiar o conteúdo da sua especificação OpenAPI e colá-lo diretamente no editor.
Editor de Schema (JSON): Espaço para colar o código da especificação OpenAPI.
Endpoints e Métodos: O schema deve detalhar os métodos suportados, como:
GET: Para buscar informações.POST: Para criar novos registros.PUT/PATCH: Para atualizar dados existentes.
Parâmetros de Entrada: Define quais dados a IA deve extrair da conversa com o usuário para preencher a requisição (Ex:
id_pedido,cpf_cliente).Validação: O sistema validará a estrutura do JSON para garantir que o formato está seguindo os padrões mundiais da OpenAPI 3.0.
Validação
Após configurar a estrutura e a segurança, o conector precisa ser registrado para ficar disponível para os Agentes.
O sistema realiza uma verificação final de sintaxe no Schema. Se houver erros de formatação no JSON, o sistema indicará a linha do erro para correção.
Clique em
.
Passo Final: Relacionando o Conector ao Agente
O Agente só terá acesso às funções da API após o relacionamento.
Acesse a seção de Artefatos > Agentes no Portal de Administração.
Selecione o Agente de IA que precisa interagir com a API.
Navegue até a aba ou seção de Relacionamentos > Conectores.
Na lista de Conectores disponíveis, localize o Conector OpenAPI recém-criado.
Associe o Conector ao Agente.
Clique em "Salvar" para aplicar as alterações.
✅ Boas Práticas e Governança
Ao gerar uma API Key no seu sistema externo, dê permissão apenas para os métodos necessários. Ex: Se a IA só precisa consultar dados, não forneça uma chave com permissão de exclusão (
DELETE).Tratamento de Erros: Certifique-se de que sua API externa retorne mensagens de erro claras (Ex: "Pedido não encontrado"). A IA lerá essa mensagem e poderá explicar ao usuário final o que aconteceu.
Documentação Atualizada: Sempre que a sua API externa mudar (adicionar um novo campo obrigatório, por exemplo), lembre-se de atualizar o Schema nesta tela para evitar falhas na integração.
Atualizado