Guida all’API di prenotazione

La Booking API è ora disponibile per i flussi pubblici di pianificazione.

Cosa copre questa guida

• Come autenticarsi e chiamare in sicurezza gli endpoint di prenotazione.
• Come scoprire le sedi, elencare i servizi, leggere la disponibilità e completare il flusso di prenotazione.
• Quando usare Booking API direttamente vs integrazione MCP.

API di prenotazione e MCP

• Usa Booking API quando costruisci una tua integrazione backend/client e vuoi controllo HTTP diretto.
• Usa MCP quando il tuo client è nativo MCP e deve chiamare strumenti come list_services e get_availability.
• Entrambi i percorsi sono progettati sulla stessa logica di prenotazione e controlli conflitti.

Se desideri un flusso di conversazione pronto da incorporare per la prenotazione dei clienti, rivedilo Agente di chat di prenotazione.

Autenticazione

1. Crea credenziali API in Impostazioni → Client API.
2. Richiedi un token da /oauth/token usando credenziali client.
3. Chiama Booking API con Authorization: Bearer <token>.

Scope usati dai flussi di prenotazione: org:read, availability:read, appointments:write.

Mappa endpoint

• GET /api/v1/locations - Elenca le sedi di prenotazione attive della tua organizzazione.
• GET /api/v1/services - Elenca i servizi della tua organizzazione, inclusi i location_ids.
• GET /api/v1/availability - Leggi gli slot disponibili per servizio e data, con location_id quando richiesto.
• POST /api/v1/appointments/hold - Crea un hold temporaneo prima della conferma, usando la stessa location_id quando richiesto.
• POST /api/v1/appointments/confirm - Conferma un hold e crea l’appuntamento.
• POST /api/v1/appointments/reschedule - Riprogramma un appuntamento esistente tramite booking_id.
• POST /api/v1/appointments/cancel - Annulla un appuntamento esistente tramite booking_id.

Riserve di appuntamento (servizi a prezzo fisso). Se tramite questa interfaccia viene creato un hold o una prenotazione per un servizio o una risorsa con prezzo fisso, si tratta di una riserva di appuntamento ai sensi delle Condizioni generali (Parte C, punto 13, comma 2), non di un contratto relativo alla prestazione. In tal caso la risposta dell’hold e la risposta della prenotazione contengono kind: "reservation", contract: "on_site", il prezzo in price_cents con price_label che riporta esattamente «Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt» (prezzo dell’organizzazione, pagabile in sede; prezzo e contratto vengono definiti in sede), nonché notice con questo testo fisso: «Terminreservierung: Mit dieser Reservierung ist noch kein Vertrag über die Leistung geschlossen. Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt.» (in italiano: «Riserva di appuntamento: con questa riserva non è ancora stato concluso alcun contratto relativo alla prestazione. Prezzo dell’organizzazione, pagabile in sede; prezzo e contratto vengono definiti in sede.») La tua interfaccia utente deve mostrare questo avviso al cliente finale, al più tardi insieme all’esito della prenotazione; è un tuo obbligo ai sensi delle Condizioni generali, Parte B, punto 8, comma 5, lettera c). La risposta dell’hold lo contiene affinché possa essere mostrato prima che il cliente finale invii la prenotazione; una traduzione in un’altra lingua deve essere completa e fedele. Tramite questa interfaccia Zimun non raccoglie né documenta alcun consenso del cliente finale alle proprie disposizioni, non accetta né pagamenti online né carte di pagamento e invia all’indirizzo e-mail trasmesso con la prenotazione una comunicazione di riserva, non una conferma di prenotazione.

Sequenza consigliata

1. Elenca le sedi se l’organizzazione può prenotare in più di un luogo.
2. Consenti all’utente di scegliere una sede quando necessario.
3. Elenca i servizi e conserva solo quelli che coprono quella sede.
4. Recupera la disponibilità con service_id, date e location_id quando serve.
5. Crea l’hold con la stessa location_id.
6. Conferma la prenotazione con i dati di contatto.
7. Conserva la booking_id così potrai riprogrammare o annullare in seguito.

Note di affidabilità

• Usa idempotenza per chiamate create/confirm per evitare duplicati nei retry.
• Tratta gli hold come temporanei e conferma rapidamente.
• Gestisci esplicitamente risposte 401/403/404 e conflitti nella UX client.

Nota sul perimetro

Le API pubbliche attuali sono focalizzate sulle operazioni di prenotazione. Le API di gestione sono previste in una fase successiva.