# Zapini API — Automatizaciones

**Versión:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Autenticación

Todos los endpoints requieren un Bearer Token:

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

Genera tokens de API en el panel admin en **API Docs → Gestionar Tokens**.

---

## Control de Automatización

Gestiona la automatización de IA para conversaciones. Cuando la automatización está activa, los mensajes manuales están bloqueados hasta que tomes el control del chat.

**Base URL:** `/api/v1/chat`

### Importante: Comportamiento de la Automatización

- Cuando la automatización está **activa**, los mensajes manuales están bloqueados para evitar conflictos con las respuestas de IA.
- Usa **pause** para tomar el control del chat y enviar mensajes manualmente.
- Usa **resume** para dejar que la IA maneje la conversación nuevamente.
- **IMPORTANTE**: Para reanudar la automatización, primero debes **archivar** la conversación.

> **Seguridad: Archivo Requerido para Reanudar**
>
> La automatización solo puede reanudarse después de archivar la conversación. Esto asegura que la sesión de atención manual se cierre correctamente antes de devolver el control a la IA. Al reanudar, la conversación será desarchivada automáticamente.

---

### POST /chat/conversations/{uuid}/pause-automation

Pausa la automatización para una conversación, permitiendo mensajes manuales.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| reason | string | No | Razón opcional para pausar la automatización |

**Ejemplo de Solicitud:**

```bash
curl -X POST https://zapini.app/api/v1/chat/conversations/550e8400-e29b-41d4-a716-446655440045/pause-automation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Manual takeover for VIP client"}'
```

**Respuesta:**

```json
{
  "success": true,
  "message": "Automation paused successfully.",
  "data": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440045",
    "automation_paused": true,
    "paused_at": "2025-12-20T14:30:00Z",
    "paused_by": "John Doe",
    "reason": "Manual takeover for VIP client"
  }
}
```

**Códigos de Error:**

| Código | Error | Descripción |
|--------|-------|-------------|
| 400 | NO_ACTIVE_AUTOMATION | La conversación no tiene automatización activa |
| 400 | AUTOMATION_ALREADY_PAUSED | La automatización ya está pausada |
| 404 | NOT_FOUND | Conversación no encontrada |

---

### POST /chat/conversations/{uuid}/resume-automation

Reanuda la automatización para una conversación, dejando que la IA gestione las respuestas.

> **Nota:** La conversación debe estar archivada antes de reanudar la automatización.

**Ejemplo de Solicitud:**

```bash
curl -X POST https://zapini.app/api/v1/chat/conversations/550e8400-e29b-41d4-a716-446655440045/resume-automation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
```

**Respuesta:**

```json
{
  "success": true,
  "message": "Automation resumed successfully.",
  "data": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440045",
    "automation_paused": false,
    "resumed_at": "2025-12-20T15:00:00Z"
  }
}
```

**Códigos de Error:**

| Código | Error | Descripción |
|--------|-------|-------------|
| 400 | NO_ACTIVE_AUTOMATION | La conversación no tiene automatización activa |
| 400 | AUTOMATION_NOT_PAUSED | La automatización no está pausada actualmente |
| 404 | NOT_FOUND | Conversación no encontrada |

---

*Generado por Zapini — https://zapini.app*