# Zapini API — Funciones de IA

Gestione las funciones de IA (herramientas basadas en webhooks) que su agente de IA puede invocar durante las conversaciones. Cree, configure, pruebe y monitoree funciones personalizadas que amplían las capacidades de su agente de IA.

**Requisito:** Una integración activa de AI Agent en su cuenta.

**URL Base:** `https://zapini.app/api/v1`

**Autenticación:** `Authorization: Bearer {token}`

---

## Endpoints

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/ai-functions` | Listar todas las funciones de IA |
| POST | `/ai-functions` | Crear una nueva función de IA |
| GET | `/ai-functions/executions/{uuid}` | Obtener detalles de ejecución |
| GET | `/ai-functions/{uuid}` | Obtener detalles de una función de IA |
| PUT | `/ai-functions/{uuid}` | Actualizar función de IA |
| DELETE | `/ai-functions/{uuid}` | Eliminar función de IA |
| POST | `/ai-functions/{uuid}/toggle` | Activar/desactivar función |
| POST | `/ai-functions/{uuid}/test` | Probar ejecución de función |
| GET | `/ai-functions/{uuid}/executions` | Listar ejecuciones de función |

---

## Listar Funciones de IA

```
GET /api/v1/ai-functions
```

**Parámetros de Consulta:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `integration_uuid` | string | Filtrar por UUID de integración |
| `type` | string | Filtrar por tipo: `fetch_data`, `collect_submit`, `action` |
| `enabled` | boolean | Filtrar por estado habilitado |
| `search` | string | Buscar por nombre o descripción |
| `per_page` | integer | Resultados por página (máx. 100, predeterminado 20) |

**Ejemplo:**

```bash
curl -X GET "https://zapini.app/api/v1/ai-functions?type=fetch_data&enabled=true" \
  -H "Authorization: Bearer {token}"
```

---

## Crear Función de IA

```
POST /api/v1/ai-functions
```

**Parámetros del Cuerpo:**

| Parámetro | Obligatorio | Tipo | Descripción |
|-----------|-------------|------|-------------|
| `integration_uuid` | Sí | string | UUID de la integración de AI Agent |
| `name` | Sí | string | Nombre de la función (minúsculas, solo guiones bajos) |
| `display_name` | Sí | string | Nombre para mostrar al usuario |
| `description` | Sí | string | Descripción mostrada al agente de IA |
| `type` | Sí | string | `fetch_data`, `collect_submit` o `action` |
| `endpoint_url` | No | string | URL del webhook a invocar |
| `http_method` | No | string | GET, POST, PUT, PATCH, DELETE |
| `auth_type` | No | string | none, bearer, basic, api_key, custom |
| `auth_config` | No | object | Credenciales de autenticación |
| `headers` | No | object | Encabezados HTTP personalizados |
| `request_body_template` | No | object | Plantilla del cuerpo de la solicitud |
| `response_mapping` | No | object | Mapeo de campos de respuesta |
| `success_message` | No | string | Mensaje en caso de éxito |
| `error_message` | No | string | Mensaje en caso de error |
| `requires_confirmation` | No | boolean | Solicitar confirmación al usuario antes de ejecutar |
| `timeout` | No | integer | Tiempo de espera en segundos (1-120) |
| `max_retries` | No | integer | Máximo de reintentos (0-5) |
| `is_enabled` | No | boolean | Si la función está activa |
| `priority` | No | integer | Prioridad de ejecución (0-100) |
| `parameters` | No | array | Array de parámetros de la función |

**Objeto de Parámetro:**

| Campo | Obligatorio | Tipo | Descripción |
|-------|-------------|------|-------------|
| `name` | Sí | string | Nombre del parámetro |
| `display_name` | Sí | string | Nombre para mostrar |
| `description` | No | string | Descripción para la IA |
| `type` | Sí | string | string, number, integer, boolean, email, phone, cpf, cnpj, date, datetime, select, multi_select |
| `is_required` | No | boolean | Si es obligatorio |
| `options` | No | array | Opciones para tipos select |
| `collect_from_user` | No | boolean | Recopilar del usuario en el chat |
| `collect_from_context` | No | boolean | Extraer del contexto |

**Ejemplo:**

```bash
curl -X POST "https://zapini.app/api/v1/ai-functions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_uuid": "abc-123-def",
    "name": "check_order_status",
    "display_name": "Check Order Status",
    "description": "Checks the status of a customer order by order number",
    "type": "fetch_data",
    "endpoint_url": "https://api.myshop.com/orders/status",
    "http_method": "GET",
    "auth_type": "bearer",
    "auth_config": {"token": "my-shop-api-key"},
    "parameters": [
      {
        "name": "order_number",
        "display_name": "Order Number",
        "description": "The customer order number",
        "type": "string",
        "is_required": true,
        "collect_from_user": true
      }
    ]
  }'
```

---

## Obtener Función de IA

```
GET /api/v1/ai-functions/{uuid}
```

Devuelve los detalles de la función con parámetros y estadísticas de ejecución (cantidad de ejecuciones, última ejecución, tasa de éxito de los últimos 30 días).

---

## Actualizar Función de IA

```
PUT /api/v1/ai-functions/{uuid}
```

Mismos parámetros que Crear. Si se proporciona el array `parameters`, todos los parámetros existentes serán reemplazados.

---

## Eliminar Función de IA

```
DELETE /api/v1/ai-functions/{uuid}
```

Falla con `409 ACTIVE_EXECUTIONS` si hay ejecuciones activas en progreso.

---

## Activar/Desactivar Función de IA

```
POST /api/v1/ai-functions/{uuid}/toggle
```

Alterna el estado `is_enabled`.

---

## Probar Función de IA

```
POST /api/v1/ai-functions/{uuid}/test
```

**Cuerpo:**

```json
{
  "parameters": {
    "order_number": "ORD-12345"
  }
}
```

Ejecuta una llamada de prueba al endpoint de la función y devuelve el resultado.

---

## Listar Ejecuciones

```
GET /api/v1/ai-functions/{uuid}/executions
```

**Parámetros de Consulta:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `status` | string | Filtrar: pending, collecting, executing, completed, failed, timeout |
| `per_page` | integer | Resultados por página (máx. 100, predeterminado 20) |

---

## Obtener Detalles de Ejecución

```
GET /api/v1/ai-functions/executions/{uuid}
```

Devuelve los detalles completos de la ejecución, incluyendo datos de solicitud/respuesta, parámetros recopilados e información de tiempos.

---

## Códigos de Error

| Código | HTTP | Descripción |
|--------|------|-------------|
| `AI_AGENT_NOT_ENABLED` | 403 | No hay integración activa de AI Agent |
| `DUPLICATE_NAME` | 422 | El nombre de la función ya existe en la integración |
| `ACTIVE_EXECUTIONS` | 409 | No se puede eliminar mientras hay ejecuciones en progreso |
| `INVALID_INTEGRATION_TYPE` | 422 | La integración no es de tipo AI Agent |
| `TEST_FAILED` | 500 | La ejecución de prueba falló |