La API de CarelyCloud.

Autenticación

Un administrador crea las claves en Ajustes → Integraciones. La clave se muestra una sola vez. Mándala en cada petición en la cabecera X-API-Key.

curl https://carelycloud-production.up.railway.app/clinics/me \
  -H "X-API-Key: cc_live_xxxxxxxxxxxxxxxxxxxx"

La clave actúa en nombre de la clínica, no de una persona, y solo alcanza una parte de la API:

• Lectura: citas, pacientes (con notas y archivos), profesionales, disponibilidad, servicios, el perfil de la clínica y las métricas del inicio.
• Escritura: citas y pacientes, incluidas sus notas y archivos.
• Todo lo demás (equipo, ajustes, facturación, integraciones, notas con IA) responde 403 API_KEY_SCOPE.

El acceso se comprueba en cada petición contra el plan de la clínica. Cuando una prueba termina o una suscripción se suspende, todas las claves responden 402 de inmediato, sin revocar nada a mano. Revocar una clave en Ajustes aplica en la siguiente petición.

Convenciones

• URL base: https://carelycloud-production.up.railway.app
• JSON de entrada y de salida. Manda Content-Type: application/json en las escrituras.
• Las fechas son ISO 8601 con zona horaria. Guardamos en UTC; manda el desfase que quieras y lo convertimos. Los huecos vuelven en la zona horaria de la clínica.
• Las listas paginadas aceptan page (desde 1) y limit. GET /appointments sin page devuelve todo el rango.
• Los errores son JSON con un código estable, un mensaje y detalles opcionales:

{ "code": "SLOT_TAKEN", "message": "SLOT_TAKEN", "details": null }

Citas

Filtra por rango (start, end), profesional, paciente, estado o texto libre (q). Sin rango devuelve todo, así que manda uno.

curl "https://carelycloud-production.up.railway.app/appointments?start=2026-09-15T00:00:00Z&end=2026-09-15T23:59:59Z&doctor_id=3" \
  -H "X-API-Key: cc_live_..."

Crear una cita pasa por las mismas reglas que la aplicación. El profesional es obligatorio, y el hueco tiene que estar dentro de su horario y libre:

curl -X POST https://carelycloud-production.up.railway.app/appointments \
  -H "X-API-Key: cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "doctor_id": 3,
    "service_id": 1,
    "patient_id": 42,
    "start_at": "2026-09-15T15:00:00Z",
    "end_at":   "2026-09-15T15:30:00Z",
    "status":   "confirmed",
    "channel":  "manual",
    "notes":    "Booked from our CRM"
  }'

Los cambios de estado van por PATCH. Transiciones permitidas: scheduled → confirmed | cancelled | no_show; confirmed → completed | cancelled | no_show. Completed, cancelled y no_show son finales. DELETE es un atajo para cancelar.

curl -X PATCH https://carelycloud-production.up.railway.app/appointments/981 \
  -H "X-API-Key: cc_live_..." -H "Content-Type: application/json" \
  -d '{ "status": "cancelled", "cancel_reason": "Patient called" }'

Pacientes

Crear un paciente busca posibles duplicados por teléfono o correo y responde 409 con las coincidencias; manda force=true para crearlo igual.

curl -X POST "https://carelycloud-production.up.railway.app/patients?force=false" \
  -H "X-API-Key: cc_live_..." -H "Content-Type: application/json" \
  -d '{
    "first_name": "Marta",
    "last_name":  "Ríos",
    "phone":      "+50499990000",
    "email":      "marta@example.com",
    "birth_date": "1992-04-12",
    "gender":     "female",
    "preferred_channel": "whatsapp"
  }'

La búsqueda cubre nombre, teléfono y correo. Paginación de 20 por página por defecto, 500 como máximo.

curl "https://carelycloud-production.up.railway.app/patients?q=marta&page=1&limit=20" -H "X-API-Key: cc_live_..."

Profesionales, disponibilidad y servicios

Solo lectura. Los profesionales y los servicios se administran desde la aplicación.

curl "https://carelycloud-production.up.railway.app/doctors/3/slots?date=2026-09-15&service_id=1" -H "X-API-Key: cc_live_..."

[
  { "start_at": "2026-09-15T15:00:00-06:00", "end_at": "2026-09-15T15:30:00-06:00", "available": true },
  { "start_at": "2026-09-15T15:15:00-06:00", "end_at": "2026-09-15T15:45:00-06:00", "available": false }
]

Webhooks

Un administrador registra una URL https en Ajustes → Integraciones y elige los eventos. Hacemos POST de cada uno cuando ocurre, una vez, con 8 segundos de espera. Sin reintentos: si tu endpoint está caído, la entrega queda como fallida en el registro y puedes reconstruir desde la API.

Cada entrega lleva el nombre del evento y una firma HMAC-SHA256 del cuerpo, con el secreto que se mostró una vez al crear el endpoint:

POST https://your-server.example.com/carelycloud
Content-Type: application/json
X-CarelyCloud-Event: appointment.confirmed
X-CarelyCloud-Signature: sha256=3f1a...

{
  "event": "appointment.confirmed",
  "created_at": "2026-09-15T14:02:11.480Z",
  "data": {
    "id": 981, "clinic_id": 6, "doctor_id": 3, "service_id": 1, "patient_id": 42,
    "start_at": "2026-09-15T15:00:00Z", "end_at": "2026-09-15T15:30:00Z",
    "status": "confirmed", "channel": "online"
  }
}

Verifica la firma antes de confiar en el contenido. Compara con una función de tiempo constante:

# Python
import hmac, hashlib
def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

// Node
const crypto = require("crypto")
function verify(secret, rawBody, header) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))
}

• Solo URLs https en hosts públicos. No se siguen redirecciones.
• Responde 2xx en menos de 8 segundos; haz el trabajo después.
• El registro guarda las últimas 100 entregas por endpoint, con estado y duración.
• El botón Probar en Ajustes manda un evento de ejemplo para revisar tu endpoint antes de salir en vivo.

Zapier, n8n y Make

No necesitan una app nativa: un disparador por webhook más una acción HTTP cubren toda la API.

• Zapier: el disparador "Webhooks by Zapier · Catch Hook" recibe los eventos; la acción "Webhooks by Zapier · Custom Request" llama a la API con la cabecera X-API-Key.
• n8n: el nodo Webhook recibe los eventos; el nodo HTTP Request llama a la API. Usa una credencial Header Auth para la clave.
• Make: el módulo Custom Webhook recibe los eventos; el módulo HTTP llama a la API.

Primera automatización típica: patient.created → agregar el paciente a tu CRM; appointment.confirmed → avisar al grupo de Slack o WhatsApp de la clínica.

Errores