# Reservas

> Listar las reuniones que tu agente reservó en la conversación, con su estado, el asistente y los enlaces de calendario, y sincronizarlas con tu CRM.

Source: https://docs.whatsetter.com/es/developers/guides/bookings/

Una reserva es una reunión que tu agente IA reservó dentro de la conversación, en tu calendario conectado. La API las lista en solo lectura, la franja más reciente primero.

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/bookings`](/api-reference/operations/listbookings/) | `bookings:read` |

## Listar reservas

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/bookings?since=2026-09-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/bookings?since=2026-09-01T00:00:00Z&limit=25',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: bookings, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/bookings",
    params={"since": "2026-09-01T00:00:00Z", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
bookings = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0f5",
      "status": "booked",
      "lead_id": "34612345678@c.us",
      "campaign_id": "acme-espana-1-ab12",
      "provider": "calendly",
      "source": "chat",
      "start_at": "2026-09-23T13:00:00.000Z",
      "end_at": "2026-09-23T13:30:00.000Z",
      "timezone": "Europe/Madrid",
      "attendee": {
        "name": "Julien",
        "email": "julien@example.com",
        "phone": "+34612345678"
      },
      "cancel_url": "https://calendly.com/cancellations/…",
      "reschedule_url": "https://calendly.com/reschedulings/…",
      "canceled_at": null,
      "cancellation_reason": null,
      "created_at": "2026-09-18T16:45:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0f5" }
}
```

| Parámetro | Qué hace |
|---|---|
| `status` | Coincidencia exacta con un estado de abajo. |
| `campaign_id` | El slug de la campaña o su `id`. |
| `since` | Solo las reservas que empiezan a partir de esta fecha ISO 8601. |
| `limit`, `cursor` | Paginación, de 1 a 100 por página. |

## Campos y estados

| Campo | Significado |
|---|---|
| `status` | `booked`, `canceled`, `rescheduled`, `failed` o `no_show`. |
| `lead_id` | El id de WhatsApp del lead (`34612345678@c.us`), el mismo valor que `whatsapp_id` en un lead. Para abrir el lead, llama a `GET /leads?phone=+34612345678`. |
| `campaign_id` | El slug de la campaña. |
| `provider` | El proveedor de calendario donde vive la reunión. |
| `source` | Cómo se reservó: `chat` (por el agente en la conversación), `static_link` (el lead usó el enlace de reserva), `webhook` (comunicada por el proveedor), `manual`. |
| `start_at`, `end_at` | En UTC. Muéstralos en `timezone`. |
| `attendee` | Nombre, email y teléfono que dio el lead al reservar. |
| `canceled_at`, `cancellation_reason` | Rellenos cuando la reunión se canceló. |

La lista se ordena por `start_at`, la franja más reciente primero: las reuniones futuras van antes que las pasadas.

## Los enlaces son secretos

`cancel_url` y `reschedule_url` son enlaces de capacidad generados por el proveedor de calendario: quien tenga uno puede cancelar o mover la reunión, sin iniciar sesión. Trátalos como contraseñas: guárdalos cifrados, no los registres nunca en logs, no se los muestres nunca a alguien que no pueda actuar sobre la reunión. Son `null` cuando el proveedor no dio ninguno.

## Errores que encontrarás

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clave ausente, desconocida o revocada. |
| 403 | `insufficient_scope` | La clave no tiene `bookings:read`. |
| 422 | `validation_error` | `since` no es una fecha ISO 8601, `limit` fuera de 1 a 100, cursor inválido o caducado. |
| 429 | `rate_limited` | Demasiadas peticiones este minuto. Respeta `Retry-After`. |

## Relacionado

- [Leads](/es/developers/guides/leads/)
- [Citas en el dashboard](/es/dashboard/bookings/)
- [Webhooks firmados](/es/developers/webhooks/)
