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

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

  

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

  

  

• Importar Conexión Existente: Utilice esta opción si ya creó la conexión anteriormente y desea reutilizarla.

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

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.

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.

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

Validación

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.