# OpenAPI

### Creación e Identificación del Conector

El Conector se crea en el Portal de Administración (**Artefactos > Conectores**).

* Haga clic en **"Crear"** y seleccione el tipo **"Conector OpenAPI"**.

<figure><img src="../../../.gitbook/assets/image (14) (1).png" alt=""><figcaption></figcaption></figure>

<figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-painel-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-painel-dark.png" alt=""><figcaption></figcaption></figure>

* Seleccione su **Proyecto** de Power Omni.
* **Nombre:** Identificador interno para la gestión en el panel. Utilice nombres claros como “API de Gestión de Inventario” o “Integración con CRM”.
* **Descripción:** Este campo es leído por la Inteligencia Artificial. Proporcione una descripción detallada de lo que hace este conector.
  * **Consejo:** Cuanto mejor sea la descripción, con mayor precisión decidirá la IA utilizar esta herramienta durante una conversación.

***

### Autenticación (Seguridad)

Para que Power Omni acceda a datos externos, debe identificarse de forma segura ante la API de destino.

*   **Tipo de Autenticación:**

    * **Anónima (Sin Autenticación):** Se utiliza solo para APIs que no requieren claves de acceso.

    <figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-auth-anonymous-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-auth-anonymous-dark.png" alt=""><figcaption></figcaption></figure>

    * **API Key:** Usted define el Header — generalmente `X-API-KEY` o `Authorization` — e ingresa el valor de la clave.

    <figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-auth-apikey-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-auth-apikey-dark.png" alt=""><figcaption></figcaption></figure>

    <figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-chaves-modal-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-chaves-modal-dark.png" alt=""><figcaption></figcaption></figure>
* **Importar Conexión Existente:** Utilice esta opción si ya creó la conexión anteriormente y desea reutilizarla.

<figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-conexao-importar-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-conexao-importar-dark.png" alt=""><figcaption></figcaption></figure>

* **Crear Nueva Conexión:** Utilice esta opción si es la primera vez que configura la API.

<figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-conexao-nova-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-conexao-nova-dark.png" alt=""><figcaption></figcaption></figure>

***

### Definición del Esquema (OpenAPI)

El Esquema es el mapa técnico de la API. Le indica a la IA qué “puertas” (endpoints) están disponibles, qué información debe enviar y qué recibirá a cambio.

#### Método de Importación Automática (Vía URL)

* **URL de la Especificación:** En este campo, ingrese el enlace directo al archivo de especificación de la API (Ej.: https://api.yourcompany.com/v1/swagger.json).
* **Botón Obtener Especificación:** Al hacer clic, Power Omni recupera automáticamente la especificación OpenAPI.

<figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-schema-automatico-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-schema-automatico-dark.png" alt=""><figcaption></figcaption></figure>

#### Método de Importación Manual

* **Cómo Usar:** Copie el contenido de su especificación OpenAPI y péguelo directamente en el editor.
* **Editor de Esquema (JSON):** Área para pegar el código de la especificación OpenAPI.

<figure><img src="../../../.gitbook/assets/image (10) (1) (1).png" alt=""><figcaption></figcaption></figure>

<figure><img class="only-light" src="../../../.gitbook/assets/telas/con-openapi-schema-erro-light.png" alt=""><img class="only-dark" src="../../../.gitbook/assets/telas/con-openapi-schema-erro-dark.png" alt=""><figcaption></figcaption></figure>

* **Endpoints y Métodos:** El esquema debe detallar los métodos admitidos, tales como:
  * `GET`: Para recuperar información.
  * `POST`: Para crear nuevos registros.
  * `PUT/PATCH`: Para actualizar datos existentes.
* **Parámetros de Entrada:** Define qué datos debe extraer la IA de la conversación del usuario para completar la solicitud (Ej.: order\_id, customer\_cpf).
* **Validación:** El sistema validará la estructura JSON para garantizar que el formato siga los estándares de OpenAPI 3.0.

<figure><img src="../../../.gitbook/assets/image (11) (1) (1).png" alt=""><figcaption></figcaption></figure>

***

### Validación&#x20;

Después de configurar la estructura y la seguridad, el conector debe registrarse para estar disponible para los Agentes.

* El sistema realiza una verificación final de sintaxis del Esquema. Si hay errores de formato en el JSON, el sistema indicará la línea del error para su corrección.
* Haga clic en **Guardar**.

### Paso Final: Vinculación del Conector al Agente

El Agente solo tendrá acceso a las funciones de la API después de que la relación esté configurada.

* Vaya a **Artefactos > Agentes** en el Portal de Administración.
* Seleccione el Agente de IA que necesita interactuar con la API.
* Navegue a la pestaña o sección **Relaciones > Conectores**.
* En la lista de Conectores disponibles, localice el Conector OpenAPI recién creado.
* Asocie el Conector con el Agente.
* Haga clic en **"Guardar"** para aplicar los cambios.

***

### ✅ Mejores Prácticas y Gobernanza

* Al generar una API Key en su sistema externo, otorgue permiso solo para los métodos necesarios. Ejemplo: si la IA solo necesita recuperar datos, no proporcione una clave con permisos de DELETE.
* **Manejo de Errores:** Asegúrese de que su API externa devuelva mensajes de error claros (Ej.: “Pedido no encontrado”). La IA leerá este mensaje y podrá explicar al usuario final lo que ocurrió.
* **Documentación Actualizada:** Siempre que su API externa cambie (por ejemplo, al agregar un nuevo campo obligatorio), recuerde actualizar el Esquema en esta pantalla para evitar fallas de integración.