---
title: "Cómo funciona Agenda"
description: "El modelo de agendamiento de Agenda, desde los servicios y los recursos hasta la disponibilidad, y cómo encajan las citas, el agendamiento y la lista de espera."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo funciona Agenda

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](/api/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](/developers/agenda/catalog/) 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](/developers/agenda/availability-and-booking/).

## 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`](/api/agenda/bookings/lookup/) | Cualquiera, por rango de fechas, paciente, agenda o estado: [`agenda.appointments.list`](/api/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`](/api/agenda/booking-offerings/list/), [`agenda.bookingLocations.list`](/api/agenda/booking-locations/list/), [`agenda.bookingRequirements.get`](/api/agenda/booking-requirements/get/), [`agenda.nearestBookingSlots.list`](/api/agenda/nearest-booking-slots/list/), [`agenda.bookingSlots.list`](/api/agenda/booking-slots/list/), [`agenda.bookings.create`](/api/agenda/bookings/create/), [`agenda.bookings.get`](/api/agenda/bookings/get/), [`agenda.bookings.reschedule`](/api/agenda/bookings/reschedule/) y [`agenda.bookings.cancel`](/api/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`](/api/agenda/appointments/get/) y [`agenda.appointments.list`](/api/agenda/appointments/list/) leen cualquier cita de la organización. [`agenda.appointments.create`](/api/agenda/appointments/create/), [`agenda.appointments.reschedule`](/api/agenda/appointments/reschedule/) y [`agenda.appointments.changeStatus`](/api/agenda/appointments/change-status/) aceptan solo a una persona con sesión iniciada, no API keys ni tokens de máquina, y no se ofrecen en [MCP](/developers/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](/developers/agenda/catalog/).

## 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`](/api/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`](/api/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`](/api/agenda/first-availability/get/) y [`agenda.availability.list`](/api/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`](/api/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](/developers/authentication/#permisos-scopes).

## 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.

Source: https://docs.getarbol.com/developers/agenda/index.mdx