# API

<figure><img src="https://content.gitbook.com/content/7nKJZNWmfvaqAyIRrGi4/blobs/W3eIlsIwm7VyC0t6iobm/API%20-%201.png" alt=""><figcaption></figcaption></figure>

Otros sistemas pueden utilizar la inteligencia analítica de Gaio a través de APIs. Esta funcionalidad permite conectar flujos de Gaio con servicios externos mediante APIs REST, utilizando autenticación segura a través de Claves de API.

***

## Cómo Utilizar la API

### 1. Acceder a la Pestaña API

En el panel lateral izquierdo, haz clic en el ícono **API**.

* Utiliza la pestaña **Clave de API** para crear y administrar tus claves.
* Utiliza la pestaña **API** para configurar llamadas a servicios externos.

***

### 2. Crear una Clave de API

<figure><img src="https://content.gitbook.com/content/7nKJZNWmfvaqAyIRrGi4/blobs/Oj1HsEjQlCoM7obmhDhV/API%20-3.png" alt=""><figcaption></figcaption></figure>

1. Haz clic en el botón **“+”** en la esquina superior derecha de la pestaña **Clave de API**.
2. Completa los campos:
   1. **Nombre:** Nombre de la clave (por ejemplo, *Doc*).
   2. **Estado:** Selecciona **Activo**.
3. Haz clic en **Generar**.
4. Una vez generada la clave, cópiala y guárdala de forma segura.
5. Para visualizar o renovar la clave, utiliza el ícono de ojo o el botón de renovar.
6. Haz clic en **Guardar**.

***

### 3. Configurar una Integración de API

<figure><img src="https://content.gitbook.com/content/7nKJZNWmfvaqAyIRrGi4/blobs/w6ytmCUnuvJPk4S8mLYW/SCR-20260121-nqnu.png" alt=""><figcaption></figcaption></figure>

1. Ve a la pestaña **API** y haz clic en **“+”** para agregar una nueva integración.
2. Completa los campos:
   * **Nombre:** Nombre de la integración (por ejemplo, *EnviarACRM*).
   * **Endpoint:** Solo el nombre final del endpoint (por ejemplo, `https://api.example.com/send`).
3. **Configurar el Token de Autorización:**
   1. Elige dónde se leerá el token de autorización.
      1. Ubicaciones compatibles:
         * **Encabezado (recomendado)**
         * Parámetros de consulta (si es requerido)
4. **Seleccionar Flujo** (opcional): Elige el flujo de Gaio que se ejecutará cuando se llame a la API.
5. **Datos de Entrada en una Tabla (opcional):** Opcionalmente, puedes mapear los datos entrantes de la API en una tabla.
   1. Cuando se define:
      1. Los datos de la solicitud entrante se almacenan como filas.
      2. La tabla queda disponible para el flujo ejecutado.
      3. Permite procesamiento por lotes, auditoría y trazabilidad.
6. **Tipo de Salida:** Define cómo se generará la respuesta de la API.
   1. **Tabla:** Devuelve datos desde una tabla.
   2. **Personalizado:** Permite definir manualmente el cuerpo de la respuesta.

**Ejemplo de Respuesta Personalizada**

```json
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "execution_id": "{{ params.execution_id }}"
  }
}

```

7. **Tabla de Retorno:** Selecciona la tabla que contiene los datos que serán consumidos vía API.
8. Ve a la pestaña **Clave de API** y marca la clave creada previamente.
9. Haz clic en **Guardar**.

***

### 4. Tarea API · Herramienta MCP

<figure><img src="https://content.gitbook.com/content/7nKJZNWmfvaqAyIRrGi4/blobs/gNbhSiErBl6OzSy4WiJu/SCR-20260121-olws.png" alt=""><figcaption></figcaption></figure>

La pestaña **Herramienta MCP** permite exponer una Tarea API existente como una herramienta invocable por agentes de IA. Una vez habilitada, la API puede ser llamada programáticamente por agentes durante procesos de razonamiento y ejecución. Esto convierte tu API en una herramienta de IA de primer nivel, utilizable en agentes conversacionales, agentes de flujo y pipelines automatizados de toma de decisiones.

