# Zapini API — Voice & IVR

**Versión:** 1.0.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**.

---

## API de Voz e IVR

**Ruta base:** `/api/v1/voice`

> **Permiso Requerido:** Las funciones de voz requieren que `twilio_voice_enabled` esté activo en tu cuenta de tenant. Contacta a tu administrador o revendedor para habilitar esta función.

### Modos de Atendimiento

| Modo | Descripción |
|------|-------------|
| `ai_only` | La IA gestiona todas las llamadas entrantes automáticamente |
| `human_only` | Las llamadas se enrutan solo a agentes humanos |
| `ai_with_handoff` | IA primero, luego transfiere a humano si se solicita |
| `ivr_menu` | Menú de Respuesta de Voz Interactiva |

---

## Números de Teléfono

### GET /voice/numbers

Listar todos los números de teléfono Twilio configurados.

```bash
curl -X GET https://zapini.app/api/v1/voice/numbers \
  -H "Authorization: Bearer {token}"
```

**Respuesta:**

```json
{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5511999999999",
      "friendly_name": "Main Line",
      "status": "active",
      "connection_type": "twilio",
      "call_handling_mode": "ai_only",
      "ai_enabled": true,
      "recording_enabled": false,
      "ivr_enabled": false,
      "created_at": "2026-02-14T10:00:00Z"
    }
  ]
}
```

---

### GET /voice/numbers/{uuid}

Obtener detalles de un número de teléfono específico.

---

### PATCH /voice/numbers/{uuid}

Actualizar configuración de gestión de llamadas para un número de teléfono.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| call_handling_mode | string | No | Modo de gestión (ai_only, human_only, ai_with_handoff, ivr_menu) |
| ai_enabled | boolean | No | Habilitar IA para gestión de llamadas |
| recording_enabled | boolean | No | Habilitar grabación de llamadas |
| ai_system_prompt | string | No | Prompt de sistema de IA |

---

## Llamadas (Voz)

### GET /voice/calls

Listar llamadas de voz.

**Parámetros de Consulta:**

| Campo | Tipo | Descripción |
|-------|------|-------------|
| phone_number_uuid | string | Filtrar por número de teléfono |
| status | string | Filtrar por estado (ringing, in-progress, completed, failed) |
| direction | string | Filtrar dirección (inbound, outbound) |
| from | datetime | Fecha de inicio |
| to | datetime | Fecha de fin |
| per_page | integer | Elementos por página |

**Respuesta:**

```json
{
  "success": true,
  "data": [
    {
      "uuid": "call-uuid",
      "sid": "CA...",
      "direction": "inbound",
      "from_number": "+15551234567",
      "to_number": "+5511999999999",
      "status": "completed",
      "duration": 125,
      "recording_url": null,
      "ai_handled": true,
      "started_at": "2026-02-14T10:00:00Z",
      "ended_at": "2026-02-14T10:02:05Z"
    }
  ]
}
```

---

### GET /voice/calls/{uuid}

Obtener detalles completos de una llamada de voz específica, incluyendo transcripción.

---

### POST /voice/calls/{uuid}/transfer

Transferir una llamada activa a otro agente o número.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| target | string | Sí | Número de teléfono destino o dirección SIP del agente |

---

## Menú IVR

### GET /voice/numbers/{uuid}/ivr

Obtener la configuración del menú IVR para un número de teléfono.

---

### PUT /voice/numbers/{uuid}/ivr

Crear o actualizar el menú IVR.

**Parámetros:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| greeting | string | Sí | Mensaje de bienvenida inicial |
| options | array | Sí | Array de opciones del menú |
| options[].digit | string | Sí | Tecla numérica (0-9, *, #) |
| options[].label | string | Sí | Descripción de la opción |
| options[].action | string | Sí | Tipo de acción (forward, ai, department, voicemail) |
| options[].target | string | No | Destino para acción forward |

**Ejemplo:**

```bash
curl -X PUT https://zapini.app/api/v1/voice/numbers/uuid/ivr \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Thank you for calling. Press 1 for Sales, 2 for Support.",
    "options": [
      {"digit": "1", "label": "Sales", "action": "ai", "target": null},
      {"digit": "2", "label": "Support", "action": "forward", "target": "+15559876543"}
    ]
  }'
```

---

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