Saltar al contenido
Docs
cliniq.esCrear una clave

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

URL basehttps://actions.cliniq.es/api/v1
Especificación OpenAPI 3.1 (pública)https://actions.cliniq.es/api/v1/openapi.json
Servidor MCPhttps://actions.cliniq.es/mcp
Tu primera petición
curl -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.

Petición autenticada
curl https://actions.cliniq.es/api/v1/services \
  -H "Authorization: Bearer cq_live_Zr8Qm2xKv7LpT4nW9sYb3HcJ6dFgA1eU"
Sin clave o revocada401 Unauthorized
{
  "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.

RecursoLecturaEscritura
Pacientespatients:readpatients:write
Citasappointments:readappointments:write
Huecos libresavailability:read—
Conversacionesconversations:readmessages:write
Tratosdeals:readdeals:write
Eventosevents:read—
PermisoQué permite
patients:readBuscar y ver pacientes (sin historial clínico)GET /patientsGET /patients/{id}
patients:writeCrear pacientesPOST /patients
appointments:readVer citasGET /servicesGET /appointments
appointments:writePedir citas (quedan pendientes de confirmar)GET /servicesPOST /appointments
availability:readVer servicios y huecos libresGET /servicesGET /availability
conversations:readVer conversaciones y mensajesGET /conversationsGET /conversations/{id}/messages
messages:writeEnviar mensajes (dentro de la ventana de 24 h)POST /conversations/{id}/messages
deals:readVer embudos y tratosGET /pipelinesGET /deals
deals:writeCrear y mover tratosPOST /dealsPATCH /deals/{id}
events:readVer 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
Permiso que falta403 Forbidden
{
  "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 /8 en IPv4 y /16 en 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.

Origen no permitido403 Forbidden
{
  "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"
  }
}
Clave caducada401 Unauthorized
{
  "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.

HTTPcodeCuándo
400BAD_REQUESTBAD_CURSOREntrada no válida: falta un campo, tipo incorrecto, fecha mal escrita, cursor de otra búsqueda… param dice el campo.
400BAD_VERSIONCliniQ-Version no es una versión de la API.
401UNAUTHORIZEDFalta la clave, está mal formada, no existe o está revocada.
401KEY_EXPIREDLa clave ha caducado, o era la anterior de una rotación y ya pasó el margen.
403FORBIDDENINSUFFICIENT_SCOPEMODULE_DISABLEDSUBSCRIPTION_INACTIVELa 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).
403IP_NOT_ALLOWEDLa clave tiene restricciones de origen y la petición no las cumple (IP, dominio, red o país).
404NOT_FOUNDNo existe o es de otra clínica.
405METHOD_NOT_ALLOWEDMétodo no admitido en esa ruta. La cabecera Allow dice cuáles.
409DUPLICATESLOT_TAKENWINDOW_CLOSEDConflicto con el estado actual: ficha repetida, hueco ocupado, ventana de 24 h cerrada…
409IDEMPOTENCY_IN_PROGRESSLa petición original con esa Idempotency-Key aún no ha terminado. Reintenta en unos segundos.
415UNSUPPORTED_MEDIA_TYPEEl cuerpo no es application/json.
422IDEMPOTENCY_KEY_REUSEDLa Idempotency-Key ya se usó con otro método, otra ruta u otro cuerpo.
429RATE_LIMITEDDemasiadas peticiones. Espera los segundos de Retry-After.
500SERVER_ERRORFallo de CliniQ. Reintenta con la misma Idempotency-Key; si se repite, pasa el requestId a soporte.
503IP_LOOKUP_FAILEDLa clave limita por país o por red y no se pudo comprobar la IP. Reintenta en unos segundos.

El objeto error

  • error.codestring

    Código estable del error, en mayúsculas.

  • error.messagestring

    Explicación en español. Puede cambiar: no la compares.

  • error.paramstring

    Si el error lo provoca un campo concreto, cuál: startAt, cursor, expand, Idempotency-Key…

  • error.requestIdstring

    El Request-Id de la petición. Dalo al pedir ayuda a soporte.

  • error.docUrlstring

    Enlace a la explicación del código en esta página.

  • error.duplicateIdstring

    Solo con DUPLICATE: id de la ficha que ya existe.

Error400 Bad Request
{
  "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.

Cabeceras de la respuesta
HTTP/1.1 200 OK
Cache-Control: no-store
CliniQ-Version: 2026-11-16
Content-Type: application/json
Request-Id: req_8fK2mQ7xLp4Tz9Wb3NcV

Idempotencia

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 (un 409 SLOT_TAKEN se repite igual). Los 5xx no: 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 GET se ignora: repetirlas ya no cambia nada.
Petición con Idempotency-Key
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",
    },
)
Reintento: respuesta repetida
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-Version con la versión aplicada.
  • Una versión que no existe da 400 BAD_VERSION.

