> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md).

# API compatible con Cal.com

Los endpoints /v2 de dCal siguen la forma de la API v2 de Cal.com, así que una herramienta o automatización que ya habla con Cal.com puede leer tus tipos de evento y horarios libres, y crear, leer, mo

Algunas herramientas, automatizaciones y agentes de IA ya saben hablar con la API v2 de Cal.com. dCal responde a un conjunto de esas mismas operaciones bajo `/v2`, con las mismas rutas, la misma cabecera `cal-api-version` y los mismos nombres de campos, así que puedes apuntar esas herramientas a dCal con una clave de API de dCal.

Si vas a escribir tu propia integración desde cero, la [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md) puede ser más simple. Las dos comparten el mismo motor de reservas y ofrecen los mismos horarios libres. Una diferencia: `/v2` solo reserva un horario que el evento ofrece, mientras que `/v1/machine` también puede reservar un horario libre fuera de esos horarios. El servidor MCP de dCal para asistentes de IA, que también usa ese motor, está disponible en `https://mcp.dcal.ai/mcp`: mira [Conecta un asistente de IA (MCP)](https://docs.dapta.ai/dapta-docs-es/dcal/developers/mcp-server.md).

Aquí no hay capturas de pantalla: todo lo de esta página pasa entre tu sistema y la API.

***

## URL base y autenticación

|                     |                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| URL base            | `https://api.dcal.ai/v2`                                                                                                                               |
| Autenticación       | `Authorization: Bearer <tu clave de API>`. La clave empieza con `dcl_`. No se acepta ninguna otra cabecera.                                            |
| Cabecera de versión | `cal-api-version`, con el valor exacto que pide cada endpoint (mira abajo). Si falta o es otro valor, la respuesta es `400` `UNSUPPORTED_API_VERSION`. |
| Formato del cuerpo  | JSON, con `Content-Type: application/json`                                                                                                             |
| Horas               | ISO 8601 con `Z` o un desfase, por ejemplo `2026-11-03T15:00:00-05:00`                                                                                 |

Crea la clave en **API y webhooks** > **Claves API**. Mira [Claves de API](https://docs.dapta.ai/dapta-docs-es/dcal/developers/api-keys.md). Una clave limitada a algunos tipos de evento solo ve esos: `/v2/event-types` lista solo esos, y cualquier otro tipo de evento, o una reserva de otro, responde `404` `RESOURCE_NOT_FOUND`. Los endpoints de calendarios no se limitan por tipo de evento.

> **⚠️ Nota:** Llama a la API desde un servidor. Nunca pongas una clave en una página web ni en una URL.

***

## Endpoints

| Método y ruta                        | `cal-api-version` | Acceso que necesita la clave                                                         | Qué hace                                                                                                                 |
| ------------------------------------ | ----------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `GET /v2/event-types`                | `2024-06-14`      | **Ver tipos de evento**                                                              | Lista tus tipos de evento visibles, personales y de equipo.                                                              |
| `GET /v2/slots`                      | `2024-09-04`      | **Consultar horarios libres**                                                        | Los horarios libres de un tipo de evento.                                                                                |
| `POST /v2/bookings`                  | `2026-02-25`      | **Crear, apartar, reagendar, confirmar y rechazar reservas**                         | Reserva un horario.                                                                                                      |
| `GET /v2/bookings/{uid}`             | `2026-02-25`      | **Leer reservas**                                                                    | Lee una reserva.                                                                                                         |
| `POST /v2/bookings/{uid}/reschedule` | `2026-02-25`      | **Crear, apartar, reagendar, confirmar y rechazar reservas**                         | Mueve una reserva. La reserva movida recibe un `uid` nuevo.                                                              |
| `POST /v2/bookings/{uid}/cancel`     | `2026-02-25`      | **Cancelar reservas** o **Crear, apartar, reagendar, confirmar y rechazar reservas** | Cancela una reserva.                                                                                                     |
| `POST /v2/bookings/{uid}/guests`     | `2024-08-13`      | **Crear, apartar, reagendar, confirmar y rechazar reservas**                         | Agrega invitados a una reserva.                                                                                          |
| `GET /v2/calendars`                  | ninguno           | **Ver calendarios conectados**                                                       | Lista los calendarios conectados en tu workspace.                                                                        |
| `POST /v2/calendars/availability`    | ninguno           | **Ver calendarios conectados**                                                       | Horarios libres de una duración dada en los calendarios que elijas. Es un agregado de dCal, no una operación de Cal.com. |

Los nombres de acceso son los del diálogo **Crear clave**. En el código son los permisos `event-types:read`, `availability:read`, `bookings:write`, `bookings:read`, `bookings:cancel` y `calendars:read`.

Todas las respuestas tienen la misma envoltura: `{ "status": "success", "data": ... }`.

***

## Cómo elegir el evento

`/v2/slots` y `POST /v2/bookings` necesitan saber de qué tipo de evento hablas. Envía exactamente una de estas opciones:

* `eventTypeId`: el `id` que devuelve `/v2/event-types`. Su `daptaId` también funciona.
* `eventTypeSlug` con `username`: un evento personal, por su identificador y el identificador del anfitrión.
* `eventTypeSlug` con `teamSlug`: un evento de equipo, por su identificador y el del equipo.

Para el enlace `book.dcal.ai/k7m2xq/jdoe/intro-call`, el identificador del anfitrión es `jdoe` y el del evento es `intro-call`. Aquí los eventos de equipo funcionan, a diferencia de los endpoints `/v1/machine`.

***

## GET /v2/event-types

Filtros opcionales en la consulta: `username`, `teamSlug` y `eventSlug`. Los tipos de evento ocultos nunca aparecen.

Cada tipo de evento trae `id`, `daptaId`, `title`, `slug`, `description`, `lengthInMinutes`, `hidden`, `type` (`personal` o `team`), `username`, `teamSlug`, `schedulingType`, `locations`, `bookingFields`, `bookingWindow`, `successRedirectUrl` y, en un evento de equipo, `team`.

| Campo                | Significado                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bookingWindow`      | Con cuánta anticipación se puede reservar, según la **Antelación máxima (días)** del evento: `{ "type": "calendarDays", "value": 14, "rolling": false }` para 14 días calendario, o `null` cuando el evento no tiene límite. |
| `successRedirectUrl` | La dirección de **Redirigir después de reservar** del evento, tal como se escribió, o `null` cuando los invitados se quedan en la confirmación.                                                                              |

Aquí los dos son solo de lectura: se cambian en los ajustes del evento, en el panel. El documento OpenAPI no incluye estos dos campos.

***

## GET /v2/slots

| Parámetro  | Obligatorio | Significado                                                                                 |
| ---------- | ----------- | ------------------------------------------------------------------------------------------- |
| El evento  | Sí          | Mira [Cómo elegir el evento](#como-elegir-el-evento).                                       |
| `start`    | Sí          | Una fecha como `2026-11-03`, o una hora con desfase.                                        |
| `end`      | Sí          | Una fecha (ese día completo queda incluido) o una hora con desfase.                         |
| `timeZone` | No          | Una zona horaria IANA. Por defecto, `UTC`.                                                  |
| `format`   | No          | `time` (por defecto) da el `start` de cada horario; `range` agrega su `end`.                |
| `duration` | No          | Debe ser igual a la duración del evento. Otro valor responde `422` `FEATURE_NOT_SUPPORTED`. |

Una fecha sola se lee como un día completo en UTC. Para días en tu propia zona horaria, envía horas con desfase. Una ventana de más de 60 días se recorta a 60 días, y no se devuelve ningún horario más allá de la antelación máxima del evento. La respuesta agrupa los horarios por día, en la zona horaria que pediste:

```json
{
  "status": "success",
  "data": {
    "2026-11-03": [
      { "start": "2026-11-03T09:00:00.000-05:00" },
      { "start": "2026-11-03T09:30:00.000-05:00" }
    ]
  }
}
```

Son los mismos horarios que ofrece tu página de reservas. Mira [Cómo se calculan los horarios libres](https://docs.dapta.ai/dapta-docs-es/dcal/calendars-and-availability/how-open-times-work.md).

***

## POST /v2/bookings

| Campo del cuerpo         | Obligatorio                                   | Significado                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| El evento                | Sí                                            | Mira [Cómo elegir el evento](#como-elegir-el-evento).                                                                                                                                                                 |
| `start`                  | Sí                                            | Un horario de `/v2/slots`, con su desfase.                                                                                                                                                                            |
| `attendee`               | Sí                                            | `name`, `email`, `timeZone`, más `phoneNumber` y `language` opcionales. `email` tiene que ser una dirección válida: uno vacío se rechaza con `400`. `language` es `en` o `es`, el idioma de los correos del invitado. |
| `guests`                 | No                                            | Hasta 10 correos más. dCal no les envía correos: se añaden al evento del calendario del anfitrión, y ese calendario le envía su propia invitación a todos los del evento, incluido el invitado principal.             |
| `bookingFieldsResponses` | Cuando el evento tiene preguntas obligatorias | Respuestas a las preguntas de la reserva del evento, con el nombre de cada pregunta como clave.                                                                                                                       |
| `metadata`               | No                                            | Hasta 50 campos propios, con nombres de hasta 40 caracteres y valores de texto de hasta 500 caracteres. Se devuelven tal cual.                                                                                        |
| `destinationCalendarId`  | No                                            | Solo eventos personales: uno de los calendarios del anfitrión, de `/v2/calendars`, que pueda recibir eventos nuevos.                                                                                                  |

Agrega una cabecera `Idempotency-Key` (de 1 a 128 caracteres) para que un reintento nunca reserve dos veces. La misma clave de idempotencia con el mismo cuerpo devuelve la primera reserva; con otro cuerpo, responde `409` `IDEMPOTENCY_KEY_REUSED`.

Una reserva responde `201` con la reserva: su `uid`, `status`, `start`, `end`, `duration`, `hosts`, `attendees`, `guests`, `location`, `meetingUrl`, `bookingFieldsResponses`, `metadata`, `utm` y más. Lo que pasa después es lo mismo que tras una reserva en tu página: los correos, con el enlace del invitado para gestionar la reserva en `book.dcal.ai`, el evento en el calendario, HubSpot si lo conectaste, y un webhook `booking.created`. **Una reserva por persona** no se aplica a las reservas hechas con una clave. **Redirigir después de reservar** y las UTM de campaña son de las reservas hechas en una página de reservas: la respuesta no trae ninguna dirección de redirección, y una reserva hecha con una clave no guarda UTM, así que su `utm` es `null`, salvo que ocupe un cupo en una reserva grupal que ya tiene una campaña.

***

## Leer, mover y cancelar

* **`GET /v2/bookings/{uid}`** devuelve una reserva, con la misma forma. También lee un evento que un anfitrión puso en su propio calendario con la herramienta MCP [`create_event`](https://docs.dapta.ai/dapta-docs-es/dcal/developers/mcp-tools.md#create_event): ese evento no tiene tipo de evento, así que su `eventTypeId` y su `eventType` son `null`. Una clave limitada a algunos tipos de evento no lo ve.
* **`POST /v2/bookings/{uid}/reschedule`** recibe `start` (un nuevo horario ofrecido, con su desfase, dentro de la antelación máxima del evento) y, opcionales, `reschedulingReason` (hasta 1000 caracteres) y `rescheduledBy` (un correo). Responde `201` con la reserva movida, que tiene un `uid` **nuevo**; la reserva anterior queda enlazada a ella. Tus webhooks reciben `booking.rescheduled` con el `uid` nuevo y `rescheduledFromUid`. El correo **Reserva reprogramada** del invitado actualiza la entrada que ya tiene en su calendario en lugar de añadir otra.
* **`POST /v2/bookings/{uid}/cancel`** recibe un `cancellationReason` opcional (hasta 1000 caracteres). Responde `200` con la reserva cancelada y le envía un correo al invitado.
* **`POST /v2/bookings/{uid}/guests`** recibe `guests`: de 1 a 10 por llamada, cada uno con un `email` válido y, opcionales, `name` y `timeZone`. Una reserva admite como máximo 30 personas en total, contando una vez a quien reservó, a cada persona y a cada invitado, o los cupos por horario del evento cuando son más. Un correo que ya está en la reserva se omite. Cuando se añade al menos un invitado a una reserva aceptada, dCal actualiza el evento en el calendario del anfitrión para que quede incluido; dCal no le envía ningún correo. Desde ese momento, el calendario del anfitrión envía sus propias invitaciones y actualizaciones a todos los del evento, incluido el invitado principal.

Cada una de estas respuestas, igual que la de `POST /v2/bookings`, trae `utm`: la campaña de la que vino la reserva, o `null` si no tiene. En una reserva hecha en tu página de reservas desde un enlace con etiquetas UTM, trae los `utm_source`, `utm_medium`, `utm_campaign`, `utm_term` y `utm_content` que guardó la reserva, cada uno solo si está presente. Una reserva movida con `reschedule` conserva su campaña con su `uid` nuevo. `utm` es un añadido de dCal, no un campo de Cal.com, así que un cliente de Cal.com lo ignora. Mira [Mide el origen de tus reservas](https://docs.dapta.ai/dapta-docs-es/dcal/share/your-booking-page.md#mide-el-origen-de-tus-reservas).

Reprogramar, cancelar y agregar invitados también aceptan una cabecera `Idempotency-Key`, con las mismas reglas que al reservar.

***

## Calendarios

* **`GET /v2/calendars`** lista los calendarios conectados en tu workspace, agrupados por conexión, más un `destinationCalendar` sugerido: el primer calendario principal que no es de solo lectura.
* **`POST /v2/calendars/availability`** devuelve los horarios libres, con inicio y fin en UTC, de hasta 100 calendarios de esa lista. Envía `calendarIds`, `from`, `to`, `timeZone`, `durationMinutes` (de 1 a 1440), `intervalMinutes`, `bufferBeforeMinutes` y `bufferAfterMinutes` opcionales, y un `mode`: `perCalendar`, `allAvailable` o `anyAvailable`. Un rango de más de 31 días responde `400` `RANGE_TOO_LARGE`.

***

## Lo que no está disponible

Estas funciones de Cal.com responden `422` `FEATURE_NOT_SUPPORTED`, o no existen:

* Listar reservas. Usa `GET /v1/machine/bookings` de la [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md).
* Apartar un horario antes de reservar (`reservationUid`).
* Eventos grupales con más de un cupo por horario.
* Reservas recurrentes, reuniones instantáneas y enrutamiento.
* Una duración distinta a la del evento (`lengthInMinutes`, `duration`).
* Cambiar el lugar o el enlace de la reunión de una sola reserva.
* Verificación por correo, `allowConflicts`, `allowBookingOutOfBounds` y `skipBookingLimits`.
* Dejar fuera de `/v2/slots` la reserva que se está reprogramando (`bookingUidToReschedule`).
* Un `language` del invitado (`attendee.language`) distinto de `en` o `es`.
* `destinationCalendarId` en un evento de equipo.

***

## Errores

Todos los errores tienen el mismo cuerpo:

```json
{
  "status": "error",
  "error": {
    "code": "SLOT_TAKEN",
    "message": "That time was just booked. Pick another slot.",
    "details": {},
    "requestId": "..."
  }
}
```

El `message` está en inglés y puede cambiar. Usa el `code`. Cada respuesta trae una cabecera `X-Request-Id` con el mismo `requestId`: inclúyelo cuando escribas a soporte.

| Estado | `code`                    | Significado                                                                                                                            |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `INVALID_REQUEST`         | Falta un campo o está mal formado.                                                                                                     |
| `400`  | `INVALID_TIMEZONE`        | La zona horaria no es una zona IANA.                                                                                                   |
| `400`  | `UNSUPPORTED_API_VERSION` | Falta la cabecera `cal-api-version` o no tiene el valor que pide ese endpoint.                                                         |
| `400`  | `RANGE_TOO_LARGE`         | Disponibilidad de calendarios por más de 31 días.                                                                                      |
| `400`  | `INVALID_SLOT`            | El nuevo horario de una reprogramación no es uno que el evento ofrece, por ejemplo uno más allá de su antelación máxima.               |
| `401`  | `AUTHENTICATION_REQUIRED` | No hay cabecera `Authorization`.                                                                                                       |
| `401`  | `INVALID_API_KEY`         | La clave es incorrecta, está revocada o venció, o no se envió como `Bearer dcl_...`.                                                   |
| `403`  | `INSUFFICIENT_SCOPE`      | A la clave le falta el acceso que necesita este endpoint.                                                                              |
| `403`  | `CALENDAR_READ_ONLY`      | El `destinationCalendarId` no puede recibir eventos nuevos.                                                                            |
| `404`  | `RESOURCE_NOT_FOUND`      | No hay ese tipo de evento, reserva o calendario en tu workspace, o está fuera de los tipos de evento de la clave.                      |
| `409`  | `SLOT_TAKEN`              | Ese horario ya no está libre. Elige otro de `/v2/slots`.                                                                               |
| `409`  | `CALENDAR_UNAVAILABLE`    | No se pudo leer un calendario que bloquea reservas, así que no se reservó ni movió nada. Vuelve a intentarlo en un momento.            |
| `409`  | `IDEMPOTENCY_KEY_REUSED`  | Ese `Idempotency-Key` ya se usó con otra petición.                                                                                     |
| `410`  | `GONE`                    | La reserva ya no se puede cambiar.                                                                                                     |
| `422`  | `BOOKING_FIELDS_INVALID`  | Una pregunta obligatoria de la reserva no tiene respuesta, o la hora de inicio no es una que el evento ofrece.                         |
| `422`  | `LIMIT_EXCEEDED`          | Agregar estos invitados llevaría la reserva a más de 30 personas en total, o a más de los cupos por horario del evento cuando son más. |
| `422`  | `FEATURE_NOT_SUPPORTED`   | Mira [Lo que no está disponible](#lo-que-no-esta-disponible). `details.feature` dice cuál.                                             |

***

## Límites

* El cuerpo de cada petición tiene un límite de 100 kB.
* Los endpoints `/v2` no tienen hoy un límite publicado por clave. Construye como si lo tuvieran: cuando recibas un `429`, espera los segundos de `Retry-After`; cuando recibas un `5xx`, reintenta con esperas cada vez más largas y el mismo `Idempotency-Key`.
* La [referencia interactiva](https://api.dcal.ai/docs) y el [documento OpenAPI](https://api.dcal.ai/openapi.json) describen cada campo. En el panel, **API y webhooks** > **Docs de la API** abre la referencia, y la introducción de la referencia enlaza al documento. En la referencia, las operaciones `/v2` están bajo **Cal.com-compatible API**, y `POST /v2/calendars/availability` bajo **Calendar availability**. Su introducción también lista el `cal-api-version` que pide cada operación `/v2`.

## Relacionado

* [Claves de API](https://docs.dapta.ai/dapta-docs-es/dcal/developers/api-keys.md): crea la clave y elige su acceso.
* [API REST](https://docs.dapta.ai/dapta-docs-es/dcal/developers/rest-api.md): los endpoints `/v1/machine`, incluida la lista de reservas.
* [Conecta un asistente de IA (MCP)](https://docs.dapta.ai/dapta-docs-es/dcal/developers/mcp-server.md): el servidor MCP de dCal, disponible en `https://mcp.dcal.ai/mcp` con un inicio de sesión o una clave de API.
* [Webhooks](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks.md): entérate de cada cambio en tus reservas.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
