Skip to main content

​
Il Calendario via API

Il Calendario MyCentralino è il sistema di prese appuntamenti integrato nel centralino: lo usano il pannello, l’agente telefonico AI, la pagina pubblica di prenotazione e, con queste API, il tuo gestionale. Tutti i canali passano dallo stesso motore di disponibilità: uno slot preso al telefono non è prenotabile via API, e viceversa.
Il Calendario è incluso per gli account con Agenti AI, MySegretaria o WhatsApp API. Senza uno di questi, gli endpoint rispondono 403 con calendar_not_enabled.

​
Base URL e autenticazione

Come tutta l’API: https://api.mycentralino.com, header X-API-KEY, rate limiting per account. Le risposte sono {"success": true, "data": …} oppure {"success": false, "error": {"code": "…", "message": "…"}}.

​
Convenzioni

  • Date e ore in ora locale del centralino, con campi separati: date = YYYY-MM-DD, time = HH:MM (24 ore). Niente ISO con offset. Il fuso è dichiarato in ogni risposta (timezone, di norma Europe/Rome); gli istanti UTC (starts_at_utc, ends_at_utc) ci sono in più, mai al posto.
  • Calendari e tipi di appuntamento si indicano con lo slug (calendar, event): quello che si legge in GET /v1/calendar/calendars e GET /v1/calendar/events.
  • Errori con code stabile e un messaggio in italiano piano. Lo status HTTP dice la famiglia: 400 richiesta malformata, 404 non trovato, 409 conflitto (slot occupato, stato non modificabile), 422 dati non validi, 429 troppe richieste, 5xx guasto nostro.
  • Idempotency-Key (header, facoltativo, max 200 caratteri) su POST /v1/calendar/bookings: ripetere la stessa chiamata con la stessa chiave restituisce la stessa prenotazione invece di crearne una seconda. Consigliato a chi fa retry.
  • Le prenotazioni fatte via API nascono con source: "api"; created_by porta il nome della chiave API usata.

​
Endpoint

​
Il flusso tipico

  1. Leggi i tipi di appuntamento con GET /v1/calendar/events e scegli lo slug.
  2. Chiedi gli orari liberi con GET /v1/calendar/availability?event=….
  3. Prenota uno di quegli orari con POST /v1/calendar/bookings, con una Idempotency-Key.
  4. Ricevi gli aggiornamenti con i webhook uscenti, oppure rileggi con GET /v1/calendar/bookings.

​
Codici di errore