Per sviluppatori

API, webhook e widget, gratis

Consulta gli orari liberi, crea e annulla prenotazioni dal tuo software, ricevi un avviso firmato a ogni modifica e metti la tua agenda sul tuo sito. Quello che altri fanno pagare, qui è gratis.

Inizia gratis · Vai a API e webhook

Autenticazione

Crea una chiave in Impostazioni → API e webhook. Scegli «Solo lettura» (tipi di riunione, disponibilità e prenotazioni) o «Lettura e prenotazione» (in più prenotare, spostare, annullare e creare link monouso). La chiave viene mostrata una sola volta.

Inviala nell’intestazione X-API-Key. Tutti gli endpoint partono da https://calendavibe.com/api/v1. Una chiave vede e modifica solo i dati del proprio account.

I tuoi tipi di riunione

curl https://calendavibe.com/api/v1/event-types \
  -H "X-API-Key: cvwh_…"

Endpoint

EndpointCosa faChiave
GET /meIl tuo account e il tipo di chiaveSolo lettura
GET /event-typesI tuoi tipi di riunione, con il loro link pubblicoSolo lettura
GET /event-types/{id}/slots?from&to&timezoneGli orari liberi, come li offre la tua paginaSolo lettura
GET /bookings?status=upcoming|past|cancelled|allLe tue prenotazioni (paginate con cursore)Solo lettura
GET /bookings/{id}Una prenotazioneSolo lettura
POST /bookingsPrenotare un orarioLettura e prenotazione
POST /bookings/{id}/rescheduleCambiare l’orarioLettura e prenotazione
POST /bookings/{id}/cancelAnnullareLettura e prenotazione
POST /single-use-linksUn link che accetta una sola prenotazioneLettura e prenotazione

Prenotare (con Idempotency-Key, per non duplicare se ripeti la richiesta)

curl -X POST https://calendavibe.com/api/v1/bookings \
  -H "X-API-Key: cvwh_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "eventTypeId": "ckx…",
    "startTime": "2026-11-03T09:00:00.000Z",
    "guest": { "name": "Ana García", "email": "ana@example.com", "timezone": "Europe/Madrid", "locale": "es" },
    "consent": true
  }'

Regole delle prenotazioni

Una prenotazione via API segue le stesse regole della tua pagina: solo orari davvero liberi (anche nel tuo calendario), l’invitato riceve le sue email e compare tra i tuoi contatti.

Invia consent: true quando l’invitato ha accettato il trattamento dei suoi dati nel tuo modulo.

Se due sistemi chiedono lo stesso orario nello stesso momento, il secondo riceve 409 SLOT_UNAVAILABLE e ne sceglie un altro. Con la stessa Idempotency-Key, una richiesta ripetuta restituisce la stessa prenotazione per 24 ore.

Una riunione a pagamento non si prenota via API: la risposta è 402 PAYMENT_REQUIRED con bookingUrl, il link con cui l’invitato prenota e paga.

Limiti

Piano gratuito: 60 chiamate al minuto e 10.000 al giorno per account, e fino a 10 webhook. Con Closevibe, di più.

Superato il limite, la risposta è 429 con l’intestazione Retry-After.

Gli errori hanno sempre la forma { "error": { "code", "message" } }.

Webhook

In Impostazioni → API e webhook aggiungi un URL di destinazione (https e pubblico) e scegli gli avvisi: Nuova prenotazione (meeting.booked), Cancellazione (meeting.cancelled), Cambio di orario (meeting.rescheduled) e Pagamento ricevuto (meeting.paid).

Ogni avviso è un POST con i dati della prenotazione, mai il link privato dell’invitato. Se il tuo server non risponde, riproviamo dopo 1 min, 5 min, 30 min, 2 h, 6 h e 12 h. Dopo 20 errori di fila l’URL viene disattivato e ti avvisiamo via email.

Verifica la firma: l’intestazione X-Webhook-Signature è sha256= seguito dall’HMAC-SHA256 del corpo così come arriva, con il segreto di firma di quell’URL.

Un avviso

{
  "id": "evt_…",
  "event": "meeting.booked",
  "createdAt": "2026-11-01T10:15:00.000Z",
  "data": {
    "booking": {
      "id": "ckx…", "status": "CONFIRMED",
      "eventType": { "id": "ckx…", "slug": "primera-consulta", "name": "Primera consulta", "duration": 30 },
      "startTime": "2026-11-03T09:00:00.000Z", "endTime": "2026-11-03T09:30:00.000Z", "timezone": "Europe/Madrid",
      "guest": { "name": "Ana García", "email": "ana@example.com", "phone": null, "timezone": "Europe/Madrid", "locale": "es", "notes": null },
      "answers": [{ "question": "Motivo", "answer": "Revisión" }],
      "meetingUrl": "https://meet.google.com/…", "payment": null
    }
  }
}

Verificare la firma (Node.js)

const crypto = require('crypto');

// rawBody: the request body exactly as received (a Buffer or string, before JSON.parse).
function isFromCalendaVibe(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header && expected.length === header.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Widget per il tuo sito

Nella pagina o in una finestra pop-up (pulsante o bolla), con il tuo colore e la tua lingua. Se conosci già il visitatore, passa il suo nome e la sua email e li troverà già compilati. Sul cellulare la finestra occupa tutto lo schermo e si chiude con la X o con Esc.

Quando qualcuno prenota dentro il widget, la tua pagina riceve l’evento calendavibe:booked con l’orario e il tipo di riunione.

Nella pagina

<div class="calendavibe-inline" data-url="https://calendavibe.com/ana/primera-consulta"
     data-color="#6d28d9" data-lang="es"></div>
<script src="https://calendavibe.com/embed.js" async></script>

Finestra pop-up da un pulsante o da una bolla

<a href="https://calendavibe.com/ana/primera-consulta" data-calendavibe-popup
   data-color="#6d28d9" data-name="Ana García" data-email="ana@example.com">Reservar</a>

<script src="https://calendavibe.com/embed.js" async
        data-calendavibe-bubble="https://calendavibe.com/ana" data-text="Reservar" data-color="#6d28d9"></script>

Domande frequenti

Costa qualcosa?

No. L’API, i webhook e il widget sono gratis nel piano gratuito, con i limiti indicati sopra.

Funziona con Zapier o Make?

Sì: usa il loro modulo HTTP con la tua chiave per l’API, e un webhook di CalendaVibe come trigger.

Posso far pagare una riunione via API?

No: l’invitato paga sulla tua pagina. L’API ti restituisce il link da inviargli.