Versiones2026-11-16

Fijar la versión en una petición
curl https://actions.cliniq.es/api/v1/patients \
  -H "Authorization: Bearer $CLINIQ_API_KEY" \
  -H "CliniQ-Version: 2026-11-16"
Versión desconocida400 Bad Request
{
  "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

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de la página anterior.

Recorrer todas las páginas
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:
        break

Expandir 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=patient o expand[]=patient.
  • patientId sigue ahí. patient es el objeto paciente, o null si no hay ficha o ya no existe.
  • Hace falta también el permiso patients:read. Sin él, 403 INSUFFICIENT_SCOPE con param: "expand".
  • Otro valor, o expand en otra ruta, da 400 BAD_REQUEST con param: "expand".
Citas con su paciente
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"
Respuesta200 OK
{
  "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_LIMITED con la cabecera Retry-After en segundos.
  • Cuerpos JSON de hasta 32 KB (64 KB en /mcp), con Content-Type: application/json; si no, 415.
  • Las escrituras se rechazan con 403 SUBSCRIPTION_INACTIVE si la suscripción de la clínica a CliniQ está impagada. Las lecturas siguen funcionando.
  • Las respuestas llevan Cache-Control: no-store, Request-Id y CliniQ-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.

Límite superado
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:00 o …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 }.
Ejemplo
{
  "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

  • idstring

    Identificador único.

  • firstNamestring

    Nombre.

  • lastNamestring

    Apellidos.

  • phonestring· puede ser null

    Teléfono en formato E.164.

  • emailstring· puede ser null

    Email.

  • birthDatestring· puede ser null

    Fecha de nacimiento (AAAA-MM-DD).

  • consentMarketingboolean

    Consiente comunicaciones comerciales.

  • whatsappOptInboolean

    Acepta recibir mensajes de WhatsApp.

  • sourcestring

    Por dónde se dio de alta la ficha.

    Valores:receptiononlineappwebimportapi

  • createdAttimestamp

    Fecha de alta.

El objeto paciente
{
  "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

  • searchstring

    Nombre, teléfono o email. Hasta 200 caracteres.

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de 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_CURSOR El cursor es de otra búsqueda
GET/v1/patients
curl -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()
Respuesta200 OK
{
  "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

  • idstringobligatorio

    Id de la paciente.

Devuelve

El objeto paciente. 404 NOT_FOUND si no existe o es de otra clínica.

GET/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"]
Respuesta200 OK
{
  "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)

  • firstNamestringobligatorio

    Nombre. Hasta 200 caracteres.

  • lastNamestring

    Apellidos. Hasta 200 caracteres.

  • phonestring

    Teléfono. Se normaliza a E.164; sin prefijo se entiende de España.

  • emailstring

    Email.

  • consentMarketingboolean

    Consiente comunicaciones comerciales.

  • whatsappOptInboolean

    Acepta recibir mensajes de WhatsApp. Exige phone.

Devuelve

El objeto paciente creado, con estado 201.

Errores propios

  • 409 DUPLICATE Ya hay una ficha con ese teléfono o email (devuelve duplicateId)
POST/v1/patients
curl -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"]
Respuesta201 Created
{
  "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.

El objeto servicio

Atributos

  • idstring

    Identificador único.

  • namestring

    Nombre.

  • descriptionstring· puede ser null

    Descripción.

  • durationMinutesinteger

    Duración en minutos.

  • priceCentsinteger

    Precio en céntimos de euro.

  • onlineBookableboolean

    Si se puede reservar online (y, por tanto, pedir por la API).

El objeto servicio
{
  "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.

GET/v1/services
curl 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"]
Respuesta200 OK
{
  "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.

El objeto disponibilidad

Atributos

  • datestring

    Día consultado.

  • serviceIdstring

    Id del servicio.

  • durationMinutesinteger

    Duración del servicio en minutos.

  • slotsobject[]

    Horas libres, por orden.

    Atributos
    • startAttimestamp

      Inicio del hueco.

    • staffIdsstring[]

      Profesionales libres a esa hora.

El objeto disponibilidad
{
  "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

  • serviceIdstringobligatorio

    Id del servicio.

  • datestringobligatorio

    Día, AAAA-MM-DD (hora de Madrid).

  • staffIdstring

    Solo los huecos de esta profesional.

Devuelve

El objeto disponibilidad del día.

GET/v1/availability
curl -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"]
Respuesta200 OK
{
  "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

  • idstring

    Identificador único.

  • startAttimestamp

    Inicio.

  • endAttimestamp

    Fin.

  • statusstring

    Estado de la cita.

    Valores:requestedpending_paymentscheduledconfirmedarrivedin_progresscompletedno_showcancelled

  • sourcestring

    Origen: la agenda (staff), la reserva online o la API (online), el área de clientes (app) o una importación.

    Valores:staffonlineappimport

  • patientIdstring· puede ser null

    Id de la paciente.

  • staffIdstring

    Id de la profesional.

  • staffNamestring· puede ser null

    Nombre de la profesional.

  • servicesobject[]

    Servicios de la cita.

    Atributos
    • idstring

      Id del servicio.

    • namestring

      Nombre.

    • durationMinutesinteger

      Duración en minutos.

    • priceCentsinteger

      Precio en céntimos.

  • patientobject· puede ser null

    Solo con expand=patient: el objeto paciente de patientId, o null si no hay ficha o ya no existe.

El objeto cita
{
  "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

  • fromstring

    Desde (AAAA-MM-DD o ISO 8601 con zona). Por defecto, ahora.

  • tostring

    Hasta (AAAA-MM-DD o ISO 8601 con zona). Por defecto, 30 días después.

  • patientIdstring

    Solo las citas de esta paciente.

  • expandstring | string[]

    patient añade la ficha de la paciente en patient. Necesita también patients:read. Vale expand=patient o expand[]=patient.

    Valores:patient

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de la página anterior, para pedir la siguiente.

Devuelve

Una lista de objetos cita.

GET/v1/appointments
curl -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()
Respuesta200 OK
{
  "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)

  • patientIdstringobligatorio

    Id de la paciente.

  • serviceIdstringobligatorio

    Id de un servicio reservable online.

  • startAtstring | integerobligatorio

    Inicio de un hueco que dé /availability. ISO 8601 con zona o milisegundos.

  • staffIdstring

    Profesional. Sin ella, cualquiera que esté libre.

Devuelve

El objeto cita, con status: "requested" y estado 201.

Errores propios

  • 409 SLOT_TAKEN La hora ya está ocupada o no es un hueco ofrecido
POST/v1/appointments
curl -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"]
Respuesta201 Created
{
  "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.

El objeto conversación

Atributos

  • idstring

    Identificador único.

  • channelstring

    Canal.

    Valores:whatsappinstagrammessenger

  • statusstring

    Estado.

    Valores:openclosed

  • patientIdstring· puede ser null

    Id de la paciente, si la conversación está enlazada.

  • contactNamestring· puede ser null

    Nombre del contacto en el canal.

  • phonestring· puede ser null

    Teléfono (WhatsApp).

  • assignedStaffIdstring· puede ser null

    Persona del equipo asignada.

  • lastMessageAttimestamp

    Último mensaje, en cualquier sentido.

  • lastInboundAttimestamp· puede ser null

    Último mensaje de la paciente.

  • lastMessagePreviewstring

    Principio del último mensaje.

  • unreadinteger

    Mensajes sin leer.

  • windowOpenboolean

    Si se puede escribir texto libre: 24 h desde el último mensaje de la paciente.

  • windowExpiresAttimestamp· puede ser null

    Cuándo se cierra la ventana.

  • patientobject· puede ser null

    Solo con expand=patient: el objeto paciente de patientId, o null si no hay ficha o ya no existe.

El objeto conversación
{
  "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

  • statusstring

    Por defecto, open.

    Valores:openclosed

  • expandstring | string[]

    patient añade la ficha de la paciente en patient. Necesita también patients:read. Vale expand=patient o expand[]=patient.

    Valores:patient

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de la página anterior, para pedir la siguiente.

Devuelve

Una lista de objetos conversación.

GET/v1/conversations
curl -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()
Respuesta200 OK
{
  "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

  • idstring

    Identificador único.

  • directionstring

    Sentido.

    Valores:inout

  • authorstring

    Quién lo escribió. automatic: recordatorios, campañas y API; phone_app: la app WhatsApp Business del móvil.

    Valores:patientstaffaibotautomaticphone_app

  • kindstring

    Tipo (text, image, audio…).

  • bodystring

    Texto.

  • statusstring

    Estado de entrega.

    Valores:queuedsentdeliveredreadfailed

  • hasMediaboolean

    Si lleva un adjunto (la API no lo da).

  • createdAttimestamp

    Envío o recepción.

El objeto mensaje
{
  "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

  • idstringobligatorio

    Id de la conversación.

Parámetros de consulta

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de la página anterior, para pedir la siguiente.

Devuelve

Una lista de objetos mensaje.

GET/v1/conversations/{id}/messages
curl -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()
Respuesta200 OK
{
  "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

  • idstringobligatorio

    Id de la conversación.

Cuerpo (JSON)

  • textstringobligatorio

    Texto. 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_CLOSED Han pasado más de 24 h desde el último mensaje de la paciente
POST/v1/conversations/{id}/messages
curl -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"]
Respuesta201 Created
{
  "data": {
    "conversationId": "m97e5g7i9k1m3o5q7s9u1w3y",
    "id": "n58g7i9k1m3o5q7s9u1w3y5a",
    "status": "queued"
  }
}

RecursoNecesita el módulo CRM

Embudos

Los embudos del CRM con sus etapas, en orden.

El objeto embudo

Atributos

  • idstring

    Identificador único.

  • namestring

    Nombre.

  • stagesobject[]

    Etapas, en orden.

    Atributos
    • idstring

      Id de la etapa.

    • namestring

      Nombre.

    • wonboolean

      Si llegar a ella da el trato por ganado.

El objeto embudo
{
  "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.

GET/v1/pipelines
curl 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"]
Respuesta200 OK
{
  "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

  • idstring

    Identificador único.

  • titlestring

    Título.

  • patientIdstring

    Id de la paciente.

  • pipelineIdstring

    Id del embudo.

  • stageIdstring

    Id de la etapa.

  • stageNamestring· puede ser null

    Nombre de la etapa.

  • statusstring

    Estado.

    Valores:openwonlost

  • valueCentsinteger

    Valor en céntimos.

  • assignedStaffIdstring· puede ser null

    Persona del equipo asignada.

  • createdAttimestamp

    Alta.

  • stageChangedAttimestamp

    Último cambio de etapa.

  • closedAttimestamp· puede ser null

    Cuándo se ganó o se perdió.

  • patientobject· puede ser null

    Solo con expand=patient: el objeto paciente de patientId, o null si no hay ficha o ya no existe.

El objeto trato
{
  "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

  • pipelineIdstring

    Solo los de este embudo.

  • statusstring

    Solo los que tengan este estado.

    Valores:openwonlost

  • expandstring | string[]

    patient añade la ficha de la paciente en patient. Necesita también patients:read. Vale expand=patient o expand[]=patient.

    Valores:patient

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de la página anterior, para pedir la siguiente.

Devuelve

Una lista de objetos trato.

GET/v1/deals
curl -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()
Respuesta200 OK
{
  "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)

  • patientIdstringobligatorio

    Id de la paciente.

  • pipelineIdstringobligatorio

    Id del embudo.

  • titlestringobligatorio

    Título. Hasta 500 caracteres.

  • valueCentsinteger

    Valor en céntimos.

  • stageIdstring

    Etapa inicial. Por defecto, la primera.

Devuelve

El objeto trato creado, con estado 201.

POST/v1/deals
curl -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"]
Respuesta201 Created
{
  "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

  • idstringobligatorio

    Id del trato.

Cuerpo (JSON)

  • stageIdstring

    Etapa nueva.

  • titlestring

    Título.

  • valueCentsinteger

    Valor en céntimos.

Devuelve

El objeto trato actualizado.

PATCH/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"]
Respuesta200 OK
{
  "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

  • idstring

    Identificador único (evt_…). Es el mismo en el webhook y en sus reintentos y reenvíos.

  • typestring

    Tipo de evento.

    Valores:message.createdconversation.assignedconversation.closedappointment.createdappointment.updatedpatient.createdpayment.receiveddeal.stage_changed

  • createdAttimestamp

    Cuándo pasó.

  • dataobject

    Los datos del evento, iguales que en el webhook (ver «Tipos de evento»).

El objeto 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

  • typestring

    Solo los de este tipo.

    Valores:message.createdconversation.assignedconversation.closedappointment.createdappointment.updatedpatient.createdpayment.receiveddeal.stage_changed

  • limitinteger

    Elementos por página, de 1 a 100. Por defecto, 50.

  • cursorstring

    El nextCursor de la página anterior, para pedir la siguiente.

Devuelve

Una lista de objetos evento.

GET/v1/events
curl -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()
Respuesta200 OK
{
  "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

  • idstringobligatorio

    Id del evento (evt_…).

Devuelve

El objeto evento. 404 NOT_FOUND si no existe o tiene más de 30 días.

GET/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"]
Respuesta200 OK
{
  "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.

  1. En Configuración → Integraciones y API, crea un webhook con la URL, los eventos y una descripción. Como mucho, 10 por clínica.
  2. Guarda el secreto whsec_…: se enseña una sola vez (puedes generar otro con «Nuevo secreto»).
  3. Responde 2xx en menos de 10 s y verifica la firma de cada entrega.
  4. 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.

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"
}

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.

EventoCuándo y qué lleva en data
message.createdLlega un mensaje de la paciente por WhatsApp, Instagram o Messenger. Es el único evento con texto escrito por ella.messageIdconversationIdpatientIdchannelkindbodycreatedAt
conversation.assignedUna conversación se asigna, a mano o automáticamente.conversationIdpatientIdassignedStaffIdteamIdauto
conversation.closedAlguien del equipo cierra la conversación.conversationIdpatientIdchannelassignedStaffIdclosedByStaffId
appointment.createdCita nueva desde la agenda, la reserva online, el área de clientes, el asistente de IA o la API.appointmentIdpatientIdstaffIdserviceIdsstartAtendAtstatussource
appointment.updatedCambia 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.createdFicha nueva: recepción, reserva online, cuenta web o API.patientIdfirstNamelastNamephoneemailsource
payment.receivedCobro registrado en una factura (mostrador, Stripe, enlace de pago, saldo o tarjeta regalo). No con devoluciones ni importaciones.paymentIdinvoiceIdinvoiceNumberinvoiceStatusisDepositappointmentIdpatientIdamountCentsmethodpaidAt
deal.stage_changedUn 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.

data de appointment.updated
{
  "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 2xx en 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 id del evento (también en X-CliniQ-Delivery) es el mismo en todos los reintentos: úsalo para no procesar dos veces.
  • El orden de llegada no está garantizado: ordena por createdAt si 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).
Cabeceras de la entrega
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.

  1. Lee el cuerpo tal cual llega, sin parsearlo ni volver a serializarlo.
  2. Calcula el HMAC de t, un punto y el cuerpo, y compáralo con v1 en tiempo constante.
  3. Rechaza las firmas con t de hace más de 5 minutos, para evitar reenvíos.
Verificación
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/list y tools/call, con la versión en _meta y las cabeceras MCP-Protocol-Version, Mcp-Method y Mcp-Name). Los clientes anteriores siguen funcionando con initialize (2025-11-25, 2025-06-18, 2025-03-26 y 2024-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_scope para 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: true para que el modelo lo corrija.
  • Las conexiones se ven y se desconectan en Configuración → Integraciones y API → Aplicaciones conectadas.
HerramientaPermisoQué hace
buscar_pacientespatients:readBusca por nombre, teléfono o email (paginado).
ver_pacientepatients:readDatos de contacto de una ficha.
crear_pacientepatients:writeAlta mínima.
listar_serviciosavailability:readappointments:*Servicios con duración y precio.
huecos_libresavailability:readHoras libres de un servicio un día.
ver_citasappointments:readCitas entre dos fechas.
pedir_citaappointments:writeSolicitud de cita en un hueco libre.
listar_conversacionesconversations:readBandeja de entrada.
leer_mensajesconversations:readMensajes de una conversación.
enviar_mensajemessages:writeTexto dentro de la ventana de 24 h.
ver_embudosdeals:readEmbudos con sus etapas.
ver_tratosdeals:readTratos de un embudo.
crear_tratodeals:writeCrea un trato.
mover_tratodeals:writeCambia un trato de etapa.
Claude Code
# 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"
Llamar a una herramienta
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": {}
      }
    }
  }'