Integración de la API de TidyCal

Resumen

La integración de TidyCal dentro de las herramientas personalizadas de E-Smart360 permite vincular tu cuenta de TidyCal y gestionar toda la programación directamente desde la plataforma. Ofrece sincronización fluida de reuniones, disponibilidad y reservas mediante la API de TidyCal. Esta integración simplifica la gestión del calendario y mejora la eficiencia del flujo de trabajo en E-Smart360.

Dispones de dos herramientas:

• tidycal_check_availability_of_slots — Obtiene franjas horarias disponibles para un tipo de reserva.
• tidycal_book_appointment — Crea una reserva (ocupa una franja horaria).

Estas herramientas encapsulan llamadas a la API REST de TidyCal. La autenticación se realiza mediante Personal Access Token / token bearer OAuth.

Versión de la API: 0.1

Autenticación

Para autenticarte con la API de TidyCal necesitas un Personal Access Token:

• Crea un Personal Access Token en la configuración de integraciones de TidyCal.
• Envía el token en la cabecera Authorization: Bearer {TOKEN} en todas las llamadas de las herramientas.

Ejemplo de definición de herramienta con autenticación:

{
  "key": "tidycal_check_availability_of_slots",
  "name": "Check TidyCal Availability",
  "description": "Obtiene franjas horarias disponibles para un tipo de reserva entre dos fechas dadas.",
  "pre_call_message": "Déjame comprobar las franjas disponibles...",
  "parameters": {
    "type": "object",
    "required": ["startTime", "endTime"],
    "properties": {
      "startTime": {
        "type": "string",
        "description": "Fecha de inicio para consultar franjas en formato YYYY-MM-DD. Se combina con la hora (normalmente medianoche UTC) para la API."
      },
      "endTime": {
        "type": "string",
        "description": "Fecha de fin para consultar franjas en formato YYYY-MM-DD. Se combina con la hora (UTC) según sea necesario. Normalmente fin del día."
      }
    }
  },
  "value": {
    "method": "GET",
    "url": "https://tidycal.com/api/booking-types/YOUR_BOOKING_TYPE_ID/timeslots",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "starts_at": "%(startTime)sT00:00:00Z",
      "ends_at": "%(endTime)sT23:59:59Z"
    }
  }
}

Herramienta: tidycal_check_availability_of_slots

Qué hace: obtiene franjas disponibles entre dos momentos dados para un tipo de reserva específico.

Comportamiento:

• Convierte startTime y endTime proporcionados por el usuario (fechas locales) en datetimes UTC-ISO completos para la consulta, p. ej. YYYY-MM-DDT00:00:00Z y YYYY-MM-DDT23:59:59Z.
• Envía una solicitud GET a https://tidycal.com/api/booking-types/{bookingTypeId}/timeslots con los parámetros de consulta starts_at y ends_at.

Respuesta exitosa:

• 200 OK
• JSON con "data" → lista de objetos, cada uno con campos como starts_at, ends_at, available_bookings.

Errores / casos límite:

• Si bookingType no existe o no es accesible → probablemente 403 o 404.
• Si no hay franjas en ese periodo → data puede ser una lista vacía.

Definición JSON de la herramienta:

{
  "key": "tidycal_check_availability_of_slots",
  "name": "Check TidyCal Availability",
  "description": "Obtiene franjas horarias disponibles para un tipo de reserva entre dos fechas dadas.",
  "pre_call_message": "Déjame comprobar las franjas disponibles...",
  "parameters": {
    "type": "object",
    "required": ["startTime", "endTime"],
    "properties": {
      "startTime": {
        "type": "string",
        "description": "Fecha de inicio para consultar franjas en formato YYYY-MM-DD. Se combina con la hora (normalmente medianoche UTC) para la API."
      },
      "endTime": {
        "type": "string",
        "description": "Fecha de fin para consultar franjas en formato YYYY-MM-DD. Se combina con la hora (UTC) según sea necesario. Normalmente fin del día."
      }
    }
  },
  "value": {
    "method": "GET",
    "url": "https://tidycal.com/api/booking-types/YOUR_BOOKING_TYPE_ID/timeslots",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "starts_at": "%(startTime)sT00:00:00Z",
      "ends_at": "%(endTime)sT23:59:59Z"
    }
  }
}

Herramienta: tidycal_book_appointment

Qué hace: crea una reserva (ocupa una franja horaria) para un tipo de reserva especificado.

Parámetros:

Comportamiento:

