Zimun: Appointment Scheduling & Booking Service: Guida API prenotazioni

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.

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 correnti sono focalizzate sulle operazioni di prenotazione. Le API di gestione sono previste in una fase successiva.