> For the complete documentation index, see [llms.txt](https://docs.poweromni.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.poweromni.ai/administracao-e-configuracao/artefatos/conectores/openapi.md).

# OpenAPI

### 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".

<figure><img src="/files/NieBCxjdCgujuueoCzcQ" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/7S5hlbGdHKjLkGckoIDv" alt=""><figcaption></figcaption></figure>

* 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.

  <figure><img src="/files/vSMG0L0LOWKUzsfmQqJz" alt=""><figcaption></figcaption></figure>

  * API Key: Você define o (Header) — geralmente `X-API-KEY` ou `Authorization` — e insere o valor da chave.

  <figure><img src="/files/DVN11i5hqNI0W7avck3k" alt=""><figcaption></figcaption></figure>

  <figure><img src="/files/IcCwajsfhNnzjkIg4wMw" alt=""><figcaption></figcaption></figure>
* **Importar conexão existente**: Utilize esta opção caso já tenha criado a conexão em outro momento e deseje reutilizá-la.

<figure><img src="/files/hrgtEdS8iY6gqsWNOHss" alt=""><figcaption></figcaption></figure>

* **Criar Nova Conexão**: Utilize caso seja a primeira vez configurando a API.&#x20;

<figure><img src="/files/QAvJRAG58RIFhrTga1vq" alt=""><figcaption></figcaption></figure>

***

### 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.

<figure><img src="/files/l2e3d5vB6v0szB9775HY" alt=""><figcaption></figcaption></figure>

#### 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.

<figure><img src="/files/vqZwzrg62iRxngfYHQ61" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/WLs0l2IkViSLd8WHWSb4" alt=""><figcaption></figcaption></figure>

* 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.

<figure><img src="/files/O4fZQaNlIUGfLoU4U6cw" alt=""><figcaption></figcaption></figure>

***

### Validação&#x20;

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 <img src="/files/WY6VwbLnQEtgwCn17H6E" alt="" data-size="line">.

### 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.