• Combina preferred_date + preferred_time en la zona horaria del usuario → convierte a una cadena datetime ISO en UTC. P. ej. 2025-09-17T12:30:00.000000Z.
• Envía en el payload:
  • starts_at (datetime UTC)
  • name, email
  • timezone
  • Opcionalmente booking_questions si el tipo de reserva define preguntas

Respuesta exitosa:

• HTTP 201 Created
• JSON con el campo data que contiene los detalles de la reserva (id, contact_id, booking_type_id, starts_at, ends_at, etc.).

Errores / casos límite:

• 403 Forbidden: si el token no tiene permisos de acceso.
• 409 Conflict: si la franja horaria ya no está disponible.
• 422 Validation Error: entrada mal formada (p. ej., email inválido, zona horaria incorrecta o campos obligatorios ausentes).

Definición JSON de la herramienta:

{
  "key": "tidycal_book_appointment",
  "name": "Book TidyCal Appointment",
  "description": "Crea una reserva (ocupa una franja horaria) para un tipo de reserva especificado.",
  "pre_call_message": "Déjame programar esa cita para ti...",
  "parameters": {
    "type": "object",
    "required": ["preferred_date", "preferred_time", "name", "email", "timezone"],
    "properties": {
      "preferred_date": {
        "type": "string",
        "description": "Fecha de la reserva en formato YYYY-MM-DD (hora local)."
      },
      "preferred_time": {
        "type": "string",
        "description": "Hora en esa fecha en formato HH:mm (24 horas). Debe convertirse a UTC."
      },
      "name": {
        "type": "string",
        "description": "Nombre completo de la persona que reserva la cita."
      },
      "email": {
        "type": "string",
        "description": "Correo electrónico de la persona que reserva."
      },
      "timezone": {
        "type": "string",
        "description": "Identificador de zona horaria IANA (p. ej., America/Los_Angeles, Europe/London). Necesario para la conversión a UTC."
      }
    }
  },
  "value": {
    "method": "POST",
    "url": "https://tidycal.com/api/booking-types/YOUR_BOOKING_TYPE_ID/bookings",
    "api_token": "Bearer YOUR_API_TOKEN",
    "param": {
      "starts_at": "%(preferred_date)sT%(preferred_time)s:00.000000Z",
      "name": "%(name)s",
      "email": "%(email)s",
      "timezone": "%(timezone)s"
    }
  }
}

Endpoints utilizados

Según la documentación oficial de la API de TidyCal, estos son los endpoints relevantes:

Ambos endpoints requieren autenticación mediante la cabecera Authorization: Bearer {TOKEN}.

Ejemplos de uso

1. Comprobar disponibilidad

curl --location 'https://tidycal.com/api/booking-types/1367385/timeslots?starts_at=2025-09-17T00:00:00Z&ends_at=2025-09-18T23:59:59Z' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN'

2. Reservar una cita

curl --location 'https://tidycal.com/api/booking-types/1367385/bookings' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data-raw '{
    "starts_at": "2025-09-17T12:30:00.000000Z",
    "name": "John Doe E-Smart360 Test",
    "email": "john@example.com",
    "timezone": "America/Los_Angeles"
  }'

Buenas prácticas y notas

• Formato de fecha y hora: asegúrate de que todos los valores enviados a la API estén en UTC y en formato ISO 8601 válido. TidyCal lo exige.
• Manejo de zonas horarias: incluye siempre timezone en las llamadas de reserva para que TidyCal interprete correctamente. Usa identificadores IANA (p. ej., America/Los_Angeles, Europe/London).
• Manejo de errores: gestiona conflictos (franja ya ocupada), prohibiciones y errores de validación. Comprueba siempre los códigos de estado de la respuesta y ofrece mensajes claros al usuario.
• Consulta de disponibilidad: usa datetimes de inicio y fin precisos; evita errores de un día. Convierte siempre las fechas locales a UTC correctamente.
• Seguridad: almacena los tokens de API de forma segura. No los expongas en código del lado del cliente, repositorios públicos ni documentación. Usa variables de entorno o prácticas seguras de gestión de configuración.
• Booking Type ID: sustituye YOUR_BOOKING_TYPE_ID en las URLs por el ID real de tu tipo de reserva en TidyCal. Puedes encontrarlo en el panel de TidyCal.

Guías relacionadas

• Introducción a las herramientas personalizadas
• Creación de herramientas personalizadas
• Cómo configurar la integración con Cal.com