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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.poweromni.ai/administracao-e-configuracao/artefatos/conectores/openapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.