Explora y prueba la API con la especificación OpenAPI 3.0.3 en Postman

Aprende a descargar la especificación oficial OpenAPI 3.0.3 de WaclisCAL e importarla en Postman, Insomnia o herramientas de desarrollo para explorar endpoints, schemas y ejecutar llamadas de prueba en pocos minutos.

1. Qué permite hacer

La especificación OpenAPI 3.0.3 (anteriormente conocida como Swagger) es el formato estándar de la industria para describir contratos de APIs REST de manera legible tanto para personas como para máquinas. WaclisCAL publica su esquema OpenAPI completo y actualizado directamente desde el servidor.

Al utilizar esta especificación puedes:

• Importar la colección completa de endpoints en Postman o Insomnia con un solo clic.
• Obtener automáticamente todos los parámetros, cabeceras requeridas y cuerpos de petición (request body) tipados y con ejemplos.
• Generar clientes de código (SDKs) en TypeScript, Python, Go, PHP, Java o C# utilizando generadores como openapi-generator.
• Validar contratos de integración antes de desplegar código a producción.

2. Dónde obtener el archivo OpenAPI

El archivo de especificación se encuentra disponible de forma pública y permanente en la siguiente ruta oficial de WaclisCAL:

https://cal.waclis.com/api/wacliscal/v1/openapi.json

Puedes abrir esta URL directamente en tu navegador web para inspeccionar el archivo JSON o descargarla mediante comandos de terminal como curl o wget:

curl -s https://cal.waclis.com/api/wacliscal/v1/openapi.json -o wacliscal-openapi.json

3. Antes de comenzar

Antes de realizar pruebas en Postman:

1. Tener instalada la aplicación de escritorio de Postman o contar con cuenta en Postman Web.
2. Contar con un token de acceso válido de WaclisCAL con permisos de lectura o escritura (con prefijo wcal_evt_...).

4. Paso a paso: Importar y configurar en Postman

Paso 1: Importa la especificación en Postman

1. Abre tu aplicación de Postman.
2. En la esquina superior izquierda de tu espacio de trabajo (Workspace), haz clic en el botón Import.
3. Elige una de las siguientes dos modalidades:

- Por URL (Recomendado): En la casilla de texto, pega la URL: https://cal.waclis.com/api/wacliscal/v1/openapi.json y presiona Enter.

- Por archivo: Si descargaste el archivo openapi.json a tu equipo, arrástralo a la ventana de importación.

1. Postman te preguntará cómo deseas importar el archivo. Selecciona Postman Collection (Colección de Postman) y haz clic en Import.

Paso 2: Configura las variables de entorno

1. En el panel izquierdo de Postman, haz clic en la nueva colección creada: WaclisCAL API v1.
2. Dirígete a la pestaña Variables.
3. Verifica que la variable baseUrl tenga como valor predeterminado:

https://cal.waclis.com/api/wacliscal/v1

1. Crea una variable adicional llamada token y en la columna Current Value pega tu clave de API (ejemplo: wcal_evt_live_...).
2. Haz clic en Save (Guardar).

Paso 3: Configura la autenticación global de la colección

1. En la misma ventana de la colección, ve a la pestaña Authorization.
2. En el selector Type, elige Bearer Token.
3. En el campo Token, ingresa la variable {{token}}.
4. De este modo, todas las peticiones dentro de la colección heredarán automáticamente tu credencial sin tener que copiarla en cada endpoint.
5. Haz clic en Save.

Paso 4: Ejecuta tu primera petición de prueba (`GET /event-types`)

1. Despliega las carpetas de la colección y localiza la carpeta Event Types.
2. Selecciona la petición Get all event types (GET /event-types).
3. Haz clic en el botón azul Send.
4. En el panel inferior de respuesta, observarás el código de estado 200 OK y el listado en formato JSON con todos los Tipos de Evento disponibles en tu cuenta.

Paso 5: Prueba la creación de una reserva en entorno de test

1. Abre la petición Create booking (POST /bookings).
2. Dirígete a la pestaña Body. Notarás que Postman ya precargó la estructura JSON con los campos requeridos (eventTypeId, start, name, email, timeZone).
3. Ajusta el eventTypeId con uno de los IDs obtenidos en el paso anterior y define una fecha futura válida.
4. Haz clic en Send.
5. Recibirás una respuesta 201 Created con el ID de la cita creada y el enlace de videollamada.

5. Estructura de Schemas y Modelos

La especificación OpenAPI de WaclisCAL define formalmente los siguientes componentes en su sección components/schemas:

• EventType: Objeto que representa un servicio con su duración, slug, modalidad y precio.
• AvailabilitySlots: Mapa de fechas con los intervalos disponibles en formato ISO 8601 UTC.
• BookingRequest: Estructura estricta para crear una cita con validación de expresiones regulares en correos y teléfonos.
• BookingResponse: Objeto de respuesta que incluye identificador único (uid), enlaces de reprogramación y estado.
• ApiError: Esquema estándar de error con código unívoco y mensaje descriptivo.

6. Generación automática de clientes (SDKs)

Si estás desarrollando en TypeScript, Python o Java, puedes generar un cliente fuertemente tipado en segundos utilizando el CLI oficial de OpenAPI Generator:

# Ejemplo: Generar cliente TypeScript para Axios
npx @openapitools/openapi-generator-cli generate \
-i https://cal.waclis.com/api/wacliscal/v1/openapi.json \
-g typescript-axios \
-o ./src/wacliscal-client

Esto creará todas las interfaces, tipos y métodos para interactuar con la agenda con autocompletado y validación de tipos estática en tu IDE.

7. Problemas frecuentes

Postman devuelve error "401 Unauthorized"

• Causa: No se configuró la cabecera de autenticación Bearer, o la variable {{token}} no fue guardada con un valor válido en la colección.
• Solución: Revisa la pestaña Authorization de la colección y confirma que el token ingresado comience con el prefijo oficial y no contenga espacios accidentales.

Error "409 Conflict: SLOT_ALREADY_BOOKED" al probar POST /bookings

• Causa: El horario que estás enviando en el cuerpo de la petición ya está ocupado o se encuentra fuera del horario de atención del profesional.
• Solución: Ejecuta primero la consulta GET /availability para obtener un horario libre comprobado y copia esa misma marca de tiempo en el campo start.

8. Buenas prácticas

• Mantén la colección sincronizada: Cuando WaclisCAL incorpore nuevos endpoints a la API v1, simplemente vuelve a importar la URL de openapi.json en Postman para actualizar los modelos sin perder tus variables de entorno.
• Utiliza entornos separados (Environments): Crea un entorno de Postman para desarrollo/pruebas y otro para producción con sus respectivos tokens para evitar agendar citas accidentales en calendarios reales.
• Prueba primero con métodos seguros (GET): Familiarízate con la estructura de datos mediante consultas de lectura antes de ejecutar peticiones POST o DELETE.

9. Artículos relacionados

• Integra WaclisCAL con tus propios sistemas mediante la API REST v1 oficial
• Genera y administra tokens de acceso seguros por Tipo de Evento
• Conecta tu agenda con asistentes de IA externos utilizando el Servidor MCP