Manual de referencia: Cal.com

Datos de esta lección
Fase	MAN — Manuales de referencia
Módulo	MAN — Biblioteca de consulta

Objetivo práctico

Este manual reúne, en un único documento de consulta, todo lo que necesitas saber sobre Cal.com más allá de la lección práctica del módulo 3.2: los planes (incluida la opción open-source autoalojada), el vocabulario completo de disponibilidad y reservas, la API y los Webhooks, la seguridad de las claves de API, y el catálogo de errores más frecuentes con su diagnóstico.

Resultado que obtendrás

No hay un resultado práctico único que producir: este manual se consulta, no se «completa». El resultado esperado es que sepas, en cualquier momento del curso, dónde buscar la respuesta correcta sobre planes, API, seguridad o errores de Cal.com sin depender de la memoria ni de fuentes de terceros no verificadas.

Dónde encaja dentro del sistema final

Cal.com ocupa la pieza CALENDARIO del sistema TELÉFONO → AGENTE → CEREBRO → VOZ → AUTOMATIZACIÓN → CALENDARIO: es el destino final de la reserva que gestiona la AUTOMATIZACIÓN (n8n o Make) cuando el AGENTE, guiado por el CEREBRO, confirma una cita durante la llamada. A diferencia de Google Calendar, Cal.com aporta de fábrica reglas de disponibilidad, tipos de evento y una API pensada específicamente para consultar huecos libres en tiempo real, lo que puede simplificar la integración con el Tool Calling del módulo 3.4.

Conocimientos previos

Cal.com para gestionar disponibilidad y reservas (módulo 3.2, lección práctica de este mismo curso).

Herramientas necesarias

Una cuenta de Cal.com ya creada.
Un navegador con NVDA activo.

Posible coste

Verificado contra la página oficial de precios de Cal.com (cal.com/pricing) el 30 de agosto de 2026.

Free: gratuito, para 1 usuario, con tipos de evento y calendarios ilimitados, notificaciones por correo y SMS, integración con más de 100 aplicaciones, app móvil, extensión de navegador, aceptación de pagos con Stripe y PayPal, sincronización bidireccional con Salesforce y HubSpot, e importación de eventos de Calendly con un clic.

Teams: 12 $/usuario/mes (facturación anual, con un 25% de descuento indicado en la página oficial), añade disponibilidad compartida de equipo, reservas por turno rotatorio (round-robin), tipos de evento gestionados y colectivos, eventos recurrentes, notificaciones personalizables, eliminación de la marca Cal.com, formularios de enrutamiento, analítica de reservas y Custom APIs.

Organizations: 28 $/usuario/mes (facturación anual), añade sub-equipos ilimitados, enrutamiento por variables personalizadas, subdominio propio de empresa, SSO SAML, aprovisionamiento SCIM, cumplimiento SOC 2/HIPAA/ISO 27001 y permisos basados en roles.

Enterprise: precio a medida, con soporte dedicado, SLA garantizado e integraciones HRIS.

Precisión importante sobre Webhooks y API en el plan Free: la página oficial de precios indica que todos los planes admiten Webhooks para transmitir datos de reserva de forma automatizada, pero la lista detallada de funciones del plan Free no menciona explícitamente el acceso a Webhooks ni a API, mientras que «Custom APIs» aparece de forma explícita como función añadida del plan Teams. Este manual no puede confirmar con total fiabilidad si un usuario individual del plan Free tiene acceso pleno a la creación de Webhooks desde /settings/developer/webhooks: antes de diseñar una integración que dependa de ello, verifica dentro de tu propia cuenta si esa sección aparece disponible, o revisa el plan Teams si tu proyecto los necesita garantizados.

Open source y autoalojamiento: Cal.com es de código abierto y puede autoalojarse sin coste de licencia. En 2026, Cal.com trasladó el producto principal a código cerrado y relanzó su edición comunitaria autoalojable, gratuita, bajo el nombre Cal.diy, separada del producto alojado por Cal.com. Autoalojar elimina la cuota de suscripción, pero implica costes indirectos (servidor, copias de seguridad, parches de seguridad, tiempo de mantenimiento) que, para la mayoría de negocios pequeños, superan en esfuerzo al plan alojado gratuito.

Para las prácticas de este curso, el plan Free alojado por Cal.com es suficiente.

Advertencia de seguridad

