# API de Llamadas

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 |

---

## Códigos de error comunes

| Código | Descripción |
|--------|-------------|
| `400` | Formato de solicitud inválido. Verifica los parámetros enviados. |
| `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).