API Appuntamenti (integrazione CRM)

Se gestisci un tuo CRM, ERP o schermata di prenotazione, puoi pilotare gli appuntamenti Conviro tramite una semplice API REST. Le prenotazioni via API usano lo stesso motore della prenotazione in chat: la disponibilità è ricalcolata lato server in base ai tuoi orari e al calendario collegato (Google, Outlook o feed ICS), il cliente riceve l'e-mail di conferma con file calendario e link di gestione, e il tuo team riceve le consuete notifiche.

Prerequisiti

1. Appuntamenti configurati per il tuo assistente: Dashboard -> Assistants -> [il tuo bot] -> Setup -> Scheduling.
2. Un calendario collegato: Google Calendar, Outlook / Microsoft 365, un feed ICS (Apple/iCloud, Fastmail, Nextcloud, ...) o il calendario interno integrato.
3. Una chiave API con gli scope giusti: Dashboard -> Settings -> API Keys; seleziona Appointments Read e/o Appointments Write.

Autenticazione

Invia la chiave nell'header Authorization a ogni richiesta:

Authorization: Bearer YOUR_API_KEY

URL di base: https://api.conviro.io

1. Elenca gli slot liberi

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments/slots?chatbotId=CHATBOT_ID&date=2026-07-15"

• date (opzionale) — una data locale (YYYY-MM-DD) nel fuso dell'assistente; se omessa, il prossimo giorno disponibile.
• serviceId (opzionale) — uno dei servizi restituiti nella risposta.

La risposta contiene timeZone, i tuoi services e slots come coppie { start, end } in formato ISO UTC.

2. Prenota un appuntamento

Richiede lo scope appointments:write. Le prenotazioni via API sono fidate — non viene inviato alcun OTP via e-mail, perché l'identità del cliente è già nel tuo sistema.

curl -X POST "https://api.conviro.io/v1/api/appointments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "startIso": "2026-07-15T09:00:00.000Z",
    "contactEmail": "[email protected]",
    "contactName": "Jane Doe",
    "contactPhone": "+31 6 00000000"
  }'

Usa uno startIso preso dall'endpoint degli slot. Il server riconvalida lo slot prima di prenotare — se nel frattempo è stato occupato ricevi un 400 ("non più disponibile"): ricarica gli slot e riprova.

3. Elenca gli appuntamenti

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.conviro.io/v1/api/appointments?status=confirmed&limit=50"

Filtri: status (es. confirmed, cancelled), limit (max 200), offset. Richiede appointments:read.

4. Annulla un appuntamento

curl -X DELETE "https://api.conviro.io/v1/api/appointments/APPOINTMENT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Richiede appointments:write. L'annullamento rimuove anche l'evento dal calendario collegato e avvisa il tuo team.

Webhook — mantieni il CRM sincronizzato

Iscriviti in Dashboard -> Developers -> Webhooks a:

• appointment.booked — scatta per ogni prenotazione confermata (chat, widget di prenotazione o API)
• appointment.cancelled — scatta a ogni annullamento

Il payload include appointmentId, chatbotId, startIso, endIso, timeZone, service, contactName, contactEmail, contactPhone e channel — tutto il necessario per replicare la prenotazione nel tuo CRM.

Opzioni calendario a colpo d'occhio

> Suggerimento: Le chiavi API hanno un limite di richieste per chiave. Per grandi volumi preferisci i webhook al polling dell'endpoint di elenco.