Cal.com documenta oficialmente tres métodos de autenticación para su API v2: OAuth, API Key, y un método «Platform» marcado como obsoleto. Cal.com recomienda expresamente usar credenciales OAuth en lugar de una API Key siempre que estés construyendo una integración o aplicación, reservando la API Key para usos más puntuales. Las API Keys se gestionan desde Configuración (Settings) → Seguridad (Security) → API Keys; las claves de modo de prueba llevan el prefijo cal_ y las de modo real cal_live_. Cal.com advierte explícitamente que una API Key concede muchos privilegios y que nunca debe compartirse en zonas públicamente accesibles, como un repositorio de GitHub o código ejecutado en el navegador (cliente). La autenticación a la API se realiza mediante la cabecera HTTP «Authorization»; trata cualquier valor de esa cabecera con el mismo cuidado que una contraseña. Los Webhooks de Cal.com incluyen una firma en la cabecera X-Cal-Signature-256 que permite verificar que la notificación procede realmente de Cal.com y no ha sido falsificada: valida siempre esa firma en el sistema receptor (n8n o Make) antes de procesar el contenido de un Webhook.

Modelo mental

Piensa en la centralita de reservas de un negocio con varios profesionales: en lugar de que cada cliente llame para preguntar «¿tienes hueco el jueves?», existe una página pública donde se ve directamente qué horas están libres, y al reservar, ese hueco se bloquea automáticamente para que nadie más pueda ocuparlo. Cal.com es, además, la centralita que puede «avisar por megafonía» a otros sistemas (mediante Webhooks) en el instante exacto en que se confirma o cancela una reserva.

Explicación

Este apartado reúne el vocabulario y los conceptos de Cal.com que no se cubren en detalle en la lección práctica del módulo 3.2.

La API v2 de Cal.com (documentada oficialmente en cal.com/docs/api-reference/v2/introduction) es la vía recomendada para que un sistema externo —como el workflow de n8n o el escenario de Make del módulo 3.3, o directamente el Tool Calling del agente en el módulo 3.4— consulte huecos disponibles, cree una reserva o la cancele, sin necesidad de abrir el panel web de Cal.com. Su autenticación admite OAuth (recomendado por Cal.com para integraciones) o una API Key simple (más rápida de configurar, adecuada para pruebas o proyectos personales).

Los Webhooks de Cal.com pueden crearse con distintos alcances (scope): a nivel de usuario, para recibir notificaciones de todos los tipos de evento de esa cuenta, o a nivel de un tipo de evento concreto, si sólo te interesa un servicio específico del negocio. Cada Webhook puede personalizar la plantilla del contenido que envía, usando variables como {{type}} (tipo de evento del disparo), {{title}} (título de la reserva) o {{organizer.name}} (nombre de quien organiza), lo que permite adaptar el payload al formato que espera n8n o Make sin necesidad de un paso de transformación adicional.

Los disparadores típicos de un Webhook de Cal.com incluyen la creación de una reserva, su cancelación y su reprogramación; para el caso de uso de este curso (el agente confirma una cita durante la llamada), el disparador relevante es la creación de la reserva, que puede usarse para, por ejemplo, enviar una confirmación por SMS o registrar la cita en un sistema interno adicional.

Vocabulario nuevo

API v2 de Cal.com

Piénsalo así: La línea directa con la centralita de reservas, para consultar o modificar huecos sin tener que abrir la página web.

Interfaz de programación oficial de Cal.com que permite gestionar reservas, disponibilidad y tipos de evento mediante peticiones HTTP autenticadas.

Ejemplo: El nodo de Tool Calling del agente puede llamar a la API v2 de Cal.com para comprobar si un hueco sigue libre justo antes de confirmarlo en voz alta.

Webhook de Cal.com

Piénsalo así: El aviso automático por megafonía que suena en el instante exacto en que se confirma una reserva en la centralita.

Notificación HTTP que Cal.com envía a una URL configurada cuando ocurre un evento (reserva creada, cancelada, reprogramada), con una firma de verificación en la cabecera X-Cal-Signature-256.

Ejemplo: Un Webhook de creación de reserva puede disparar el workflow de n8n que envía un SMS de confirmación al cliente.

API Key de Cal.com

Piénsalo así: Una llave de acceso rápido para pruebas, frente al pase de empleado (OAuth) recomendado para un sistema de producción.

Cadena de autenticación simple, con prefijo cal_ (pruebas) o cal_live_ (producción), gestionada desde Settings → Security.

