Integra WaclisCAL con tus propios sistemas mediante la API REST v1 oficial

Guía técnica para desarrolladores e integradores sobre la arquitectura, autenticación Bearer, endpoints de consulta de disponibilidad, creación de reservas y manejo de respuestas de la API REST v1 oficial de WaclisCAL.

1. Visión general de la API v1

La API REST v1 de WaclisCAL proporciona acceso programático seguro a las capacidades centrales de la plataforma de agendamiento. Diseñada bajo principios REST estándar, permite a equipos de ingeniería integrar calendarios de citas dentro de aplicaciones móviles nativas (iOS / Android), portales de clientes, plataformas de telemedicina, CRMs o sistemas de gestión empresarial propios.

Características técnicas principales:

• Protocolo: HTTPS obligatorio en todas las peticiones.
• Formato de datos: Intercambio exclusivo en application/json.
• Codificación: UTF-8 estricto.
• Autenticación: Cabecera HTTP Authorization: Bearer [TOKEN].
• Ruta base oficial: https://cal.waclis.com/api/wacliscal/v1
• Tiempos y fechas: Estándar ISO 8601 en formato UTC (ejemplo: 2026-09-18T14:30:00.000Z).

2. Autenticación y Seguridad

Todas las solicitudes a la API deben incluir un token de acceso válido generado previamente en el panel de control de WaclisCAL (consulta la guía Genera y administra tokens de acceso seguros por Tipo de Evento).

Cabecera HTTP requerida:

Authorization: Bearer wcal_evt_live_a1b2c3d4e5f6g7h8i9j0
Content-Type: application/json
Accept: application/json

Si el token es inválido, ha expirado o fue revocado, la API responderá con un código de estado HTTP 401 Unauthorized. Si el token carece de permisos para el Tipo de Evento solicitado, responderá con HTTP 403 Forbidden.

3. Catálogo de Endpoints Principales

3.1 Consulta de Tipos de Evento (`GET /event-types`)

Obtiene la lista de servicios activos configurados en la cuenta o autorizados para el token provisto.

• Método: GET
• Ruta: /api/wacliscal/v1/event-types
• Parámetros de consulta (Query params):

- active (booleano, opcional): true para filtrar únicamente eventos habilitados.

Ejemplo de respuesta (200 OK):

{
"success": true,
"data": [
{
"id": 124,
"title": "Asesoría Comercial Personalizada",
"slug": "asesoria-comercial",
"length": 45,
"description": "Sesión de evaluación de requerimientos corporativos.",
"requiresConfirmation": false,
"currency": "ARS",
"price": 0
}
]
}

3.2 Consulta de Disponibilidad de Horarios Libres (`GET /availability`)

Devuelve los intervalos horarios disponibles para un servicio específico dentro de un rango de fechas, calculando en tiempo real los eventos de Google Calendar, los descansos (buffers) y la antelación mínima.

• Método: GET
• Ruta: /api/wacliscal/v1/availability
• Parámetros de consulta obligatorios:

- eventTypeId (entero): ID del Tipo de Evento.

- dateFrom (string YYYY-MM-DD): Fecha de inicio de búsqueda.

- dateTo (string YYYY-MM-DD): Fecha de fin de búsqueda.

- timeZone (string IANA, opcional): Zona horaria para formatear los slots (ej. America/Argentina/Buenos_Aires).

Ejemplo de solicitud cURL:

curl -X GET "https://cal.waclis.com/api/wacliscal/v1/availability?eventTypeId=124&dateFrom=2026-09-20&dateTo=2026-09-21&timeZone=America/Argentina/Buenos_Aires" \
-H "Authorization: Bearer wcal_evt_live_a1b2c3d4e5f6g7h8i9j0"

Ejemplo de respuesta (200 OK):

{
"success": true,
"data": {
"2026-09-20": [
{ "time": "2026-09-20T10:00:00.000Z", "local": "07:00" },
{ "time": "2026-09-20T11:00:00.000Z", "local": "08:00" },
{ "time": "2026-09-20T15:30:00.000Z", "local": "12:30" }
],
"2026-09-21": [
{ "time": "2026-09-21T14:00:00.000Z", "local": "11:00" },
{ "time": "2026-09-21T16:00:00.000Z", "local": "13:00" }
]
}
}

