> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mycentralino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lista Prenotazioni

> Le prenotazioni del centralino, con filtri e paginazione

# GET /v1/calendar/bookings

Restituisce le prenotazioni, da qualunque canale siano arrivate (pannello, agente AI, pagina pubblica, API).

## Parametri Query

| Parametro    | Tipo   | Default    | Descrizione                                                 |
| ------------ | ------ | ---------- | ----------------------------------------------------------- |
| `view`       | string | `upcoming` | `upcoming` (ciò che deve ancora avvenire), `past`, `all`    |
| `status`     | string | —          | `pending`, `confirmed`, `cancelled`, `no_show`, `completed` |
| `calendar`   | string | —          | Slug del calendario                                         |
| `event`      | string | —          | Slug del tipo di appuntamento                               |
| `from`, `to` | date   | —          | Filtro sulla data di inizio (`YYYY-MM-DD`)                  |
| `q`          | string | —          | Cerca per nome, email o numero di telefono                  |
| `page`       | int    | `1`        | Pagina                                                      |
| `limit`      | int    | `50`       | Per pagina (max `200`)                                      |

## Richiesta

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.mycentralino.com/v1/calendar/bookings?view=upcoming&calendar=luigi&limit=50" \
    -H "X-API-KEY: sk_mycentralino_your_api_key"
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.mycentralino.com/v1/calendar/bookings?view=upcoming&calendar=luigi&limit=50');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'GET',
      CURLOPT_HTTPHEADER => [
          'X-API-KEY: sk_mycentralino_your_api_key'
      ]
  ]);
  $response = curl_exec($ch);
  curl_close($ch);
  print_r(json_decode($response, true));
  ```

  ```python Python theme={null}
  import requests

  headers = {'X-API-KEY': 'sk_mycentralino_your_api_key'}
  response = requests.get('https://api.mycentralino.com/v1/calendar/bookings?view=upcoming&calendar=luigi&limit=50', headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Risposta

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 91,
      "status": "confirmed",
      "calendar": {
        "id": 34,
        "slug": "luigi",
        "name": "Luigi"
      },
      "event": {
        "id": 12,
        "slug": "visita-nord",
        "name": "Visita",
        "duration_minutes": 60
      },
      "date": "2026-09-17",
      "time": "10:00",
      "end_date": "2026-09-17",
      "end_time": "11:00",
      "timezone": "Europe/Rome",
      "starts_at_utc": "2026-09-17T08:00:00Z",
      "ends_at_utc": "2026-09-17T09:00:00Z",
      "attendee": {
        "name": "Mario Rossi",
        "phone": "+393331234567",
        "email": "mario@example.com",
        "notes": null
      },
      "staff_notes": null,
      "answers": null,
      "source": "api",
      "source_ref": "api:gestionale",
      "created_by": "api:gestionale",
      "created_at": "2026-09-07T12:30:00+02:00",
      "updated_at": null,
      "cancelled_at": null,
      "cancel_reason": null,
      "cancelled_by": null
    }
  ],
  "pagination": {"current_page": 1, "per_page": 50, "total": 1, "total_pages": 1}
}
```

## Campi della prenotazione

| Campo                                           | Tipo           | Descrizione                                                                                      |
| ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| `id`                                            | int            | ID della prenotazione                                                                            |
| `status`                                        | string         | `pending` (da confermare), `confirmed`, `cancelled`, `no_show` (assente), `completed` (conclusa) |
| `calendar`                                      | object         | Il calendario: `id`, `slug`, `name`                                                              |
| `event`                                         | object         | Il tipo di appuntamento: `id`, `slug`, `name`, `duration_minutes`                                |
| `date`, `time`                                  | string         | Inizio in ora locale del centralino: `YYYY-MM-DD` e `HH:MM`                                      |
| `end_date`, `end_time`                          | string         | Fine in ora locale                                                                               |
| `timezone`                                      | string         | Il fuso del centralino, di norma `Europe/Rome`                                                   |
| `starts_at_utc`, `ends_at_utc`                  | string         | Gli stessi istanti in UTC, in più, mai al posto dei campi locali                                 |
| `attendee`                                      | object         | Chi ha prenotato: `name`, `phone`, `email`, `notes`                                              |
| `staff_notes`                                   | string \| null | Note interne dello studio: solo nel pannello e qui, mai nelle email a chi prenota                |
| `answers`                                       | object \| null | Le risposte alle domande del tipo di appuntamento (`fields`)                                     |
| `source`                                        | string         | Da dove è arrivata: `panel`, `ai` (agente telefonico), `public` (pagina di prenotazione), `api`  |
| `source_ref`, `created_by`                      | string \| null | Riferimento e autore; per l'API il nome della chiave usata                                       |
| `created_at`, `updated_at`                      | string \| null | Date in ISO 8601 con offset                                                                      |
| `cancelled_at`, `cancel_reason`, `cancelled_by` | —              | Valorizzati solo dopo un annullamento                                                            |

## Errori

### 403 - calendar\_not\_enabled

Il Calendario non è attivo su questo account.

### 404 - unknown\_event / unknown\_calendar

Lo slug del tipo di appuntamento o del calendario non esiste.

### 429 - rate\_limit\_minute / rate\_limit\_day

Limiti dell'account superati: l'header `Retry-After` dice quanto aspettare.

### 422 - invalid\_view / invalid\_status / invalid\_date

Valore non ammesso nel filtro.