Ejemplo: Para probar rápidamente la API v2 desde n8n, una API Key es más sencilla de configurar que un flujo OAuth completo.

Alcance del Webhook (scope)

Piénsalo así: Decidir si el aviso de megafonía suena para toda la centralita o sólo para el mostrador de un servicio concreto.

Nivel al que se suscribe un Webhook: a todos los tipos de evento de un usuario, o a un tipo de evento concreto.

Ejemplo: Puedes crear un Webhook con alcance limitado únicamente al tipo de evento «Urgencia de fontanería», sin recibir notificaciones de otros servicios del negocio.

Preparación

Este manual no requiere preparación técnica adicional: puedes consultarlo con tu cuenta de Cal.com abierta o cerrada. Si vas a poner en práctica algo de lo que leas aquí, ten tu cuenta de Cal.com iniciada y NVDA activo.

Procedimiento paso a paso

Contexto: Vas a comprobar si tu cuenta tiene acceso a la sección de Webhooks, dado que la página oficial de precios no confirma con total claridad su disponibilidad en el plan Free.
Acción de teclado: Ve a la URL /settings/developer/webhooks dentro de tu cuenta de Cal.com, o recorre el menú de ajustes con Tab hasta «Developer» y después «Webhooks».
Respuesta esperada de NVDA: NVDA debería anunciar un texto similar a «Webhooks, encabezado» y, si tu plan lo permite, un botón «New Webhook» o «Add».
Qué significa: Si la sección se muestra con un formulario funcional para crear Webhooks, tu cuenta tiene acceso; si en su lugar aparece un aviso de función bloqueada o de actualización de plan, tu plan actual no la incluye.
Acción siguiente: Documenta lo que observes en tu propia cuenta, ya que este manual no puede confirmar el comportamiento exacto por adelantado para todos los casos.
Contexto: Vas a generar una API Key de prueba para consultar la disponibilidad de un tipo de evento desde fuera de Cal.com.
Acción de teclado: Ve a Settings → Security → API Keys, y activa «New API Key» recorriendo con Tab hasta el botón correspondiente.
Respuesta esperada de NVDA: NVDA debería anunciar un formulario con un campo de nombre para la clave y, al confirmarla, un texto de un solo uso con el valor completo de la clave (con el prefijo cal_ o cal_live_).
Qué significa: Ese valor sólo se muestra una vez: cópialo inmediatamente a un gestor de contraseñas o variable de entorno segura, siguiendo el protocolo de seguridad del módulo 2.1 del curso.
Acción siguiente: Usa esa clave en la cabecera «Authorization» de tus peticiones de prueba a la API v2, nunca en código visible del lado del cliente.
Contexto: Vas a crear un Webhook de prueba para el disparador «Booking Created», con verificación de firma.
Acción de teclado: Dentro de «New Webhook», rellena con Tab el campo «Subscriber URL» (la URL de tu workflow de n8n o escenario de Make) y marca la casilla del disparador «Booking Created».
Respuesta esperada de NVDA: NVDA debería anunciar cada campo del formulario: URL, secreto de firma opcional, y la lista de disparadores disponibles como casillas de verificación.
Qué significa: El campo de secreto, si lo rellenas, es el valor que Cal.com usará para firmar cada payload en la cabecera X-Cal-Signature-256.
Acción siguiente: Guarda el Webhook y realiza una reserva de prueba para confirmar que tu sistema receptor recibe la notificación y valida correctamente la firma.

Posibles diferencias de interfaz

Cal.com distingue entre su documentación de API v1 (heredada) y API v2 (actual); si encuentras artículos o ejemplos de terceros que mencionan endpoints distintos a los de cal.com/docs/api-reference/v2, es probable que describan la versión anterior. Usa siempre la documentación de la v2 como referencia principal para proyectos nuevos.

Problema de accesibilidad y alternativa

No se ha encontrado, en la documentación oficial consultada el 30 de agosto de 2026, una declaración de accesibilidad específica ni una auditoría WCAG publicada oficialmente por Cal.com para su panel de administración o su página pública de reserva. A diferencia de n8n y Make, la interfaz de Cal.com no se basa en un lienzo de arrastrar y soltar: tanto el panel de configuración de tipos de evento como la página pública de reserva (el booking link) están construidos, según lo observado en la lección práctica del módulo 3.2, con formularios, encabezados y calendarios de selección de fecha navegables mediante Tab y flechas, un patrón estructuralmente más compatible con NVDA que un lienzo de posiciones libres. Aun así, este manual no afirma una conformidad WCAG que no ha podido verificar contra una fuente oficial: si detectas un control concreto que NVDA no anuncia correctamente, tradúcelo primero a la vía de la API (crear o consultar reservas mediante peticiones HTTP con tu API Key) como alternativa, ya que evita por completo la interfaz visual.

