Agenda es el producto de agendamiento de Arbol: el calendario de la clínica. Sabe qué ofrece la clínica, quién y qué lo presta, dónde y en qué horario, y qué citas ya están agendadas. A partir de eso calcula los horarios que un paciente puede agendar, y lleva una lista de espera para los pacientes a los que todavía no puede ubicar. Cada organización tiene una Agenda.
Todo lo que hace Agenda está en la API bajo https://api.getarbol.com/v1/agenda/, operación por operación en la referencia de la API de Agenda. La página de cada operación ahí muestra su Scope (permiso), sus Credentials (las credenciales que acepta) y su Effect (efecto).
El modelo de agendamiento
La clínica configura un catálogo una vez y lo mantiene al día. Consulta Catálogo para ver cómo leerlo y cambiarlo.
| Concepto | Qué es | Ids |
|---|---|---|
| Servicio | Lo que pide un paciente, como una consulta de neurología o un electroencefalograma, con una duración por defecto. | svc_… |
| Oferta (offering) | Un servicio vinculado a una agenda: la duración de la cita, el intervalo entre horas de inicio, la antelación mínima y el horizonte de agendamiento, y los recursos que necesita cada cita. | off_… |
| Recurso | Cualquier cosa con su propio calendario: un profesional, una sala, un equipo y otros tipos. Cada uno tiene una capacidad y una zona horaria, y puede pertenecer a una sede. | srs_… |
| Sede (location) | Una sede de la clínica, con su dirección, su ciudad y su zona horaria. | loc_… |
| Regla de horario | Cuándo trabaja un recurso: un horario semanal, un cambio en una fecha, una ausencia o un bloqueo, en la hora local del recurso. | sch_… |
El kind de un recurso es practitioner, assistant, room, chair, equipment, location, team o generic. Las descripciones de los campos de la API a menudo llaman agenda a un recurso: las agendas de una oferta y los resourceIds de un cupo son recursos.
Disponibilidad
Agenda calcula los horarios libres cuando los pides. Para una oferta, lee las reglas de horario de los recursos que la oferta necesita y la capacidad que les queda, y responde con los horarios que se pueden agendar, del más cercano al más lejano. Cada uno es un cupo (slot):
| Campo | Significado |
|---|---|
startsAt, endsAt |
La cita visible, con un desfase horario explícito. |
timezone |
La zona horaria IANA que se usa para las fechas locales y el horario de trabajo, como America/Bogota. |
offeringId, resourceIds |
La oferta, y los recursos que usaría la cita. |
slotToken |
Un token firmado para esa hora exacta. Para agendar se envía sin cambios. |
Un cupo no se le guarda a nadie: hasta que se agenda, otro agendamiento puede tomarlo. Consulta Disponibilidad y agendamiento.
Citas y agendamiento
Una cita es un horario agendado para un paciente en uno o más recursos, con un id como eng_… y un status. La API llega a las citas a través de dos conjuntos de operaciones, hechos para distintos tipos de quien llama. Ambos trabajan sobre los mismos registros: una cita agendada con uno se lee con el otro con el mismo id.
| Agendamiento (bookings) | Citas (appointments) | |
|---|---|---|
| Hecho para | Agendar en nombre de un paciente: un agente de IA, una app para pacientes, otro sistema. | El calendario propio de la clínica: las herramientas del personal, y los sistemas que lo leen o hacen reportes sobre él. |
| Quién llama | Personas y máquinas (API keys y client credentials). | Lecturas: personas y máquinas. Crear, reprogramar y cambiar el estado: solo personas. |
| Permisos (scopes) | agenda:bookings:read, agenda:bookings:write |
agenda:appointments:read, agenda:appointments:write |
| Buscar citas | Las de un paciente, por número de documento: agenda.bookings.lookup |
Cualquiera, por rango de fechas, paciente, agenda o estado: agenda.appointments.list |
| Escrituras | Agendar, reprogramar dentro del mismo servicio, cancelar con un motivo | Crear, reprogramar, cambiar el estado |
| Qué responden agendar y reprogramar | La cita, con indicaciones para el paciente y un comprobante imprimible | La cita |
Las operaciones de agendamiento cubren todo el camino hasta una cita agendada: agenda.bookingOfferings.list, agenda.bookingLocations.list, agenda.bookingRequirements.get, agenda.nearestBookingSlots.list, agenda.bookingSlots.list, agenda.bookings.create, agenda.bookings.get, agenda.bookings.reschedule y agenda.bookings.cancel. Llevan las reglas de la clínica para agendar por un paciente: los datos de admisión que exige, los pagadores cuyos pacientes solo agenda el equipo de la clínica, y los servicios con una regla de edad.
Las operaciones de citas son la vista de la recepción. agenda.appointments.get y agenda.appointments.list leen cualquier cita de la organización. agenda.appointments.create, agenda.appointments.reschedule y agenda.appointments.changeStatus aceptan solo a una persona con sesión iniciada, no API keys ni tokens de máquina, y no se ofrecen en MCP. Crear requiere un idempotencyKey; reprogramar y cambiar el estado requieren la expectedVersion que leíste.
Si construyes para pacientes o con una API key, usa las operaciones de agendamiento. Si construyes una herramienta en la que el personal de la clínica inicia sesión, usa las de citas y las operaciones del catálogo.
La lista de espera
Cuando ningún horario le sirve al paciente, o solo el equipo de la clínica puede agendarlo, Agenda lleva una lista de espera para que el equipo actúe. agenda.waitlist.join agrega a un paciente, con su consentimiento, para un servicio, opcionalmente un profesional (resourceId) y sus fechas preferidas. Nunca agenda: dile al paciente que el equipo de la clínica lo contactará. Cada entrada tiene un reason:
reason |
Cuándo |
|---|---|
manual |
No había ningún horario adecuado y el paciente aceptó esperar. |
payer_review |
El pagador del paciente tiene la política de agendamiento staff_only: el equipo coordina y agenda. |
priority |
El paciente pidió una cita urgente: pasa la cita agendada como appointmentId para que el equipo pueda adelantarla. |
El status de una entrada es waiting, offered, booked, expired o cancelled, y su priority es normal o urgent. Unirse otra vez para el mismo paciente, servicio y motivo devuelve la misma entrada abierta. agenda.waitlist.list lista las entradas: primero las abiertas, las urgentes y luego las que llevan más tiempo esperando, y después las cerradas.
Permisos (scopes)
| Scope | Qué permite |
|---|---|
agenda:bookings:read |
Buscar servicios que se pueden agendar, sus requisitos y sus cupos, y las citas de un paciente. |
agenda:bookings:write |
Agendar, reprogramar y cancelar con las operaciones de agendamiento, y todas las lecturas de agendamiento. |
agenda:availability:read |
Buscar cupos con agenda.firstAvailability.get y agenda.availability.list. |
agenda:appointments:read, agenda:appointments:write |
Leer citas. El scope de escritura también lee, y le permite a una persona crear citas, reprogramarlas y cambiar su estado. |
agenda:services:…, agenda:offerings:…, agenda:resources:…, agenda:schedule-rules:… |
:read lista el catálogo; :write le permite a una persona cambiarlo. Una lista del catálogo acepta solo su scope :read. |
agenda:locations:read |
Listar las sedes con agenda.locations.list. |
agenda:waitlist:read, agenda:waitlist:write |
Leer la lista de espera. El scope de escritura también lee, y agrega pacientes a ella. |
Una API key lleva los scopes que se eligieron al crearla; el token de una persona cuenta un scope solo hasta donde sus roles lo otorgan. Consulta Autenticación.
Siguientes pasos
Disponibilidad y agendamiento
Busca cupos, revisa los requisitos, y agenda, reprograma o cancela.
Catálogo
Servicios, ofertas, recursos, sedes y reglas de horario.
Agendar una cita
Todo el flujo de agendamiento con curl.
Manejar errores y reintentos
Un agendamiento que agotó el tiempo de espera, un conflicto de versión, un 429.