# 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. **Categoría**: Integraciones · **Lectura**: 8 min · **Actualizado**: 2026-08-25 --- 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ó y no_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](/tutoriales/conectar-crm-gohighlevel-n8n-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. --- **Tags**: api, webhooks, desarrolladores, integraciones, rest [← Volver a Tutoriales](https://vitaldesk.cl/tutoriales)