API pública y webhooks de VitalDesk: guía para desarrolladores
Cómo generar API keys con permisos granulares, autenticarte, crear pacientes y citas por API REST, y recibir webhooks firmados cuando pasan cosas en tu clínica.
VitalDesk expone una API REST y webhooks salientes para que conectes tu clínica con cualquier sistema externo: un CRM, una herramienta de automatización como n8n o Make, tu facturador electrónico o un desarrollo propio. Esta guía cubre la autenticación, los permisos y los endpoints principales.
La API está disponible en el plan Enterprise, sin costo adicional por uso. La documentación OpenAPI completa se entrega junto con el acceso.
Generar una API key (lo hace el administrador, autoservicio)
- Ve a Configuración → API y Webhooks (grupo Avanzado).
- En la pestaña API Keys, presiona Crear y asigna un nombre descriptivo (por ejemplo, "Integración CRM").
- Marca los permisos (scopes) que tendrá la key: lectura y escritura son independientes — Pacientes (leer), Pacientes (crear/editar), Citas (leer), Citas (crear/editar), Pagos, Tratamientos, Inventario y Reportes.
- Copia la key en ese momento: por seguridad se muestra una sola vez (en el servidor solo se guarda su hash). Si la pierdes, revócala y crea otra.
Cada key queda atada exclusivamente a tu clínica, registra su último uso, se puede desactivar al instante y admite fecha de expiración. El límite estándar es de 1.000 solicitudes por minuto por key.
Autenticación
Envía la key en el header X-API-Key de cada solicitud:
curl https://api.vitaldesk.cl/api/v1/external/patients \
-H "X-API-Key: vd_live_tu_clave_aqui"Endpoints principales
- GET /external/patients — lista y busca pacientes (por nombre, documento, email, teléfono o identificador externo).
- POST /external/patients — crea un paciente. Es idempotente: si el paciente ya existe (mismo identificador externo, documento, email o teléfono), devuelve el existente en vez de duplicarlo.
- GET /external/appointments — lista citas con filtros por fecha, profesional, paciente y estado (incluye
completed= asistió yno_show= no asistió). - POST /external/appointments — crea una cita validando solapes de horario (con opción de sobrecupo).
- PATCH /external/appointments/{id} — reagenda, cancela o cambia el estado de una cita.
- GET /external/payments · /treatments · /inventory/items · /reports/summary — pagos, tratamientos, inventario y resumen de indicadores.
Identificadores externos (external_ref)
Todos los pacientes y citas aceptan un campo external_ref para guardar el ID de tu sistema de origen (por ejemplo, el contact ID de tu CRM). Puedes buscar por él directamente (?external_ref=...), y es la base de la idempotencia: reintentar una creación con el mismo external_ref nunca duplica.
Webhooks salientes
En la pestaña Webhooks registras una URL de destino y eliges los eventos: cita creada, cita actualizada (reagendada, asistió o no asistió), cita cancelada, pago recibido, tratamiento completado y paciente creado.
Cada entrega va firmada con HMAC-SHA256 (header X-VitalDesk-Signature) usando el secret que se te entrega al crear el endpoint — así tu receptor verifica que el mensaje es auténtico. Las entregas fallidas se reintentan automáticamente con espera creciente, y cada intento queda registrado con su código de respuesta.
¿Buscas el caso de uso completo con un CRM? Sigue la guía Conectar GoHighLevel y n8n con VitalDesk.
Preguntas frecuentes
¿La API de VitalDesk tiene costo adicional?⌄
No. La API y los webhooks están incluidos en el plan Enterprise, sin cobro por solicitud ni por volumen dentro del límite estándar de 1.000 solicitudes por minuto por key.
¿Quién puede crear las API keys?⌄
El administrador de la clínica, en autoservicio, desde Configuración → API y Webhooks. Cada key se crea con permisos granulares (lectura y escritura independientes por módulo) y puede revocarse al instante.
¿Puedo crear pacientes y citas por API, o es solo lectura?⌄
Puedes leer y escribir. La API permite crear y editar pacientes, y crear, reagendar, cancelar y cambiar el estado de citas — con validación de solapes y creación idempotente para evitar duplicados.
¿Cómo sé que un webhook realmente viene de VitalDesk?⌄
Cada entrega va firmada con HMAC-SHA256 en el header X-VitalDesk-Signature, usando un secret que solo tú y VitalDesk conocen. Verificando la firma descartas cualquier mensaje falsificado.
¿Hay ambiente de pruebas?⌄
Sí: puedes usar una clínica de evaluación con la prueba gratuita de 14 días y solicitar la habilitación de las funciones Enterprise para validar tu integración antes de contratar.