Per a desenvolupadors

API, webhooks i widget, gratis

Consulta hores lliures, crea i cancel·la reserves des del teu programari, rep un avís signat de cada canvi i posa la teva agenda al teu web. El que altres cobren, aquí és gratis.

Comença gratis · Ves a API i webhooks

Autenticació

Crea una clau a Configuració → API i webhooks. Tria «Només llegir» (tipus de reunió, disponibilitat i reserves) o «Llegir i reservar» (a més, reservar, canviar, cancel·lar i crear enllaços d’un sol ús). La clau només es mostra una vegada.

Envia-la a la capçalera X-API-Key. Totes les rutes pengen de https://calendavibe.com/api/v1. Una clau només veu i toca les dades del seu propi compte.

Els teus tipus de reunió

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

Rutes

Ruta	Què fa	Clau
GET /me	El teu compte i el tipus de clau	Només llegir
GET /event-types	Els teus tipus de reunió, amb el seu enllaç públic	Només llegir
GET /event-types/{id}/slots?from&to&timezone	Les hores lliures, tal com les ofereix la teva pàgina	Només llegir
GET /bookings?status=upcoming\|past\|cancelled\|all	Les teves reserves (paginades amb cursor)	Només llegir
GET /bookings/{id}	Una reserva	Només llegir
POST /bookings	Reservar una hora	Llegir i reservar
POST /bookings/{id}/reschedule	Canviar l’hora	Llegir i reservar
POST /bookings/{id}/cancel	Cancel·lar	Llegir i reservar
POST /single-use-links	Un enllaç que només admet una reserva	Llegir i reservar

Reservar (amb Idempotency-Key, per no duplicar res si repeteixes la petició)

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
  }'

Regles de les reserves

Una reserva per API segueix les mateixes regles que la teva pàgina: només hores lliures de veritat (també al teu calendari), el convidat rep els seus correus i apareix als teus contactes.

Envia consent: true quan el convidat hagi acceptat el tractament de les seves dades al teu formulari.

Si dos sistemes demanen la mateixa hora alhora, el segon rep 409 SLOT_UNAVAILABLE i en tria una altra. Amb la mateixa Idempotency-Key, una petició repetida retorna la mateixa reserva durant 24 hores.

Una reunió de pagament no es reserva per API: la resposta és 402 PAYMENT_REQUIRED amb bookingUrl, l’enllaç perquè el convidat reservi i pagui.

Límits

Pla gratis: 60 crides per minut i 10.000 al dia per compte, i fins a 10 webhooks. Amb Closevibe, més.

Quan se supera el límit, la resposta és 429 amb la capçalera Retry-After.

Els errors sempre tenen la forma { "error": { "code", "message" } }.

Webhooks

A Configuració → API i webhooks afegeix un URL de destinació (https i públic) i tria els avisos: Reserva nova (meeting.booked), Cancel·lació (meeting.cancelled), Canvi d’hora (meeting.rescheduled) i Pagament rebut (meeting.paid).

Cada avís és un POST amb les dades de la reserva, mai l’enllaç privat del convidat. Si el teu servidor falla, ho tornem a provar al cap d’1 min, 5 min, 30 min, 2 h, 6 h i 12 h. Després de 20 errors seguits, l’URL es desactiva i t’avisem per correu.

Comprova la signatura: la capçalera X-Webhook-Signature és sha256= i l’HMAC-SHA256 del cos tal com arriba, amb el secret de signatura d’aquest URL.

Un avís

{
  "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
    }
  }
}

Verificar la signatura (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));
}

A la pàgina

<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 emergent des d’un botó o una bombolla

<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>

Preguntes freqüents

Costa alguna cosa?

No. L’API, els webhooks i el widget són gratis al pla gratis, amb els límits que hi ha més amunt.

Funciona amb Zapier o Make?

Sí: fes servir el seu mòdul HTTP amb la teva clau per a l’API, i un webhook de CalendaVibe com a disparador.

Puc cobrar una reunió per API?

No: el convidat paga a la teva pàgina. L’API et retorna l’enllaç perquè l’hi puguis enviar.