Referencia de la API · v1
API de CliniQ
Conecta CliniQ con tu web, tu CRM, Zapier, Make o n8n. La API es REST, recibe y devuelve JSON, usa los códigos de estado HTTP de siempre y se autentica con claves que solo tienen los permisos que eliges.
- Busca y da de alta pacientes, consulta huecos libres y pide citas.
- Lee la bandeja de WhatsApp, Instagram y Messenger y responde dentro de la ventana de 24 h.
- Crea y mueve tratos del CRM.
- Recibe webhooks firmados cuando algo cambia o consulta los eventos de los últimos 30 días.
- Conecta Claude o ChatGPT con el servidor MCP.
Sin datos clínicos, por diseñoLa API nunca da el historial clínico, los formularios, los documentos ni los diagnósticos, ni las notas de la ficha, la cita o el trato. Tampoco borra datos, confirma o anula citas ni cobra.
Viene con el módulo Integraciones y API, incluido en el plan Excellence y en los planes a medida.
Direcciones
https://actions.cliniq.es/api/v1https://actions.cliniq.es/mcpcurl -G https://actions.cliniq.es/api/v1/patients \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "limit=10" \
--data-urlencode "search=lucia 612"const response = await fetch(
"https://actions.cliniq.es/api/v1/patients?limit=10&search=lucia+612",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/patients",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"limit": "10",
"search": "lucia 612",
},
)
response.raise_for_status()
page = response.json()Autenticación
Cada petición lleva una clave de API en la cabecera Authorization como token Bearer. Las claves se crean en CliniQ, en Configuración → Integraciones y API, con el permiso de administración settings:update.
- Empiezan por
cq_live_, así los escáneres de secretos las detectan si se suben a un repositorio. - La clave completa se enseña una sola vez. CliniQ guarda solo su SHA-256 y el principio para reconocerla.
- Revocarla la invalida al momento, en la API y en el MCP. También puede caducar, rotarse o restringirse por origen.
- Una clave solo ve los datos de su clínica. Como mucho, 20 claves activas por clínica.
Solo de servidor a servidorLa API no admite CORS. No pongas nunca una clave en una web pública, una app móvil o un repositorio: guárdala en una variable de entorno, como CLINIQ_API_KEY.
curl https://actions.cliniq.es/api/v1/services \
-H "Authorization: Bearer cq_live_Zr8Qm2xKv7LpT4nW9sYb3HcJ6dFgA1eU"{
"error": {
"code": "UNAUTHORIZED",
"message": "Clave no válida o revocada",
"docUrl": "https://docs.cliniq.es/api/#error-unauthorized",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}Permisos de las claves
Cada clave tiene, por recurso, Ninguno, Lectura o Escritura (la escritura incluye la lectura). Cada nivel equivale a unos permisos, y cada permiso abre un grupo de rutas y nada más. Crea una clave por integración con lo mínimo que necesite. Los permisos se cambian en cualquier momento sin cambiar la clave: valen desde la petición siguiente.
| Recurso | Lectura | Escritura |
|---|---|---|
| Pacientes | patients:read | patients:write |
| Citas | appointments:read | appointments:write |
| Huecos libres | availability:read | — |
| Conversaciones | conversations:read | messages:write |
| Tratos | deals:read | deals:write |
| Eventos | events:read | — |
| Permiso | Qué permite |
|---|---|
patients:read | Buscar y ver pacientes (sin historial clínico)GET /patientsGET /patients/{id} |
patients:write | Crear pacientesPOST /patients |
appointments:read | Ver citasGET /servicesGET /appointments |
appointments:write | Pedir citas (quedan pendientes de confirmar)GET /servicesPOST /appointments |
availability:read | Ver servicios y huecos libresGET /servicesGET /availability |
conversations:read | Ver conversaciones y mensajesGET /conversationsGET /conversations/{id}/messages |
messages:write | Enviar mensajes (dentro de la ventana de 24 h)POST /conversations/{id}/messages |
deals:read | Ver embudos y tratosGET /pipelinesGET /deals |
deals:write | Crear y mover tratosPOST /dealsPATCH /deals/{id} |
events:read | Ver los eventos de los últimos 30 días (incluyen el texto de los mensajes recibidos)GET /eventsGET /events/{id} |
Plantillas
Al crear una clave puedes partir de una plantilla y ajustar después cada recurso:
- Web de reservas. Consultar huecos, dar de alta pacientes y pedir citas.
availability:readpatients:readpatients:writeappointments:readappointments:write - Solo lectura. Todo en lectura, sin poder cambiar nada.
patients:readappointments:readavailability:readconversations:readdeals:readevents:read - Asistente de IA. Para Claude o ChatGPT: agenda y bandeja, sin enviar mensajes.
patients:readavailability:readappointments:readappointments:writeconversations:read - CRM. Sincronizar pacientes y tratos con un CRM.
patients:readpatients:writedeals:readdeals:writeevents:read
{
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "La clave no tiene permiso: hace falta deals:write",
"docUrl": "https://docs.cliniq.es/api/#error-insufficient-scope",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}Caducidad, rotación y restricciones
Como las claves restringidas de Stripe, cada clave se puede limitar en el tiempo y en el origen. Todo se configura en Configuración → Integraciones y API y vale al momento, sin cambiar la clave.
Caducidad
- Es opcional. Si la pones, tiene que ser al menos dentro de una hora y como mucho a dos años vista.
- Desde ese momento la clave responde
401 KEY_EXPIRED. - Siete días antes, administración recibe un aviso en la campana para rotarla o alargarla.
Rotar una clave
«Rotar» crea una clave nueva con el mismo nombre, permisos, restricciones y versión (la caducidad se elige de nuevo) y la enseña una sola vez. La anterior sigue funcionando el margen que elijas (ahora mismo, 1 h, 24 h o 7 días) para que cambies la integración sin cortes; pasado el margen responde 401 KEY_EXPIRED. Con «ahora mismo» queda revocada al momento.
Restringir el origen
- IP y rangos CIDR, IPv4 o IPv6 (como mucho
/8en IPv4 y/16en IPv6). Hasta 50. - Dominios: valen las IP a las que resuelve el dominio (registros A y AAAA, por DNS sobre HTTPS, guardados lo que diga su TTL, entre 1 min y 1 h). Hasta 10. Un dominio que no se puede resolver no da acceso.
- Redes (número de sistema autónomo,
AS3352), hasta 20, y países (ISO 3166-1 alfa-2,ES), hasta 60. Se consultan a ipinfo y se guardan 24 h. Solo si la instalación de CliniQ lo tiene configurado.
La petición tiene que cumplir todas las condiciones que tenga la clave. Las IP y los dominios son alternativas entre sí: basta con coincidir con uno. La IP de origen es la última de X-Forwarded-For, la que añade el proxy de CliniQ, así que no se puede falsear con esa cabecera. Si no cumple, 403 IP_NOT_ALLOWED; si no se puede comprobar el país o la red, 503 IP_LOOKUP_FAILED: una restricción nunca se salta por un fallo.
{
"error": {
"code": "IP_NOT_ALLOWED",
"message": "La clave no admite peticiones desde la IP 203.0.113.7",
"docUrl": "https://docs.cliniq.es/api/#error-ip-not-allowed",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}{
"error": {
"code": "KEY_EXPIRED",
"message": "La clave ha caducado: crea o rota otra en Configuración → Integraciones y API",
"docUrl": "https://docs.cliniq.es/api/#error-key-expired",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}Errores
Los 2xx indican éxito; los 4xx, un problema con la petición; los 5xx, un fallo de CliniQ (poco habitual). Todos los errores devuelven el mismo objeto, con un code estable para tu código y un message en español para las personas. Los campos de entrada desconocidos se ignoran.
Vale la pena reintentar los 409 IDEMPOTENCY_IN_PROGRESS, 429, 500 y 503, esperando un poco y con la misma Idempotency-Key si es una escritura. El resto no cambia por repetir la petición.
| HTTP | code | Cuándo |
|---|---|---|
| 400 | BAD_REQUESTBAD_CURSOR | Entrada no válida: falta un campo, tipo incorrecto, fecha mal escrita, cursor de otra búsqueda… param dice el campo. |
| 400 | BAD_VERSION | CliniQ-Version no es una versión de la API. |
| 401 | UNAUTHORIZED | Falta la clave, está mal formada, no existe o está revocada. |
| 401 | KEY_EXPIRED | La clave ha caducado, o era la anterior de una rotación y ya pasó el margen. |
| 403 | FORBIDDENINSUFFICIENT_SCOPEMODULE_DISABLEDSUBSCRIPTION_INACTIVE | La clave no tiene el permiso, la clínica no tiene el módulo (API, WhatsApp, CRM), está suspendida o tiene la suscripción impagada (solo escrituras). |
| 403 | IP_NOT_ALLOWED | La clave tiene restricciones de origen y la petición no las cumple (IP, dominio, red o país). |
| 404 | NOT_FOUND | No existe o es de otra clínica. |
| 405 | METHOD_NOT_ALLOWED | Método no admitido en esa ruta. La cabecera Allow dice cuáles. |
| 409 | DUPLICATESLOT_TAKENWINDOW_CLOSED | Conflicto con el estado actual: ficha repetida, hueco ocupado, ventana de 24 h cerrada… |
| 409 | IDEMPOTENCY_IN_PROGRESS | La petición original con esa Idempotency-Key aún no ha terminado. Reintenta en unos segundos. |
| 415 | UNSUPPORTED_MEDIA_TYPE | El cuerpo no es application/json. |
| 422 | IDEMPOTENCY_KEY_REUSED | La Idempotency-Key ya se usó con otro método, otra ruta u otro cuerpo. |
| 429 | RATE_LIMITED | Demasiadas peticiones. Espera los segundos de Retry-After. |
| 500 | SERVER_ERROR | Fallo de CliniQ. Reintenta con la misma Idempotency-Key; si se repite, pasa el requestId a soporte. |
| 503 | IP_LOOKUP_FAILED | La clave limita por país o por red y no se pudo comprobar la IP. Reintenta en unos segundos. |
El objeto error
error.codestringCódigo estable del error, en mayúsculas.
error.messagestringExplicación en español. Puede cambiar: no la compares.
error.paramstringSi el error lo provoca un campo concreto, cuál:
startAt,cursor,expand,Idempotency-Key…error.requestIdstringEl
Request-Idde la petición. Dalo al pedir ayuda a soporte.error.docUrlstringEnlace a la explicación del código en esta página.
error.duplicateIdstringSolo con
DUPLICATE: id de la ficha que ya existe.
{
"error": {
"code": "BAD_REQUEST",
"message": "«startAt» tiene que llevar la zona horaria (2026-11-12T10:00:00+01:00)",
"param": "startAt",
"docUrl": "https://docs.cliniq.es/api/#error-bad-request",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}Request-Id y registro
Cada respuesta, también los errores y las del servidor MCP, lleva la cabecera Request-Id (req_…), que en los errores se repite en error.requestId. Guárdala en tus logs: con ella se encuentra la petición en CliniQ.
En Configuración → Integraciones y API, el registro de peticiones enseña las de los últimos 30 días de cada clave: método, ruta, estado, código de error, IP, versión, duración, Idempotency-Key y si fue una respuesta repetida. Entran las peticiones de cada clave, también las rechazadas por sus restricciones de origen (no las de claves desconocidas o caducadas, ni las que pasan del límite). No se guardan los cuerpos ni las respuestas, que pueden llevar datos de pacientes.
HTTP/1.1 200 OK
Cache-Control: no-store
CliniQ-Version: 2026-11-16
Content-Type: application/json
Request-Id: req_8fK2mQ7xLp4Tz9Wb3NcVIdempotencia
Para reintentar una escritura (POST o PATCH) sin miedo a hacerla dos veces, por ejemplo tras un corte de red, envía la cabecera Idempotency-Key con un valor único por operación, como un UUID v4. CliniQ guarda la primera respuesta 24 h y, si llega otra petición con la misma clave, la devuelve tal cual sin volver a ejecutar nada, con Idempotent-Replayed: true y Original-Request-Id (el Request-Id de la primera).
- Hasta 255 caracteres visibles, sin espacios. Si no,
400 BAD_REQUEST. - Cada clave de API tiene las suyas: el mismo valor con otra clave es otra operación.
- Se guardan también los errores
4xx(un409 SLOT_TAKENse repite igual). Los5xxno: el reintento vuelve a ejecutarse. - La misma clave con otro método, otra ruta u otro cuerpo da
422 IDEMPOTENCY_KEY_REUSED. - Si la primera petición aún no ha terminado,
409 IDEMPOTENCY_IN_PROGRESS: reintenta en unos segundos. - En las
GETse ignora: repetirlas ya no cambia nada.
curl -X POST https://actions.cliniq.es/api/v1/appointments \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Idempotency-Key: 5f0c7c1e-3a8b-4d2e-9f61-2b7d0c4e8a13" \
-H "Content-Type: application/json" \
-d '{
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
"startAt": "2026-11-12T10:00:00+01:00"
}'import { randomUUID } from "node:crypto";
// Una por operación: guárdala y repítela en cada reintento.
const idempotencyKey = randomUUID();
const response = await fetch("https://actions.cliniq.es/api/v1/appointments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLINIQ_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({
patientId: "k17d2x9w4m8f0q3z6c1v5b7n",
serviceId: "j57a9c2e4g6i8k0m2o4q6s8u",
startAt: "2026-11-12T10:00:00+01:00",
}),
});import os
import uuid
import requests
# Una por operación: guárdala y repítela en cada reintento.
idempotency_key = str(uuid.uuid4())
response = requests.post(
"https://actions.cliniq.es/api/v1/appointments",
headers={
"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}",
"Idempotency-Key": idempotency_key,
},
json={
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
"startAt": "2026-11-12T10:00:00+01:00",
},
)HTTP/1.1 201 Created
Content-Type: application/json
CliniQ-Version: 2026-11-16
Idempotent-Replayed: true
Original-Request-Id: req_3Hq9Lw2Zt7Vb5Nx1Kc8M
Request-Id: req_Xp4Rt8Yw2Mn6Qb1Zs9Kd
{ "data": { "id": "jh7b3d5f7h9j1l3n5p7r9t1v", "status": "requested", … } }Versiones
La API se versiona por fecha; la actual es 2026-11-16. Cada clave queda fijada a la versión vigente al crearla, así que un cambio incompatible nunca rompe una integración que ya funciona: llega en una versión nueva y tú decides cuándo pasar a ella. Los cambios compatibles (rutas, campos o eventos nuevos) llegan a todas: tu código debe aceptar campos que no conozca.
- La versión de cada clave se ve y se cambia en su configuración. Al rotarla, la nueva conserva la misma.
- La cabecera
CliniQ-Version: <fecha>usa otra versión solo en esa petición, por ejemplo para probar antes de cambiar la de la clave. - Cada respuesta lleva
CliniQ-Versioncon la versión aplicada. - Una versión que no existe da
400 BAD_VERSION.
Versiones2026-11-16
curl https://actions.cliniq.es/api/v1/patients \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "CliniQ-Version: 2026-11-16"{
"error": {
"code": "BAD_VERSION",
"message": "Versión de la API desconocida en CliniQ-Version",
"docUrl": "https://docs.cliniq.es/api/#error-bad-version",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}Paginación
Las rutas que listan devuelven { data: [...], nextCursor }. Para la página siguiente, repite la petición con cursor=<nextCursor> y los mismos filtros. Cuando nextCursor es null no hay más.
limit va de 1 a 100 (50 por defecto). Una página puede traer menos elementos que limit aunque queden más (se omiten, por ejemplo, fichas fusionadas o notas internas): sigue siempre hasta que nextCursor sea null. Un cursor de otra búsqueda, manipulado o caducado da 400 BAD_CURSOR.
Parámetros
limitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior.
curl -G https://actions.cliniq.es/api/v1/patients \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "limit=100" \
--data-urlencode "cursor=eyJ2IjoxLCJjIjoiazE3…"let cursor = null;
do {
const url = new URL("https://actions.cliniq.es/api/v1/patients");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
});
const page = await response.json();
for (const patient of page.data) {
// …
}
cursor = page.nextCursor;
} while (cursor);import os
import requests
cursor = None
while True:
params = {"limit": 100}
if cursor:
params["cursor"] = cursor
page = requests.get(
"https://actions.cliniq.es/api/v1/patients",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params=params,
).json()
for patient in page["data"]:
...
cursor = page["nextCursor"]
if cursor is None:
breakExpandir objetos
Algunas listas dan solo el id de la paciente (patientId). Con expand=patient traen además su ficha en patient, en la misma petición, sin tener que pedirla aparte. Se puede en GET /appointments, GET /deals y GET /conversations.
- Vale
expand=patientoexpand[]=patient. patientIdsigue ahí.patientes el objeto paciente, onullsi no hay ficha o ya no existe.- Hace falta también el permiso
patients:read. Sin él,403 INSUFFICIENT_SCOPEconparam: "expand". - Otro valor, o
expanden otra ruta, da400 BAD_REQUESTconparam: "expand".
curl -G https://actions.cliniq.es/api/v1/appointments \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "from=2026-11-12" \
--data-urlencode "expand=patient"{
"data": [
{
"endAt": "2026-11-12T10:00:00.000Z",
"id": "jh7b3d5f7h9j1l3n5p7r9t1v",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"services": [
{
"durationMinutes": 60,
"id": "j57a9c2e4g6i8k0m2o4q6s8u",
"name": "Fisioterapia",
"priceCents": 5000
}
],
"source": "online",
"staffId": "jd7c4e6g8i0k2m4o6q8s0u2w",
"staffName": "Ana Sanitaria",
"startAt": "2026-11-12T09:00:00.000Z",
"status": "requested",
"patient": {
"birthDate": "1990-04-12",
"consentMarketing": true,
"createdAt": "2026-11-09T10:00:00.000Z",
"email": "lucia@example.com",
"firstName": "Lucía",
"id": "k17d2x9w4m8f0q3z6c1v5b7n",
"lastName": "Pérez",
"phone": "+34612345678",
"source": "api",
"whatsappOptIn": true
}
}
],
"nextCursor": null
}Límites
- 120 peticiones por minuto y clave, contando las del servidor MCP. Pasado el límite,
429 RATE_LIMITEDcon la cabeceraRetry-Afteren segundos. - Cuerpos JSON de hasta 32 KB (64 KB en
/mcp), conContent-Type: application/json; si no,415. - Las escrituras se rechazan con
403 SUBSCRIPTION_INACTIVEsi la suscripción de la clínica a CliniQ está impagada. Las lecturas siguen funcionando. - Las respuestas llevan
Cache-Control: no-store,Request-IdyCliniQ-Version.
Si recibes un 429, espera lo que diga Retry-After antes de reintentar (con la misma Idempotency-Key si era una escritura). Para sincronizaciones grandes, reparte las peticiones o usa los webhooks en lugar de consultar cada poco.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Request-Id: req_8fK2mQ7xLp4Tz9Wb3NcV
Retry-After: 12
{
"error": {
"code": "RATE_LIMITED",
"message": "Demasiadas peticiones con esta clave: espera un poco",
"docUrl": "https://docs.cliniq.es/api/#error-rate-limited",
"requestId": "req_8fK2mQ7xLp4Tz9Wb3NcV"
}
}Fechas e importes
- Fechas de salida: ISO 8601 en UTC, como
2026-11-12T09:00:00.000Z. - Fechas de entrada: ISO 8601 con zona (
2026-11-12T10:00:00+01:00o…Z) o milisegundos desde 1970. Sin zona,400. - Días:
AAAA-MM-DD, en hora de Madrid. - Importes: enteros en céntimos de euro (
priceCents,valueCents,amountCents). - Teléfonos: se devuelven en E.164 (
+34612345678). - Un recurso va en
{ data: { … } }; una lista, en{ data: [ … ], nextCursor }.
{
"startAt": "2026-11-12T10:00:00+01:00",
"date": "2026-11-12",
"priceCents": 5000
}Recurso
Pacientes
Las fichas de las pacientes, solo con los datos de contacto. La API nunca da el historial clínico, las notas, el DNI, la dirección, las etiquetas ni los campos propios de la ficha.
El objeto paciente
Atributos
idstringIdentificador único.
firstNamestringNombre.
lastNamestringApellidos.
phonestring· puede ser nullTeléfono en formato E.164.
emailstring· puede ser nullEmail.
birthDatestring· puede ser nullFecha de nacimiento (
AAAA-MM-DD).consentMarketingbooleanConsiente comunicaciones comerciales.
whatsappOptInbooleanAcepta recibir mensajes de WhatsApp.
sourcestringPor dónde se dio de alta la ficha.
Valores:
receptiononlineappwebimportapicreatedAttimestampFecha de alta.
{
"birthDate": "1990-04-12",
"consentMarketing": true,
"createdAt": "2026-11-09T10:00:00.000Z",
"email": "lucia@example.com",
"firstName": "Lucía",
"id": "k17d2x9w4m8f0q3z6c1v5b7n",
"lastName": "Pérez",
"phone": "+34612345678",
"source": "api",
"whatsappOptIn": true
}Listar pacientes
GET/v1/patients
Sin search, las fichas más recientes primero. Con search (nombre, teléfono o email, en cualquier orden), las que contienen todas las palabras, de más a menos relevante. El cursor solo vale para la misma búsqueda.
Permisopatients:read
Parámetros de consulta
searchstringNombre, teléfono o email. Hasta 200 caracteres.
limitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior, para pedir la siguiente.
Devuelve
Una lista de objetos paciente. Una página puede traer menos de limit aunque haya más: sigue hasta que nextCursor sea null.
Errores propios
400 BAD_CURSOREl cursor es de otra búsqueda
/v1/patientscurl -G https://actions.cliniq.es/api/v1/patients \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "limit=10" \
--data-urlencode "search=lucia 612"const response = await fetch(
"https://actions.cliniq.es/api/v1/patients?limit=10&search=lucia+612",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/patients",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"limit": "10",
"search": "lucia 612",
},
)
response.raise_for_status()
page = response.json(){
"data": [
{
"birthDate": "1990-04-12",
"consentMarketing": true,
"createdAt": "2026-11-09T10:00:00.000Z",
"email": "lucia@example.com",
"firstName": "Lucía",
"id": "k17d2x9w4m8f0q3z6c1v5b7n",
"lastName": "Pérez",
"phone": "+34612345678",
"source": "api",
"whatsappOptIn": true
}
],
"nextCursor": null
}Obtener una paciente
GET/v1/patients/{id}
Devuelve una ficha por su id.
Permisopatients:read
Parámetros de ruta
idstringobligatorioId de la paciente.
Devuelve
El objeto paciente. 404 NOT_FOUND si no existe o es de otra clínica.
/v1/patients/{id}curl https://actions.cliniq.es/api/v1/patients/k17d2x9w4m8f0q3z6c1v5b7n \
-H "Authorization: Bearer $CLINIQ_API_KEY"const response = await fetch(
"https://actions.cliniq.es/api/v1/patients/k17d2x9w4m8f0q3z6c1v5b7n",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/patients/k17d2x9w4m8f0q3z6c1v5b7n",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"birthDate": "1990-04-12",
"consentMarketing": true,
"createdAt": "2026-11-09T10:00:00.000Z",
"email": "lucia@example.com",
"firstName": "Lucía",
"id": "k17d2x9w4m8f0q3z6c1v5b7n",
"lastName": "Pérez",
"phone": "+34612345678",
"source": "api",
"whatsappOptIn": true
}
}Crear una paciente
POST/v1/patients
Alta mínima de una ficha. Queda en la auditoría con el nombre de la clave y lanza el webhook patient.created.
Permisopatients:write
Cuerpo (JSON)
firstNamestringobligatorioNombre. Hasta 200 caracteres.
lastNamestringApellidos. Hasta 200 caracteres.
phonestringTeléfono. Se normaliza a E.164; sin prefijo se entiende de España.
emailstringEmail.
consentMarketingbooleanConsiente comunicaciones comerciales.
whatsappOptInbooleanAcepta recibir mensajes de WhatsApp. Exige
phone.
Devuelve
El objeto paciente creado, con estado 201.
Errores propios
409 DUPLICATEYa hay una ficha con ese teléfono o email (devuelveduplicateId)
/v1/patientscurl -X POST https://actions.cliniq.es/api/v1/patients \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "lucia@example.com",
"firstName": "Lucía",
"lastName": "Pérez",
"phone": "612 345 678",
"whatsappOptIn": true
}'const response = await fetch(
"https://actions.cliniq.es/api/v1/patients",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLINIQ_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
email: "lucia@example.com",
firstName: "Lucía",
lastName: "Pérez",
phone: "612 345 678",
whatsappOptIn: true,
}),
}
);
const { data } = await response.json();import os
import requests
response = requests.post(
"https://actions.cliniq.es/api/v1/patients",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
json={
"email": "lucia@example.com",
"firstName": "Lucía",
"lastName": "Pérez",
"phone": "612 345 678",
"whatsappOptIn": True,
},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"birthDate": null,
"consentMarketing": false,
"createdAt": "2026-11-09T10:00:00.000Z",
"email": "lucia@example.com",
"firstName": "Lucía",
"id": "k17d2x9w4m8f0q3z6c1v5b7n",
"lastName": "Pérez",
"phone": "+34612345678",
"source": "api",
"whatsappOptIn": true
}
}Recurso
Servicios
Los servicios activos de la clínica, con su duración y su precio. Sirven para pedir huecos libres y citas.
Rutas
El objeto servicio
Atributos
idstringIdentificador único.
namestringNombre.
descriptionstring· puede ser nullDescripción.
durationMinutesintegerDuración en minutos.
priceCentsintegerPrecio en céntimos de euro.
onlineBookablebooleanSi se puede reservar online (y, por tanto, pedir por la API).
{
"description": "Sesión individual de fisioterapia.",
"durationMinutes": 60,
"id": "j57a9c2e4g6i8k0m2o4q6s8u",
"name": "Fisioterapia",
"onlineBookable": true,
"priceCents": 5000
}Listar servicios
GET/v1/services
Todos los servicios activos, sin paginar.
Permiso (uno de)availability:readappointments:readappointments:write
Parámetros
Ninguno.
Devuelve
Una lista de objetos servicio.
/v1/servicescurl https://actions.cliniq.es/api/v1/services \
-H "Authorization: Bearer $CLINIQ_API_KEY"const response = await fetch(
"https://actions.cliniq.es/api/v1/services",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/services",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
)
response.raise_for_status()
data = response.json()["data"]{
"data": [
{
"description": "Sesión individual de fisioterapia.",
"durationMinutes": 60,
"id": "j57a9c2e4g6i8k0m2o4q6s8u",
"name": "Fisioterapia",
"onlineBookable": true,
"priceCents": 5000
}
]
}Recurso
Huecos libres
Las horas libres de un servicio un día, calculadas igual que en la reserva online: turnos, ausencias, bloqueos, festivos, solapes, capacidad, antelación mínima y días por delante de la clínica.
Rutas
El objeto disponibilidad
Atributos
datestringDía consultado.
serviceIdstringId del servicio.
durationMinutesintegerDuración del servicio en minutos.
slotsobject[]Horas libres, por orden.
Atributos
startAttimestampInicio del hueco.
staffIdsstring[]Profesionales libres a esa hora.
{
"date": "2026-11-12",
"durationMinutes": 60,
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
"slots": [
{
"staffIds": [
"jd7c4e6g8i0k2m4o6q8s0u2w"
],
"startAt": "2026-11-12T09:00:00.000Z"
}
]
}Consultar huecos libres
GET/v1/availability
Necesita la reserva online activa y un servicio reservable online. Como mucho, 90 días por delante.
Permisoavailability:read
Parámetros de consulta
serviceIdstringobligatorioId del servicio.
datestringobligatorioDía,
AAAA-MM-DD(hora de Madrid).staffIdstringSolo los huecos de esta profesional.
Devuelve
El objeto disponibilidad del día.
/v1/availabilitycurl -G https://actions.cliniq.es/api/v1/availability \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "date=2026-11-12" \
--data-urlencode "serviceId=j57a9c2e4g6i8k0m2o4q6s8u"const response = await fetch(
"https://actions.cliniq.es/api/v1/availability?date=2026-11-12&serviceId=j57a9c2e4g6i8k0m2o4q6s8u",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/availability",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"date": "2026-11-12",
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"date": "2026-11-12",
"durationMinutes": 60,
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
"slots": [
{
"staffIds": [
"jd7c4e6g8i0k2m4o6q8s0u2w"
],
"startAt": "2026-11-12T09:00:00.000Z"
},
{
"staffIds": [
"jd7c4e6g8i0k2m4o6q8s0u2w"
],
"startAt": "2026-11-12T10:00:00.000Z"
}
]
}
}Recurso
Citas
Las citas de la agenda. Por la API se piden citas: quedan como requested, retienen el hueco 24 h y recepción las confirma o las rechaza desde la agenda.
El objeto cita
Atributos
idstringIdentificador único.
startAttimestampInicio.
endAttimestampFin.
statusstringEstado de la cita.
Valores:
requestedpending_paymentscheduledconfirmedarrivedin_progresscompletedno_showcancelledsourcestringOrigen: la agenda (
staff), la reserva online o la API (online), el área de clientes (app) o una importación.Valores:
staffonlineappimportpatientIdstring· puede ser nullId de la paciente.
staffIdstringId de la profesional.
staffNamestring· puede ser nullNombre de la profesional.
servicesobject[]Servicios de la cita.
Atributos
idstringId del servicio.
namestringNombre.
durationMinutesintegerDuración en minutos.
priceCentsintegerPrecio en céntimos.
patientobject· puede ser nullSolo con
expand=patient: el objeto paciente depatientId, onullsi no hay ficha o ya no existe.
{
"endAt": "2026-11-12T10:00:00.000Z",
"id": "jh7b3d5f7h9j1l3n5p7r9t1v",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"services": [
{
"durationMinutes": 60,
"id": "j57a9c2e4g6i8k0m2o4q6s8u",
"name": "Fisioterapia",
"priceCents": 5000
}
],
"source": "online",
"staffId": "jd7c4e6g8i0k2m4o6q8s0u2w",
"staffName": "Ana Sanitaria",
"startAt": "2026-11-12T09:00:00.000Z",
"status": "requested"
}Listar citas
GET/v1/appointments
Citas que empiezan entre from y to, por hora. Como mucho, 92 días.
Permisoappointments:read
Parámetros de consulta
fromstringDesde (
AAAA-MM-DDo ISO 8601 con zona). Por defecto, ahora.tostringHasta (
AAAA-MM-DDo ISO 8601 con zona). Por defecto, 30 días después.patientIdstringSolo las citas de esta paciente.
expandstring | string[]patientañade la ficha de la paciente enpatient. Necesita tambiénpatients:read. Valeexpand=patientoexpand[]=patient.Valores:
patientlimitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior, para pedir la siguiente.
Devuelve
Una lista de objetos cita.
/v1/appointmentscurl -G https://actions.cliniq.es/api/v1/appointments \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "from=2026-11-12" \
--data-urlencode "to=2026-11-19"const response = await fetch(
"https://actions.cliniq.es/api/v1/appointments?from=2026-11-12&to=2026-11-19",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/appointments",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"from": "2026-11-12",
"to": "2026-11-19",
},
)
response.raise_for_status()
page = response.json(){
"data": [
{
"endAt": "2026-11-12T10:00:00.000Z",
"id": "jh7b3d5f7h9j1l3n5p7r9t1v",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"services": [
{
"durationMinutes": 60,
"id": "j57a9c2e4g6i8k0m2o4q6s8u",
"name": "Fisioterapia",
"priceCents": 5000
}
],
"source": "online",
"staffId": "jd7c4e6g8i0k2m4o6q8s0u2w",
"staffName": "Ana Sanitaria",
"startAt": "2026-11-12T09:00:00.000Z",
"status": "requested"
}
],
"nextCursor": null
}Pedir una cita
POST/v1/appointments
Pide una cita en un hueco libre, como el área de clientes y el asistente de IA. Recepción recibe un aviso. Lanza el webhook appointment.created.
Permisoappointments:write
Cuerpo (JSON)
patientIdstringobligatorioId de la paciente.
serviceIdstringobligatorioId de un servicio reservable online.
startAtstring | integerobligatorioInicio de un hueco que dé
/availability. ISO 8601 con zona o milisegundos.staffIdstringProfesional. Sin ella, cualquiera que esté libre.
Devuelve
El objeto cita, con status: "requested" y estado 201.
Errores propios
409 SLOT_TAKENLa hora ya está ocupada o no es un hueco ofrecido
/v1/appointmentscurl -X POST https://actions.cliniq.es/api/v1/appointments \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
"staffId": "jd7c4e6g8i0k2m4o6q8s0u2w",
"startAt": "2026-11-12T10:00:00+01:00"
}'const response = await fetch(
"https://actions.cliniq.es/api/v1/appointments",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLINIQ_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
patientId: "k17d2x9w4m8f0q3z6c1v5b7n",
serviceId: "j57a9c2e4g6i8k0m2o4q6s8u",
staffId: "jd7c4e6g8i0k2m4o6q8s0u2w",
startAt: "2026-11-12T10:00:00+01:00",
}),
}
);
const { data } = await response.json();import os
import requests
response = requests.post(
"https://actions.cliniq.es/api/v1/appointments",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
json={
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"serviceId": "j57a9c2e4g6i8k0m2o4q6s8u",
"staffId": "jd7c4e6g8i0k2m4o6q8s0u2w",
"startAt": "2026-11-12T10:00:00+01:00",
},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"endAt": "2026-11-12T10:00:00.000Z",
"id": "jh7b3d5f7h9j1l3n5p7r9t1v",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"services": [
{
"durationMinutes": 60,
"id": "j57a9c2e4g6i8k0m2o4q6s8u",
"name": "Fisioterapia",
"priceCents": 5000
}
],
"source": "online",
"staffId": "jd7c4e6g8i0k2m4o6q8s0u2w",
"staffName": "Ana Sanitaria",
"startAt": "2026-11-12T09:00:00.000Z",
"status": "requested"
}
}RecursoNecesita el módulo WhatsApp
Conversaciones
La bandeja de entrada: WhatsApp, Instagram y Messenger. Las notas internas y los mensajes de sistema no salen nunca por la API.
Rutas
El objeto conversación
Atributos
idstringIdentificador único.
channelstringCanal.
Valores:
whatsappinstagrammessengerstatusstringEstado.
Valores:
openclosedpatientIdstring· puede ser nullId de la paciente, si la conversación está enlazada.
contactNamestring· puede ser nullNombre del contacto en el canal.
phonestring· puede ser nullTeléfono (WhatsApp).
assignedStaffIdstring· puede ser nullPersona del equipo asignada.
lastMessageAttimestampÚltimo mensaje, en cualquier sentido.
lastInboundAttimestamp· puede ser nullÚltimo mensaje de la paciente.
lastMessagePreviewstringPrincipio del último mensaje.
unreadintegerMensajes sin leer.
windowOpenbooleanSi se puede escribir texto libre: 24 h desde el último mensaje de la paciente.
windowExpiresAttimestamp· puede ser nullCuándo se cierra la ventana.
patientobject· puede ser nullSolo con
expand=patient: el objeto paciente depatientId, onullsi no hay ficha o ya no existe.
{
"assignedStaffId": null,
"channel": "whatsapp",
"contactName": "Lucía",
"id": "m97e5g7i9k1m3o5q7s9u1w3y",
"lastInboundAt": "2026-11-09T10:00:00.000Z",
"lastMessageAt": "2026-11-09T10:00:00.000Z",
"lastMessagePreview": "¿Tenéis hueco el jueves?",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"phone": "+34612345678",
"status": "open",
"unread": 1,
"windowExpiresAt": "2026-11-10T10:00:00.000Z",
"windowOpen": true
}Listar conversaciones
GET/v1/conversations
La conversación con el último mensaje más reciente primero.
Permisoconversations:read
Parámetros de consulta
statusstringPor defecto,
open.Valores:
openclosedexpandstring | string[]patientañade la ficha de la paciente enpatient. Necesita tambiénpatients:read. Valeexpand=patientoexpand[]=patient.Valores:
patientlimitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior, para pedir la siguiente.
Devuelve
Una lista de objetos conversación.
/v1/conversationscurl -G https://actions.cliniq.es/api/v1/conversations \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "status=open"const response = await fetch(
"https://actions.cliniq.es/api/v1/conversations?status=open",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/conversations",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"status": "open",
},
)
response.raise_for_status()
page = response.json(){
"data": [
{
"assignedStaffId": null,
"channel": "whatsapp",
"contactName": "Lucía",
"id": "m97e5g7i9k1m3o5q7s9u1w3y",
"lastInboundAt": "2026-11-09T10:00:00.000Z",
"lastMessageAt": "2026-11-09T10:00:00.000Z",
"lastMessagePreview": "¿Tenéis hueco el jueves?",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"phone": "+34612345678",
"status": "open",
"unread": 1,
"windowExpiresAt": "2026-11-10T10:00:00.000Z",
"windowOpen": true
}
],
"nextCursor": null
}RecursoNecesita el módulo WhatsApp
Mensajes
Los mensajes de una conversación. Se puede responder con texto libre dentro de la ventana de 24 h; fuera de ella hace falta una plantilla, que se envía desde la bandeja.
El objeto mensaje
Atributos
idstringIdentificador único.
directionstringSentido.
Valores:
inoutauthorstringQuién lo escribió.
automatic: recordatorios, campañas y API;phone_app: la app WhatsApp Business del móvil.Valores:
patientstaffaibotautomaticphone_appkindstringTipo (
text,image,audio…).bodystringTexto.
statusstringEstado de entrega.
Valores:
queuedsentdeliveredreadfailedhasMediabooleanSi lleva un adjunto (la API no lo da).
createdAttimestampEnvío o recepción.
{
"author": "patient",
"body": "¿Tenéis hueco el jueves?",
"createdAt": "2026-11-09T10:00:00.000Z",
"direction": "in",
"hasMedia": false,
"id": "n57f6h8j0l2n4p6r8t0v2x4z",
"kind": "text",
"status": "delivered"
}Listar mensajes
GET/v1/conversations/{id}/messages
Del más reciente al más antiguo.
Permisoconversations:read
Parámetros de ruta
idstringobligatorioId de la conversación.
Parámetros de consulta
limitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior, para pedir la siguiente.
Devuelve
Una lista de objetos mensaje.
/v1/conversations/{id}/messagescurl -G https://actions.cliniq.es/api/v1/conversations/m97e5g7i9k1m3o5q7s9u1w3y/messages \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "limit=20"const response = await fetch(
"https://actions.cliniq.es/api/v1/conversations/m97e5g7i9k1m3o5q7s9u1w3y/messages?limit=20",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/conversations/m97e5g7i9k1m3o5q7s9u1w3y/messages",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"limit": "20",
},
)
response.raise_for_status()
page = response.json(){
"data": [
{
"author": "patient",
"body": "¿Tenéis hueco el jueves?",
"createdAt": "2026-11-09T10:00:00.000Z",
"direction": "in",
"hasMedia": false,
"id": "n57f6h8j0l2n4p6r8t0v2x4z",
"kind": "text",
"status": "delivered"
}
],
"nextCursor": null
}Enviar un mensaje
POST/v1/conversations/{id}/messages
Envía texto por el canal de la conversación. Sale en la bandeja como mensaje automático.
Permisomessages:write
Parámetros de ruta
idstringobligatorioId de la conversación.
Cuerpo (JSON)
textstringobligatorioTexto. Hasta 4.096 caracteres (Instagram, 1.000; Messenger, 2.000).
Devuelve
El id del mensaje y status: "queued". El envío sigue en segundo plano.
Errores propios
409 WINDOW_CLOSEDHan pasado más de 24 h desde el último mensaje de la paciente
/v1/conversations/{id}/messagescurl -X POST https://actions.cliniq.es/api/v1/conversations/m97e5g7i9k1m3o5q7s9u1w3y/messages \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Sí, el jueves a las 10:00 tenemos hueco."
}'const response = await fetch(
"https://actions.cliniq.es/api/v1/conversations/m97e5g7i9k1m3o5q7s9u1w3y/messages",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLINIQ_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
text: "Sí, el jueves a las 10:00 tenemos hueco.",
}),
}
);
const { data } = await response.json();import os
import requests
response = requests.post(
"https://actions.cliniq.es/api/v1/conversations/m97e5g7i9k1m3o5q7s9u1w3y/messages",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
json={
"text": "Sí, el jueves a las 10:00 tenemos hueco.",
},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"conversationId": "m97e5g7i9k1m3o5q7s9u1w3y",
"id": "n58g7i9k1m3o5q7s9u1w3y5a",
"status": "queued"
}
}RecursoNecesita el módulo CRM
Embudos
Los embudos del CRM con sus etapas, en orden.
Rutas
El objeto embudo
Atributos
idstringIdentificador único.
namestringNombre.
stagesobject[]Etapas, en orden.
Atributos
idstringId de la etapa.
namestringNombre.
wonbooleanSi llegar a ella da el trato por ganado.
{
"id": "q27g7i9k1m3o5q7s9u1w3y5a",
"name": "Tratamientos estéticos",
"stages": [
{
"id": "s1",
"name": "Primera visita",
"won": false
},
{
"id": "s2",
"name": "Presupuesto",
"won": false
},
{
"id": "s3",
"name": "Aceptado",
"won": true
}
]
}Listar embudos
GET/v1/pipelines
Embudos no archivados.
Permisodeals:read
Parámetros
Ninguno.
Devuelve
Una lista de objetos embudo.
/v1/pipelinescurl https://actions.cliniq.es/api/v1/pipelines \
-H "Authorization: Bearer $CLINIQ_API_KEY"const response = await fetch(
"https://actions.cliniq.es/api/v1/pipelines",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/pipelines",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
)
response.raise_for_status()
data = response.json()["data"]{
"data": [
{
"id": "q27g7i9k1m3o5q7s9u1w3y5a",
"name": "Tratamientos estéticos",
"stages": [
{
"id": "s1",
"name": "Primera visita",
"won": false
},
{
"id": "s2",
"name": "Presupuesto",
"won": false
},
{
"id": "s3",
"name": "Aceptado",
"won": true
}
]
}
]
}RecursoNecesita el módulo CRM
Tratos
Los tratos del CRM: una oportunidad con una paciente que avanza por las etapas de un embudo. Sin notas ni motivo de pérdida.
El objeto trato
Atributos
idstringIdentificador único.
titlestringTítulo.
patientIdstringId de la paciente.
pipelineIdstringId del embudo.
stageIdstringId de la etapa.
stageNamestring· puede ser nullNombre de la etapa.
statusstringEstado.
Valores:
openwonlostvalueCentsintegerValor en céntimos.
assignedStaffIdstring· puede ser nullPersona del equipo asignada.
createdAttimestampAlta.
stageChangedAttimestampÚltimo cambio de etapa.
closedAttimestamp· puede ser nullCuándo se ganó o se perdió.
patientobject· puede ser nullSolo con
expand=patient: el objeto paciente depatientId, onullsi no hay ficha o ya no existe.
{
"assignedStaffId": null,
"closedAt": null,
"createdAt": "2026-11-02T16:20:00.000Z",
"id": "p17h8j0l2n4p6r8t0v2x4z6b",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"stageChangedAt": "2026-11-05T11:00:00.000Z",
"stageId": "s2",
"stageName": "Presupuesto",
"status": "open",
"title": "Rellenos",
"valueCents": 30000
}Listar tratos
GET/v1/deals
Tratos, filtrados por embudo o estado.
Permisodeals:read
Parámetros de consulta
pipelineIdstringSolo los de este embudo.
statusstringSolo los que tengan este estado.
Valores:
openwonlostexpandstring | string[]patientañade la ficha de la paciente enpatient. Necesita tambiénpatients:read. Valeexpand=patientoexpand[]=patient.Valores:
patientlimitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior, para pedir la siguiente.
Devuelve
Una lista de objetos trato.
/v1/dealscurl -G https://actions.cliniq.es/api/v1/deals \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "pipelineId=q27g7i9k1m3o5q7s9u1w3y5a" \
--data-urlencode "status=open"const response = await fetch(
"https://actions.cliniq.es/api/v1/deals?pipelineId=q27g7i9k1m3o5q7s9u1w3y5a&status=open",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/deals",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"status": "open",
},
)
response.raise_for_status()
page = response.json(){
"data": [
{
"assignedStaffId": null,
"closedAt": null,
"createdAt": "2026-11-02T16:20:00.000Z",
"id": "p17h8j0l2n4p6r8t0v2x4z6b",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"stageChangedAt": "2026-11-05T11:00:00.000Z",
"stageId": "s2",
"stageName": "Presupuesto",
"status": "open",
"title": "Rellenos",
"valueCents": 30000
}
],
"nextCursor": null
}Crear un trato
POST/v1/deals
Crea un trato abierto.
Permisodeals:write
Cuerpo (JSON)
patientIdstringobligatorioId de la paciente.
pipelineIdstringobligatorioId del embudo.
titlestringobligatorioTítulo. Hasta 500 caracteres.
valueCentsintegerValor en céntimos.
stageIdstringEtapa inicial. Por defecto, la primera.
Devuelve
El objeto trato creado, con estado 201.
/v1/dealscurl -X POST https://actions.cliniq.es/api/v1/deals \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"title": "Rellenos",
"valueCents": 30000
}'const response = await fetch(
"https://actions.cliniq.es/api/v1/deals",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLINIQ_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
patientId: "k17d2x9w4m8f0q3z6c1v5b7n",
pipelineId: "q27g7i9k1m3o5q7s9u1w3y5a",
title: "Rellenos",
valueCents: 30000,
}),
}
);
const { data } = await response.json();import os
import requests
response = requests.post(
"https://actions.cliniq.es/api/v1/deals",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
json={
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"title": "Rellenos",
"valueCents": 30000,
},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"assignedStaffId": null,
"closedAt": null,
"createdAt": "2026-11-02T16:20:00.000Z",
"id": "p17h8j0l2n4p6r8t0v2x4z6b",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"stageChangedAt": "2026-11-05T11:00:00.000Z",
"stageId": "s1",
"stageName": "Primera visita",
"status": "open",
"title": "Rellenos",
"valueCents": 30000
}
}Actualizar un trato
PATCH/v1/deals/{id}
Cambia la etapa, el título o el valor. Mover de etapa queda en el historial del trato y lanza deal.stage_changed. Un trato perdido no se mueve: se reabre en CliniQ.
Permisodeals:write
Parámetros de ruta
idstringobligatorioId del trato.
Cuerpo (JSON)
stageIdstringEtapa nueva.
titlestringTítulo.
valueCentsintegerValor en céntimos.
Devuelve
El objeto trato actualizado.
/v1/deals/{id}curl -X PATCH https://actions.cliniq.es/api/v1/deals/p17h8j0l2n4p6r8t0v2x4z6b \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"stageId": "s3"
}'const response = await fetch(
"https://actions.cliniq.es/api/v1/deals/p17h8j0l2n4p6r8t0v2x4z6b",
{
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.CLINIQ_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
stageId: "s3",
}),
}
);
const { data } = await response.json();import os
import requests
response = requests.patch(
"https://actions.cliniq.es/api/v1/deals/p17h8j0l2n4p6r8t0v2x4z6b",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
json={
"stageId": "s3",
},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"assignedStaffId": null,
"closedAt": "2026-11-16T09:30:00.000Z",
"createdAt": "2026-11-02T16:20:00.000Z",
"id": "p17h8j0l2n4p6r8t0v2x4z6b",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"pipelineId": "q27g7i9k1m3o5q7s9u1w3y5a",
"stageChangedAt": "2026-11-16T09:30:00.000Z",
"stageId": "s3",
"stageName": "Aceptado",
"status": "won",
"title": "Rellenos",
"valueCents": 30000
}
}Recurso
Eventos
Lo que ha pasado en la clínica, con los mismos datos que los webhooks: sirven para recuperar entregas perdidas o para sincronizar sin un servidor que las reciba. Se guardan 30 días.
El objeto evento
Atributos
idstringIdentificador único (
evt_…). Es el mismo en el webhook y en sus reintentos y reenvíos.typestringTipo de evento.
Valores:
message.createdconversation.assignedconversation.closedappointment.createdappointment.updatedpatient.createdpayment.receiveddeal.stage_changedcreatedAttimestampCuándo pasó.
dataobjectLos datos del evento, iguales que en el webhook (ver «Tipos de evento»).
{
"createdAt": "2026-11-09T23:14:05.447Z",
"data": {
"email": null,
"firstName": "Nuria",
"lastName": "López",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"phone": "+34622222222",
"source": "reception"
},
"id": "evt_3f9a6c0e1b7d4a2f",
"type": "patient.created"
}Listar eventos
GET/v1/events
Eventos de los últimos 30 días, el más reciente primero. Incluye el texto de los mensajes recibidos (message.created).
Permisoevents:read
Parámetros de consulta
typestringSolo los de este tipo.
Valores:
message.createdconversation.assignedconversation.closedappointment.createdappointment.updatedpatient.createdpayment.receiveddeal.stage_changedlimitintegerElementos por página, de 1 a 100. Por defecto, 50.
cursorstringEl
nextCursorde la página anterior, para pedir la siguiente.
Devuelve
Una lista de objetos evento.
/v1/eventscurl -G https://actions.cliniq.es/api/v1/events \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
--data-urlencode "limit=20" \
--data-urlencode "type=patient.created"const response = await fetch(
"https://actions.cliniq.es/api/v1/events?limit=20&type=patient.created",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data, nextCursor } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/events",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
params={
"limit": "20",
"type": "patient.created",
},
)
response.raise_for_status()
page = response.json(){
"data": [
{
"createdAt": "2026-11-09T23:14:05.447Z",
"data": {
"email": null,
"firstName": "Nuria",
"lastName": "López",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"phone": "+34622222222",
"source": "reception"
},
"id": "evt_3f9a6c0e1b7d4a2f",
"type": "patient.created"
}
],
"nextCursor": null
}Obtener un evento
GET/v1/events/{id}
Devuelve un evento por su id: el id de la entrega del webhook (también en X-CliniQ-Delivery).
Permisoevents:read
Parámetros de ruta
idstringobligatorioId del evento (
evt_…).
Devuelve
El objeto evento. 404 NOT_FOUND si no existe o tiene más de 30 días.
/v1/events/{id}curl https://actions.cliniq.es/api/v1/events/evt_3f9a6c0e1b7d4a2f \
-H "Authorization: Bearer $CLINIQ_API_KEY"const response = await fetch(
"https://actions.cliniq.es/api/v1/events/evt_3f9a6c0e1b7d4a2f",
{
headers: { Authorization: `Bearer ${process.env.CLINIQ_API_KEY}` },
}
);
const { data } = await response.json();import os
import requests
response = requests.get(
"https://actions.cliniq.es/api/v1/events/evt_3f9a6c0e1b7d4a2f",
headers={"Authorization": f"Bearer {os.environ['CLINIQ_API_KEY']}"},
)
response.raise_for_status()
data = response.json()["data"]{
"data": {
"createdAt": "2026-11-09T23:14:05.447Z",
"data": {
"email": null,
"firstName": "Nuria",
"lastName": "López",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"phone": "+34622222222",
"source": "reception"
},
"id": "evt_3f9a6c0e1b7d4a2f",
"type": "patient.created"
}
}Webhooks
Webhooks
En lugar de preguntar a la API cada poco, CliniQ te avisa: cuando pasa algo, hace un POST firmado a la URL que elijas.
- En Configuración → Integraciones y API, crea un webhook con la URL, los eventos y una descripción. Como mucho, 10 por clínica.
- Guarda el secreto
whsec_…: se enseña una sola vez (puedes generar otro con «Nuevo secreto»). - Responde
2xxen menos de 10 s y verifica la firma de cada entrega. - Usa «Enviar evento de prueba» (
webhook.test) para probarlo.
Cada evento se guarda además 30 días y se puede leer con GET /events, con los mismos datos y el mismo id.
La URL tiene que ser https://, a un dominio o una IPv4 públicos. Antes de cada entrega se comprueban todas las direcciones a las que resuelve el dominio y la conexión se abre contra esas mismas IP, así que no se puede apuntar a redes privadas ni con DNS rebinding.
{
"createdAt": "2026-11-09T23:14:05.447Z",
"data": {
"email": null,
"firstName": "Nuria",
"lastName": "López",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"phone": "+34622222222",
"source": "reception"
},
"id": "evt_3f9a6c0e1b7d4a2f",
"type": "patient.created"
}Tipos de evento
Ningún evento lleva datos clínicos, notas ni títulos de tratos. No se envían las notas internas, los mensajes salientes ni el historial importado al conectar un número.
| Evento | Cuándo y qué lleva en data |
|---|---|
message.created | Llega un mensaje de la paciente por WhatsApp, Instagram o Messenger. Es el único evento con texto escrito por ella.messageIdconversationIdpatientIdchannelkindbodycreatedAt |
conversation.assigned | Una conversación se asigna, a mano o automáticamente.conversationIdpatientIdassignedStaffIdteamIdauto |
conversation.closed | Alguien del equipo cierra la conversación.conversationIdpatientIdchannelassignedStaffIdclosedByStaffId |
appointment.created | Cita nueva desde la agenda, la reserva online, el área de clientes, el asistente de IA o la API.appointmentIdpatientIdstaffIdserviceIdsstartAtendAtstatussource |
appointment.updated | Cambia el estado, la hora, la profesional, la paciente o los servicios de una cita, desde cualquier sitio. Uno por cita y operación, con todos los cambios juntos.…los de appointment.createdchangesprevious |
patient.created | Ficha nueva: recepción, reserva online, cuenta web o API.patientIdfirstNamelastNamephoneemailsource |
payment.received | Cobro registrado en una factura (mostrador, Stripe, enlace de pago, saldo o tarjeta regalo). No con devoluciones ni importaciones.paymentIdinvoiceIdinvoiceNumberinvoiceStatusisDepositappointmentIdpatientIdamountCentsmethodpaidAt |
deal.stage_changed | Un trato cambia de etapa: a mano, por la API o solo (por una cita o un cobro).dealIdpatientIdpipelineIdfromStageIdtoStageIdtoStageNamestatusvalueCentsauto |
appointment.updated trae los valores actuales, la lista de campos cambiados (changes) y su valor anterior (previous). Si la cita vuelve a quedar como estaba, no se envía. payment.received lleva method: cash, card, transfer, bizum, stripe, wallet o gift_card.
{
"appointmentId": "j97c2e4g6i8k0m2o4q6s8u0w",
"changes": [
"status",
"startAt",
"endAt"
],
"endAt": "2026-11-12T11:00:00.000Z",
"patientId": "k17d2x9w4m8f0q3z6c1v5b7n",
"previous": {
"endAt": "2026-11-12T10:00:00.000Z",
"startAt": "2026-11-12T09:00:00.000Z",
"status": "scheduled"
},
"serviceIds": [
"j57a9c2e4g6i8k0m2o4q6s8u"
],
"source": "staff",
"staffId": "m12d4f6h8j0l2n4p6r8t0v2x",
"startAt": "2026-11-12T10:00:00.000Z",
"status": "confirmed"
}Entrega y reintentos
- Cuenta como entregado cualquier
2xxen menos de 10 s. Las redirecciones no se siguen: cuentan como fallo. - Si falla, se reintenta a los 1 min, 5 min, 30 min, 2 h y 12 h (6 intentos en total).
- El
iddel evento (también enX-CliniQ-Delivery) es el mismo en todos los reintentos: úsalo para no procesar dos veces. - El orden de llegada no está garantizado: ordena por
createdAtsi lo necesitas. - Con 20 fallos seguidos y más de 24 h fallando, el webhook se desactiva solo y se avisa a administración. Al reactivarlo, la cuenta vuelve a cero.
- Configuración → Integraciones y API enseña las últimas 50 entregas con su estado, código HTTP, intentos y tiempo.
- Una entrega terminada se puede reenviar a mano desde ahí: sale otra vez el mismo evento, con el mismo
id, en un solo intento. Solo mientras el evento esté guardado (30 días).
POST /webhooks/cliniq HTTP/1.1
Content-Type: application/json
User-Agent: CliniQ-Webhooks/1.0
X-CliniQ-Event: patient.created
X-CliniQ-Delivery: evt_3f9a6c0e1b7d4a2f
X-CliniQ-Signature: t=1794266045,v1=5d2c8e…Verificar la firma
Cada entrega lleva X-CliniQ-Signature: t=<segundos>,v1=<firma>. v1 es el HMAC-SHA256, en hexadecimal, de <t>.<cuerpo> con el secreto del webhook.
- Lee el cuerpo tal cual llega, sin parsearlo ni volver a serializarlo.
- Calcula el HMAC de
t, un punto y el cuerpo, y compáralo conv1en tiempo constante. - Rechaza las firmas con
tde hace más de 5 minutos, para evitar reenvíos.
import { createHmac, timingSafeEqual } from "node:crypto";
export const verifyCliniq = (rawBody, header, secret, toleranceSeconds = 300) => {
const parts = Object.fromEntries(
header.split(",").map((part) => part.split("="))
);
const timestamp = Number(parts.t);
if (!parts.v1 || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
return false;
}
const expected = createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
return (
expected.length === parts.v1.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
);
};
// Express: el cuerpo tal cual llega, sin parsear.
app.post("/webhooks/cliniq", express.raw({ type: "application/json" }), (req, res) => {
const ok = verifyCliniq(
req.body.toString("utf8"),
req.get("X-CliniQ-Signature") ?? "",
process.env.CLINIQ_WEBHOOK_SECRET
);
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body);
// Usa event.id para no procesar dos veces el mismo evento.
res.sendStatus(200);
});import hashlib
import hmac
import time
def verify_cliniq(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(item.split("=", 1) for item in header.split(","))
if abs(time.time() - int(parts.get("t", "0"))) > tolerance:
return False
expected = hmac.new(
secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
# Flask
@app.post("/webhooks/cliniq")
def cliniq_webhook():
if not verify_cliniq(
request.get_data(),
request.headers.get("X-CliniQ-Signature", ""),
os.environ["CLINIQ_WEBHOOK_SECRET"],
):
abort(400)
event = request.get_json()
return "", 200# La firma se comprueba en tu servidor.
# Elige Node.js o Python para ver un ejemplo.Asistentes de IA
Servidor MCP
Conecta Claude, ChatGPT o cualquier cliente del Model Context Protocol con CliniQ. Basta con la URL: el asistente abre CliniQ, una persona de administración entra, elige qué permisos le da y acepta. El asistente solo ve las herramientas de esos permisos.
POST https://actions.cliniq.es/mcp, «Streamable HTTP» sin sesión ni SSE: cada petición JSON-RPC 2.0 se responde con JSON.- Protocolo
2026-07-28(sin estado:server/discover,tools/listytools/call, con la versión en_metay las cabecerasMCP-Protocol-Version,Mcp-MethodyMcp-Name). Los clientes anteriores siguen funcionando coninitialize(2025-11-25,2025-06-18,2025-03-26y2024-11-05). - Autorización OAuth 2.1 de MCP: metadatos del recurso (RFC 9728) y del servidor (RFC 8414), PKCE
S256,resource(RFC 8707), clientes por Client ID Metadata Document o registro dinámico y tokens de refresco que rotan. Si falta un permiso,403 insufficient_scopepara volver a pedirlo. - Para clientes que solo admiten un token fijo valen las claves de API, con sus mismos límites.
- Si una herramienta falla (hueco ocupado, ventana cerrada…), el resultado llega con
isError: truepara que el modelo lo corrija. - Las conexiones se ven y se desconectan en Configuración → Integraciones y API → Aplicaciones conectadas.
| Herramienta | Permiso | Qué hace |
|---|---|---|
buscar_pacientes | patients:read | Busca por nombre, teléfono o email (paginado). |
ver_paciente | patients:read | Datos de contacto de una ficha. |
crear_paciente | patients:write | Alta mínima. |
listar_servicios | availability:readappointments:* | Servicios con duración y precio. |
huecos_libres | availability:read | Horas libres de un servicio un día. |
ver_citas | appointments:read | Citas entre dos fechas. |
pedir_cita | appointments:write | Solicitud de cita en un hueco libre. |
listar_conversaciones | conversations:read | Bandeja de entrada. |
leer_mensajes | conversations:read | Mensajes de una conversación. |
enviar_mensaje | messages:write | Texto dentro de la ventana de 24 h. |
ver_embudos | deals:read | Embudos con sus etapas. |
ver_tratos | deals:read | Tratos de un embudo. |
crear_trato | deals:write | Crea un trato. |
mover_trato | deals:write | Cambia un trato de etapa. |
# OAuth: se abre CliniQ para entrar y elegir los permisos
claude mcp add --transport http cliniq https://actions.cliniq.es/mcp
# Clientes sin OAuth: con una clave de API
claude mcp add --transport http cliniq https://actions.cliniq.es/mcp \
--header "Authorization: Bearer $CLINIQ_API_KEY"curl -s https://actions.cliniq.es/mcp \
-H "Authorization: Bearer $CLINIQ_API_KEY" \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/call" \
-H "Mcp-Name: huecos_libres" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "huecos_libres",
"arguments": { "serviceId": "j57a9c2e4g6i8k0m2o4q6s8u", "date": "2026-11-12" },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'