Catálogo

El catálogo de Agenda es cómo está configurada la clínica: los servicios que ofrece, las ofertas que hacen que cada uno se pueda agendar, los recursos que los prestan, las sedes donde están y el horario en que trabaja cada recurso. La disponibilidad se calcula a partir de él, así que un cambio aquí cambia los horarios que los pacientes pueden agendar.

Quién puede leerlo y cambiarlo

Leer el catálogo está abierto a personas y máquinas que tengan el permiso (scope) :read de lo que listan, como agenda:services:read; una lista no acepta ningún otro scope. Cambiarlo acepta solo personas: un miembro con sesión iniciada cuyos roles le otorgan el scope :write, como agenda:services:write, normalmente a través de una herramienta del personal. Las API keys y los tokens de máquina no pueden cambiar el catálogo.

Las listas de servicios, ofertas, recursos y sedes responden una página a la vez, 25 elementos por defecto y hasta 100: consulta Paginación. Crear no es idempotente, así que después de una creación cuyo resultado se desconoce, lista antes de volver a crear. No hay ninguna operación para eliminar: pon el status de un registro en inactive para dejar de usarlo. Las operaciones de agendamiento solo ofrecen ofertas activas.

Servicios

Un servicio es lo que pide un paciente, con el nombre que le da la clínica, como una consulta de neurología. agenda.services.list filtra por status.

Ofertas

Una oferta vincula un servicio a una agenda, con lo que se necesita para agendarlo. agenda.offerings.list filtra por serviceId y status.

Cada requisito nombra un kind de recurso y una quantity, 1 por defecto. alternatives lista los recursos que pueden cumplirlo; cuando está vacío, puede cumplirlo cualquier recurso de ese tipo. required, true por defecto, dice si el requisito debe cumplirse para que el agendamiento siga adelante. En una actualización, resourceRequirements reemplaza toda la lista para los agendamientos futuros; las citas existentes conservan sus recursos.

Un cuerpo de ejemplo para agenda.offerings.create, una consulta de 30 minutos con un profesional determinado y cualquier sala:

{
  "serviceId": "svc_00000000-0000-4000-8000-000000000001",
  "name": "Consulta de neurología, Dr. Example",
  "durationMinutes": 30,
  "slotIntervalMinutes": 30,
  "minNoticeMinutes": 120,
  "resourceRequirements": [
    { "kind": "practitioner", "alternatives": ["srs_00000000-0000-4000-8000-000000000003"] },
    { "kind": "room" }
  ]
}

Recursos

Un recurso es cualquier cosa con su propio calendario que usa un agendamiento. agenda.resources.list filtra por kind y status.

Sedes

Las sedes (locations) de la clínica tienen cada una su name, address, city, timezone y status. La API las lee con agenda.locations.list (agenda:locations:read), o con agenda.bookingLocations.list cuando agendas (agenda:bookings:read). No tiene ninguna operación que cree o cambie una sede.

Reglas de horario

Las reglas de horario dicen cuándo trabaja un recurso. Cada regla es una franja de hora local, de from a to en formato HH:MM, leída en la zona horaria del recurso:

• agenda.scheduleRules.list filtra por resourceId y responde con la lista completa, sin páginas. Cada regla tiene su id, su resourceId y su version.
• agenda.scheduleRules.create añade una regla con resourceId, kind, timezone, from y to.
• agenda.scheduleRules.update cambia la regla identificada por scheduleRuleId; envía su expectedVersion. Sin ella se rechaza con SCHEDULE_RULE_EXPECTED_VERSION_REQUIRED.
• agenda.resourceSchedules.update reemplaza de una vez todo el horario del recurso: rules es el conjunto nuevo, de hasta 400 reglas, y expectedRules contiene el id y la version de cada regla que cargaste. Si el horario cambió desde entonces, el reemplazo se rechaza y nada cambia.

Un cuerpo de ejemplo para agenda.resourceSchedules.update: de lunes a viernes, de 07:00 a 12:00 y de 14:00 a 17:00, reemplazando una regla cargada en la versión 3:

{
  "expectedRules": [{ "id": "sch_00000000-0000-4000-8000-000000000006", "version": 3 }],
  "rules": [
    { "kind": "weekly", "weekdays": [1, 2, 3, 4, 5], "from": "07:00", "to": "12:00" },
    { "kind": "weekly", "weekdays": [1, 2, 3, 4, 5], "from": "14:00", "to": "17:00" }
  ]
}

Versiones

Cada registro del catálogo tiene una version. Una actualización requiere como expectedVersion la versión que leíste, y se rechaza con 409 cuando alguien cambió el registro desde entonces:

Vuelve a leer el registro, aplica tu cambio sobre lo que leíste y envíalo con la nueva versión. Consulta Manejar errores y reintentos.