Errores frecuentes y diagnóstico

Un Webhook configurado no llega nunca al sistema receptor (n8n o Make).

Cómo localizarlo: Puede deberse a que el disparador seleccionado no coincide con el evento real (por ejemplo, tener marcado sólo «Booking Cancelled» cuando lo que ocurre es una creación), a que la URL de destino tiene un error tipográfico, o a que tu plan no incluye Webhooks para esa cuenta.

Solución: Revisa los disparadores marcados en la configuración del Webhook, confirma la URL exacta contra la URL real del Webhook de n8n o Make, y comprueba si la sección de Webhooks aparece disponible sin restricciones en tu cuenta.

La verificación de la firma X-Cal-Signature-256 falla en el sistema receptor.

Cómo localizarlo: El secreto configurado en Cal.com no coincide exactamente con el secreto usado para verificar la firma en n8n o Make, o el payload se ha modificado (por ejemplo, reformateado) antes de calcular la firma.

Solución: Copia de nuevo el secreto directamente desde la configuración del Webhook en Cal.com, sin espacios adicionales, y verifica la firma sobre el cuerpo bruto (raw body) de la petición, no sobre una versión ya interpretada.

Una petición a la API v2 con una API Key devuelve un error de autenticación.

Cómo localizarlo: La clave puede haberse copiado incompleta, haber sido revocada desde Settings → Security, o estar usando el prefijo de modo de prueba (cal_) contra un entorno que espera el de producción (cal_live_), o viceversa.

Solución: Genera una nueva API Key si es necesario, confirma que usas el prefijo correcto para tu entorno, y revisa que la cabecera «Authorization» tiene el formato exacto documentado en cal.com/docs/api-reference/v2.

Comprobación final

Sabes que puedes usar este manual con eficacia si eres capaz de: explicar la diferencia entre autenticarte con OAuth y con una API Key, verificar la firma de un Webhook antes de confiar en su contenido, y diagnosticar por qué un Webhook de Cal.com no llega a su destino usando el apartado «Errores frecuentes» de este manual.

Qué acabas de conseguir

Tienes una referencia completa de Cal.com —planes, API, Webhooks, seguridad y diagnóstico de errores— a la que volver en cualquier momento del curso sin depender de la memoria ni de fuentes no verificadas.

Ejercicio práctico

Explica, en dos o tres frases, qué harías si necesitas confirmar con seguridad total si tu plan Free de Cal.com incluye Webhooks nativos ilimitados para tu proyecto, sabiendo que la página de precios no lo confirma explícitamente para un usuario individual.

Resumen de lo imprescindible

El plan Free de Cal.com cubre generosamente la gestión de eventos y reservas para un usuario individual; los Webhooks aparecen documentados como disponibles en la plataforma, pero «Custom APIs» se lista explícitamente sólo desde el plan Teams: verifica en tu propia cuenta antes de asumir cobertura completa en el plan gratuito.
Cal.com es open source; en 2026 su edición comunitaria autoalojable se relanzó como Cal.diy, separada del producto alojado de pago.
La API v2 admite OAuth (recomendado para integraciones) y API Key (más simple, para pruebas); nunca expongas una API Key en código de cliente ni en repositorios públicos.
Los Webhooks incluyen una firma verificable en X-Cal-Signature-256: valídala siempre antes de procesar el contenido recibido.

Estoy preparado para continuar si puedo…

Explicar qué funciones de Cal.com están confirmadas en el plan Free y cuáles requieren verificación o el plan Teams.
Generar una API Key de forma segura y usarla en la cabecera Authorization de una petición de prueba.
Configurar un Webhook con su disparador correcto y verificar su firma en el sistema receptor.
Diagnosticar por qué un Webhook de Cal.com no llega a su destino.

Fuentes

Última actualización de esta lección: 2026-08-30.

Navegación

Lección anterior: Plan de 30 días para el primer cliente

Volver a la ruta completa del curso

Descargar esta lección en PDF accesible