# 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2F3FMPSmza7FkhspTcY1ZA%2Fimage.png?alt=media&#x26;token=d0aff570-45a2-4cd6-a7f0-f960d5b613cc" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2Fr7dQq8ylc19USaIcZMdj%2Fimage.png?alt=media&#x26;token=11acd8b3-8500-4f49-b903-47ec03f12b54" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FHVEULG0Ob319VjfffsrH%2Fimage.png?alt=media&#x26;token=b2208294-2f68-4100-a939-f5e61a6af15e" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FyqA3Rev7ylFybHG8iXkN%2Fimage.png?alt=media&#x26;token=d501659a-c137-43ce-bb90-a18695aa7131" alt=""><figcaption></figcaption></figure>

  <figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2F9lucjL6ROxOj5DeuNLxS%2Fimage.png?alt=media&#x26;token=ff49ec08-7c1f-464c-b2d7-65df35d9c7f1" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2Fqgirscene26bcKwjp4f9%2Fimage.png?alt=media&#x26;token=563d28f3-3f37-4509-bb5b-4847b770cc82" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FwceHgbZPnJMppmp7NdV1%2Fimage.png?alt=media&#x26;token=ff925c25-e477-43b0-8251-67cbcbf19b5b" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FKpdnAFxgesn4HKi0IVt5%2Fimage.png?alt=media&#x26;token=575ec575-07f4-4088-a757-1954fa6e7057" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FPCThugOIFXtfiFnwZHy6%2Fimage.png?alt=media&#x26;token=c877592d-eb05-4a7d-8e11-fe3549513e63" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FR8srUIt4KpLKAxxMyAW0%2Fimage.png?alt=media&#x26;token=6b1c1209-ad7d-4545-bdd9-9f753a27b969" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FGPRa50vkuDKd7lBy0sCB%2Fimage.png?alt=media&#x26;token=67f9a62d-3961-4e1f-8e31-6e2adf9a54fb" 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="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2F13WPFi4Vhm0DGEOcuNNZ%2Fimage.png?alt=media&#x26;token=135afd13-4e2a-4fc6-b427-618518aa3638" 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.