La configuración de la Herramienta MCP define:

* Cómo se presenta la API a los agentes de IA.
* Qué entrada debe proporcionar el agente.
* Si la herramienta está disponible para ejecución.
* Cómo el agente entiende cuándo y por qué debe llamarla.

#### Cómo Configurar la Herramienta MCP

1. Ingresa un nombre claro y orientado a la acción.
2. Describe qué hace la herramienta y cuándo debe utilizarse.
3. Define el esquema de entrada esperado.

```json
{
  "review_text": "string",
  "language": "string"
}

```

4. Haz clic en **Generar** para crear automáticamente un esquema de entrada basado en la configuración de la API.
5. Activa o desactiva el interruptor de **Estado** para habilitar o deshabilitar la herramienta.

***

## 5. Ejecución y Resultados

Después de guardar la configuración:

* La API puede activarse manualmente o como parte de un proceso automatizado en Gaio.
* Si se selecciona un proceso, se ejecutará cada vez que se llame al endpoint de la API de Gaio.

Esto significa que cualquier análisis puede realizarse mediante llamadas externas a Gaio, como:

* Crear o aplicar modelos predictivos
* Insertar o eliminar registros
* Llamar APIs externas (REST)
* Acceder a fuentes de datos externas a Gaio
* Utilizar cualquier otra funcionalidad disponible
* **Límite de Filas:** Es posible limitar el número de filas devueltas por la API de Gaio, incluso si la tabla generada contiene millones de registros.

```
https://your_url/endpoint?limit=10
```

* Paginación con limit y offset

{% code overflow="wrap" %}

```
https://your_url/endpoint?limit=10&offset=10
```

{% endcode %}

* Paginación con limit y page

```
https://your_url/endpoint?limit=10&page=1
```

* Puedes agregar parámetros personalizados para filtrar y personalizar las respuestas de la API según criterios específicos. Si la consulta previa a la tarea API filtra la tabla utilizando este parámetro, solo los datos solicitados serán enviados en el resultado.

{% code overflow="wrap" %}

```
https://your_url/endpoint?limit=10&page=1&param_name_one=sales&param_name_two=male
```

{% endcode %}

{% hint style="warning" %}
Para cada API de Gaio, se genera una clave de acceso única.
{% endhint %}

## Tarea API · Solicitudes en Vivo

<figure><img src="https://content.gitbook.com/content/7nKJZNWmfvaqAyIRrGi4/blobs/TckNZU7hrL58Te8rZ2BC/SCR-20260121-oohc.png" alt=""><figcaption></figcaption></figure>

La pestaña **Solicitudes en Vivo** permite monitorear llamadas a la API en tiempo real después de ejecutar la Tarea API.

Proporciona visibilidad sobre:

* Solicitudes entrantes
* Comportamiento de ejecución
* Datos en tiempo de ejecución

Es una herramienta esencial para depuración y observabilidad.

***

### Qué Puedes Ver

Después de que se llame a la API, cada solicitud aparece en el panel de **Solicitudes en Vivo** con:

* Datos de la solicitud entrante
* Parámetros y carga útil
* Contexto de ejecución
* Respuesta o resultado de ejecución
* Errores (cuando corresponda)

Esta información se muestra en tiempo real, sin necesidad de volver a desplegar ni reiniciar.

***

### Casos de Uso Típicos

* Depuración de problemas de autenticación
* Validación de cargas útiles
* Monitoreo del comportamiento de ejecución de flujos
* Verificación de respuestas personalizadas
* Observación de llamadas API activadas por agentes
* Resolución de problemas en integraciones externas

***

## Buenas Prácticas

* **Seguridad:** Nunca compartas tu Clave de API. Usa el estado **Inactivo** para deshabilitar temporalmente el acceso.
* **Versionado:** Crea nuevas entradas de API cuando existan cambios estructurales.
* **Validación:** Prueba manualmente los endpoints antes de integrarlos en flujos automatizados.
* **Validation**: Test endpoints manually before embedding in automation flows.