# API de Llamadas

> 🚀 **Motor de voz VPower.** Estamos pasando los agentes de voz a VPower y el motor anterior quedará deprecado. Las rutas y tu `agent_id` no cambian: revisa la [guía de migración a VPower](migrar-a-vpower.md) para confirmar que tu integración está lista.

La API de Llamadas de Anunzi te permite gestionar llamadas de voz en tiempo real de forma programática. Puedes iniciar llamadas telefónicas y web, consultar registros, actualizar metadatos, detener llamadas activas y obtener la configuración completa de tus agentes.

---

## URL base

Todas las solicitudes se realizan a:

```
https://calls.anunzi.net
```

---

## Autenticación

Todas las solicitudes deben incluir tu API Key en el encabezado HTTP:

```
Authorization: Bearer anz_live_TU_API_KEY
```

Genera tu API Key desde el menú del usuario → **API Keys** en el panel de Anunzi (ver [API Keys de cuenta](../api/api-keys.md)). Cada operación queda **limitada automáticamente a los agentes de tu cuenta** (y a los de tus clientes, si eres partner): no puedes operar llamadas ni agentes de otras cuentas.

---

## Endpoints disponibles

| Método | Ruta | Descripción |
|--------|------|-------------|
| `POST` | `/v2/create-phone-call` | Inicia una llamada telefónica saliente |
| `POST` | `/v3/create-web-call` | Crea una llamada web desde el navegador ([migrar desde v2](migrar-llamadas-web-v3.md)) |
| `GET` | `/v2/get-call/{call_id}` | Obtiene el detalle de una llamada |
| `POST` | `/v3/list-calls` | Lista llamadas con filtros y paginación |
| `PATCH` | `/v2/update-call/{call_id}` | Actualiza metadatos de una llamada |
| `POST` | `/v2/stop-call/{call_id}` | Detiene una llamada en curso |
| `DELETE` | `/v2/delete-call/{call_id}` | Elimina el registro de una llamada |
| `GET` | `/get-agent/{agent_id}` | Obtiene la configuración completa de un agente |

### Gestión de agentes (motor de voz VPower)

| Método | Ruta | Descripción |
|--------|------|-------------|
| `GET` | `/list-agents` | Lista tus agentes de voz ([ver](gestionar-agentes.md#listar-agentes)) |
| `PATCH` | `/update-agent/{agent_id}` | Cambia voz, idioma, comportamiento, extractores… ([ver](gestionar-agentes.md#actualizar-agente)) |
| `POST` | `/publish-agent/{agent_id}` | Pone en uso los cambios ([ver](gestionar-agentes.md#publicar-agente)) |
| `GET` | `/get-agent-versions/{agent_id}` | Historial de versiones ([ver](gestionar-agentes.md#versiones-del-agente)) |
| `GET` | `/get-retell-llm/{llm_id}` | Prompt, mensaje inicial, modelo y funciones ([ver](prompt-y-funciones.md)) |
| `PATCH` | `/update-retell-llm/{llm_id}` | Cambia prompt, mensaje inicial, modelo y funciones ([ver](prompt-y-funciones.md#actualizar)) |
| `GET` | `/list-voices` | Voces disponibles ([ver](voces-y-numeros.md#listar-voces)) |
| `GET` | `/get-voice/{voice_id}` | Una voz ([ver](voces-y-numeros.md#obtener-una-voz)) |
| `GET` | `/list-phone-numbers` | Números de tu cuenta ([ver](voces-y-numeros.md#listar-numeros)) |

Para contactos, campañas, mensajes, créditos y webhooks de la plataforma, usa la [API de la plataforma](../api/README.md).

---

## Códigos de error comunes

| Código | Descripción |
|--------|-------------|
| `400` | Formato de solicitud inválido. Verifica los parámetros enviados. |
| `409` | Operación de gestión sobre un agente que todavía no está en el motor de voz VPower (`agent_not_migrated`). |
| `401` | API Key ausente o inválida. |
| `402` | Período de prueba vencido. Agrega un método de pago. |
| `422` | El recurso solicitado no existe bajo tu API Key. |
| `429` | Límite de solicitudes alcanzado. Reduce la frecuencia de tus llamadas. |
| `500` | Error interno del servidor. |

---

> 💡 Si necesitas ejecutar múltiples llamadas en paralelo, verifica los límites de concurrencia de tu plan en la sección [Suscripción](../suscripcion.md).