OpenAPI | Power Omni Docs

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-KEY ou Authorization — 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.