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 elencare servizi, leggere 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/services - Elenca i servizi della tua organizzazione.
• GET /api/v1/availability - Leggi gli slot disponibili per servizio e data.
• POST /api/v1/appointments/hold - Crea un hold temporaneo prima della conferma.
• POST /api/v1/appointments/confirm - Conferma un hold e crea l'appuntamento.
• POST /api/v1/appointments/reschedule - Riprogrammare un appuntamento esistente per appuntamento_id.
• POST /api/v1/appointments/cancel - Annulla un appuntamento esistente tramite appuntamento_id.

Sequenza consigliata

1. Elenca i servizi e lascia scegliere all'utente.
2. Recupera la disponibilità per il servizio scelto.
3. Crea hold per lo slot selezionato.
4. Conferma la prenotazione con i dati di contatto.
5. Se necessario, riprogramma o annulla in un secondo momento utilizzando appuntamento_id dal tuo stato di integrazione.

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.