# Zapini API — Funciones Externas

Gestione las funciones externas — endpoints de webhook que permiten a sistemas externos activar acciones de WhatsApp (enviar mensajes, gestionar contactos, controlar automatizaciones). Cada función obtiene una clave API única para autenticación.

**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 | `/external-functions` | Listar todas las funciones externas |
| POST | `/external-functions` | Crear una nueva función externa |
| GET | `/external-functions/{uuid}` | Obtener detalles de función externa |
| PUT | `/external-functions/{uuid}` | Actualizar función externa |
| DELETE | `/external-functions/{uuid}` | Eliminar función externa |
| POST | `/external-functions/{uuid}/toggle` | Activar/desactivar función |
| POST | `/external-functions/{uuid}/regenerate-key` | Regenerar clave API |
| GET | `/external-functions/{uuid}/logs` | Listar registros de ejecución |

---

## Listar Funciones Externas

```
GET /api/v1/external-functions
```

**Parámetros de Consulta:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `instance_uuid` | string | Filtrar por UUID de instancia de WhatsApp |
| `enabled` | boolean | Filtrar por estado habilitado |
| `search` | string | Buscar por nombre, slug 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/external-functions?enabled=true" \
  -H "Authorization: Bearer {token}"
```

---

## Crear Función Externa

```
POST /api/v1/external-functions
```

**Parámetros del Cuerpo:**

| Parámetro | Obligatorio | Tipo | Descripción |
|-----------|-------------|------|-------------|
| `instance_uuid` | Sí | string | UUID de la instancia de WhatsApp |
| `name` | Sí | string | Nombre de la función |
| `slug` | Sí | string | Slug de URL (minúsculas, solo guiones) |
| `action_type` | Sí | string | Tipo de acción (ver abajo) |
| `description` | No | string | Descripción de la función |
| `config` | No | object | Configuración específica de la acción |
| `rate_limit` | No | integer | Máximo de llamadas por día (predeterminado: 1000) |
| `allowed_ips` | No | array | Direcciones IP permitidas (vacío = todas) |
| `is_enabled` | No | boolean | Si la función está activa |

> **Importante:** La `api_key` se devuelve solo una vez en la respuesta de creación. Guárdela de forma segura.

**Ejemplo:**

```bash
curl -X POST "https://zapini.app/api/v1/external-functions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_uuid": "abc-123-def",
    "name": "CRM Order Notification",
    "slug": "crm-order-notify",
    "action_type": "send_message",
    "description": "Sends order status updates from CRM",
    "config": {
      "message_template": "Order {{order_id}}: {{status}}"
    },
    "rate_limit": 500,
    "allowed_ips": ["203.0.113.10"]
  }'
```

**La respuesta incluye:**

```json
{
  "success": true,
  "data": {
    "uuid": "...",
    "api_key": "efk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "api_key_warning": "Store this key securely. It will not be shown again.",
    "endpoint_url": "https://zapini.app/api/v1/external/crm-order-notify",
    ...
  }
}
```

---

## Actualizar Función Externa

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

Mismos parámetros que Crear (excepto que `instance_uuid` es opcional para actualizaciones).

---

## Eliminar Función Externa

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

Elimina la función y todos sus registros de ejecución.

---

## Activar/Desactivar Función Externa

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

Alterna el estado `is_enabled`.

---

## Regenerar Clave API

```
POST /api/v1/external-functions/{uuid}/regenerate-key
```

Genera una nueva clave API e invalida la anterior. La nueva clave solo se devuelve una vez.

**Respuesta:**

```json
{
  "success": true,
  "data": {
    "uuid": "...",
    "api_key": "efk_new_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "api_key_prefix": "efk_new_",
    "api_key_warning": "Store this key securely. It will not be shown again."
  }
}
```

---

## Listar Registros

```
GET /api/v1/external-functions/{uuid}/logs
```

**Parámetros de Consulta:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `status` | string | Filtrar: success, error, unauthorized, rate_limited |
| `per_page` | integer | Resultados por página (máx. 100, predeterminado 20) |

---

## Tipos de Acción Disponibles

| Acción | Descripción |
|--------|-------------|
| `send_message` | Enviar un mensaje de texto |
| `send_buttons` | Enviar un mensaje con botones |
| `send_media` | Enviar multimedia (imagen, video, documento) |
| `create_contact` | Crear un nuevo contacto |
| `update_contact` | Actualizar un contacto existente |
| `create_lead` | Crear un lead en Kanban |
| `update_lead` | Actualizar un lead en Kanban |
| `pause_automation` | Pausar la automatización de IA para una conversación |
| `resume_automation` | Reanudar la automatización de IA para una conversación |

---

## Códigos de Error

| Código | HTTP | Descripción |
|--------|------|-------------|
| `AI_AGENT_NOT_ENABLED` | 403 | No hay integración activa de AI Agent |
| `DUPLICATE_SLUG` | 422 | El slug ya existe para esta cuenta |
| `NOT_FOUND` | 404 | Función o instancia no encontrada |