3.3 Creación de una Reserva (`POST /bookings`)

Registra una nueva cita en el calendario del anfitrión, despacha las confirmaciones oficiales por WhatsApp y correo electrónico, y genera la sala de videollamada si corresponde.

• Método: POST
• Ruta: /api/wacliscal/v1/bookings

Ejemplo de cuerpo de la petición (JSON Body):

{
"eventTypeId": 124,
"start": "2026-09-20T15:30:00.000Z",
"name": "Mariana López",
"email": "mariana.lopez@cliente.com",
"timeZone": "America/Argentina/Buenos_Aires",
"phone": "+5491155554321",
"responses": {
"motivo": "Implementación de WaclisCAL en equipo de ventas",
"personas": "5"
},
"metadata": {
"crm_lead_id": "LD-98234",
"source": "mobile_app_ios"
}
}

Ejemplo de respuesta exitosa (201 Created):

{
"success": true,
"data": {
"id": 8942,
"uid": "bkg_f8a92b3c4d5e",
"title": "Asesoría Comercial Personalizada con Mariana López",
"startTime": "2026-09-20T15:30:00.000Z",
"endTime": "2026-09-20T16:15:00.000Z",
"status": "ACCEPTED",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"cancellationUrl": "https://cal.waclis.com/booking/bkg_f8a92b3c4d5e?cancel=true",
"rescheduleUrl": "https://cal.waclis.com/booking/bkg_f8a92b3c4d5e?reschedule=true"
}
}

3.4 Cancelación de una Reserva (`DELETE /bookings/{id}`)

Anula una reserva confirmada, libera el espacio horario en la agenda y notifica a ambas partes.

• Método: DELETE
• Ruta: /api/wacliscal/v1/bookings/8942

Cuerpo de la petición (opcional):

{
"reason": "Reunión suspendida a solicitud del cliente."
}

Ejemplo de respuesta (200 OK):

{
"success": true,
"message": "Reserva cancelada exitosamente y horario liberado."
}

4. Códigos de Estado y Manejo de Errores

La API utiliza los códigos de estado HTTP estándar:

Formato de respuesta de error:

{
"success": false,
"error": {
"code": "SLOT_ALREADY_BOOKED",
"message": "El horario seleccionado ya no se encuentra disponible. Por favor elija un nuevo horario."
}
}

5. Límites de Tasa (Rate Limiting)

Para proteger la infraestructura de producción y garantizar alta disponibilidad, se aplican límites automáticos por IP y por token de acceso:

• Consultas de lectura (GET): Hasta 120 peticiones por minuto.
• Creación y cancelación (POST, DELETE): Hasta 30 peticiones por minuto.

Si tu aplicación supera estos umbrales, recibirá una respuesta HTTP 429 Too Many Requests con la cabecera Retry-After: 60 indicando los segundos que debe esperar antes de reintentar.

6. Buenas prácticas para desarrolladores

1. Almacena los tokens en variables de entorno seguras: Nunca expongas tokens con prefijo wcal_evt_... en repositorios públicos de Git ni en código frontend del cliente.
2. Implementa reintentos exponenciales (Exponential Backoff): Maneja respuestas 429 o 5xx con pausas progresivas (1s, 2s, 4s, 8s).
3. Aprovecha el campo metadata: Envía identificadores de tu propio sistema (ejemplo: crm_lead_id o patient_id) para facilitar la reconciliación de datos entre plataformas.
4. Combina la API con Webhooks: Usa la API para consultas activas y creación de reservas, y utiliza Webhooks para escuchar eventos de cancelación o cambios sin sobrecargar el servidor con peticiones repetitivas.

7. Artículos relacionados

• Explora y prueba la API con la especificación OpenAPI 3.0.3 en Postman
• Conecta tu agenda con asistentes de IA externos utilizando el Servidor MCP
• Genera y administra tokens de acceso seguros por Tipo de Evento
• Configura Webhooks para conectar WaclisCAL con tus sistemas internos y bases de datos
• Solución: La API REST o el Servidor MCP responden con error de autorización 401