Las operaciones de agendamiento son la forma en que un sistema agenda por un paciente: un agente de IA en WhatsApp, una app para pacientes, una herramienta de call center. Encuentran qué ofrece la clínica y cuándo, dicen qué necesita saber la clínica, agendan el horario que eligió el paciente y, más adelante, lo mueven o lo cancelan. Personas y máquinas (API keys y client credentials) pueden llamar a todas. Para el flujo completo con curl, consulta Agendar una cita.
Las operaciones
| Operación | Solicitud | Efecto |
|---|---|---|
agenda.bookingOfferings.list |
GET /v1/agenda/booking-offerings |
Lee |
agenda.bookingLocations.list |
GET /v1/agenda/booking-locations |
Lee |
agenda.bookingRequirements.get |
GET /v1/agenda/booking-requirements |
Lee |
agenda.nearestBookingSlots.list |
GET /v1/agenda/nearest-booking-slots |
Lee |
agenda.bookingSlots.list |
GET /v1/agenda/booking-slots |
Lee |
agenda.bookings.create |
POST /v1/agenda/bookings |
Escribe; idempotente |
agenda.bookings.lookup |
POST /v1/agenda/bookings/lookup |
Lee |
agenda.bookings.get |
GET /v1/agenda/bookings/{appointmentId} |
Lee |
agenda.bookings.reschedule |
POST /v1/agenda/bookings/{appointmentId}/reschedule |
Escribe; no idempotente |
agenda.bookings.cancel |
POST /v1/agenda/bookings/{appointmentId}/cancel |
Elimina; idempotente |
Las lecturas aceptan agenda:bookings:read o agenda:bookings:write; las tres escrituras necesitan agenda:bookings:write. Cada operación también acepta channel y connectionId: los fija la plataforma y no cambian nada en Agenda, así que omítelos.
Encontrar qué agendar
agenda.bookingOfferings.list busca ofertas activas que se pueden agendar por q (el nombre de un servicio, como neurología), serviceId o locationId, 10 por página por defecto y como máximo 20. Busca el servicio que nombró el paciente en lugar de cargar todo el catálogo. Cada oferta lleva lo que debes revisar antes de ofrecer un horario:
| Campo | Significado |
|---|---|
id, serviceId |
La oferta y su servicio. |
durationMinutes, occupationMinutes |
Cuánto dura la cita, y cuánto tiempo se queda el paciente cuando es más largo, como en un estudio de 12 horas (si no, null). |
agendas, locations |
Los recursos que la prestan y sus sedes, con la dirección que hay que darle al paciente. |
scheduleSummary |
Su horario y sus cierres, en palabras. Lo que cuenta es la disponibilidad. |
service.eligibility |
Las edades que admite el servicio, minAgeYears y maxAgeYears, en años cumplidos el día de la cita; null para cualquier edad. |
service.bookingChecklist |
Requisitos para contrastar con lo que sabes del paciente antes de ofrecerle un cupo. |
service.patientInstructions |
Instrucciones de preparación y llegada para explicarle al paciente. |
Cuando aplica exactamente una sede, úsala sin pedirle al paciente que elija. Que un servicio aparezca en la lista no establece que el pagador del paciente lo cubra. agenda.bookingLocations.list lista las sedes, una página a la vez.
Revisar los requisitos
agenda.bookingRequirements.get responde con lo que la organización necesita para agendar:
| Campo | Qué dice |
|---|---|
fields |
Cómo se pide cada campo predefinido: off, optional o required para phone, email, payer, authorization y notes; optional o required para document; on u off para priority. |
customFields |
Los campos propios de la organización: key, label, type (text, number, date, select o checkbox), options y required. |
documentTypes |
Los códigos de tipo de documento que usa, como CC o TI. |
payers |
Sus pagadores activos. Cada uno tiene una bookingPolicy, open o staff_only, y sites, las sedes (IPS) que la clínica atiende con ese pagador: un paciente cuya sede no está en la lista no se atiende con él, y una lista vacía significa que no hay restricción. |
Pasa payerQuery con el nombre del pagador, tal como aparece en el carné del paciente, para dejar fuera los pagadores que no vienen al caso; que no haya coincidencias no establece la cobertura. Solo el equipo de la clínica agenda a los pacientes de un pagador staff_only: no los agendes; agrégalos a la lista de espera con el motivo payer_review a través de agenda.waitlist.join. Reutiliza lo que el paciente ya te dijo, y pide solo los valores obligatorios que falten o no estén claros.
Encontrar un cupo
Dos operaciones responden con cupos, del más cercano al más lejano, cada uno con un slotToken:
nearestBookingSlots.list |
bookingSlots.list |
|
|---|---|---|
| Busca | Un servicio, en todas las agendas que lo ofrecen | Una oferta, desde from hasta to |
| Requiere | serviceId, timezone |
offeringId, from, to, timezone |
| Se acota o se orienta con | locationId, resourceId, from, days |
preferredResourceIds, las agendas que se consideran primero |
| Responde | Hasta limit cupos: 20 por defecto, como máximo 50 |
Páginas de 25 por defecto, como máximo 100 |
| Continúa | Vuelve a llamar con from igual a nextFrom |
pageInfo.nextCursor |
timezone es la zona horaria IANA que se usa para leer las fechas locales y el horario de trabajo, como America/Bogota.
Para ofrecer el horario más cercano, llama a agenda.nearestBookingSlots.list con un limit de 1 a 3 y omite days: así busca en todo el plazo en que se puede agendar el servicio, de modo que un espacio libre a meses de distancia vuelve en una sola llamada. No pagines semana por semana. group: "offering" responde con los primeros cupos de cada oferta en lugar de los más cercanos en general. Un data vacío significa que no hay ningún espacio libre en ese alcance, y searchedUntil dice hasta dónde buscó: ofrece la lista de espera. truncatedOfferings: true significa que algunas agendas no se revisaron; acota la búsqueda con locationId o resourceId.
agenda.firstAvailability.get y agenda.availability.list responden con el mismo tipo de cupos a las credenciales con agenda:availability:read. También reciben durationMinutes, que se admite solo cuando la organización permite cambiar la duración, y occupationMinutes, una duración de estudio que ofrece la oferta.
Agendar
Agenda solo después de que el paciente confirme el horario de forma explícita. agenda.bookings.create recibe el slotToken exactamente como se devolvió:
| Campo | Significado |
|---|---|
slotToken |
Obligatorio. El cupo que confirmó el paciente. |
patient |
name, documentNumber y documentType, uno de los códigos de la organización (el primero si se omite). |
patientBirthDate |
YYYY-MM-DD, tal como la da el paciente. Necesaria cuando el servicio tiene una regla de edad. Nunca deduzcas la edad a partir de un nombre o un tipo de documento. |
intake |
phone, email, entity (el pagador, con el nombre que usa la clínica), authorization, notes, priority (normal o urgent) y fields, los campos personalizados por key. |
El agendamiento también crea o actualiza el registro del paciente, cuyo id vuelve como patientId. La respuesta es la cita, con:
guidance: las instrucciones del servicio para el paciente, si los pacientes se atienden por orden de llegada, quién lo atiende y la sede con su dirección. Cuéntaselo al paciente.slip: un enlace al comprobante imprimible de la cita en PDF, válido por una hora (expiresAt). Descárgalo justo después de agendar y envíale al paciente el archivo, nunca el enlace como texto: el enlace no necesita ninguna credencial.
Los errores que puede encontrar un agendamiento, y qué hacer con cada uno, están en Agendar una cita.
Reprogramar y cancelar
agenda.bookings.lookup busca a un paciente por el documentNumber exacto (y el documentType, cuando se conoce) y responde con sus citas, de la más reciente a la más antigua, cada una con su id, su startsAt, su status y sus agendas; las próximas también llevan guidance. found: false significa que ningún paciente tiene ese documento. Cuando varios pacientes comparten el número con tipos distintos, patients los lista y appointments viene vacío: pregunta cuál es y vuelve a llamar con documentType. agenda.bookings.get lee una cita por id, con sus indicaciones y su comprobante.
- Reprogramar. Busca un horario nuevo para el mismo servicio, pide al paciente que lo confirme y envía su
slotTokenaagenda.bookings.reschedule. Sirve otro profesional u otra sala de ese servicio; un cupo de otro servicio se rechaza conSERVICE_CHANGED. Conagenda.bookingSlots.list, pasa el id de la cita comoexcludeAppointmentIdpara que su horario actual no cuente como ocupado. - Cancelar. Una vez que la persona confirme cuál es la cita, envía el
reasonque dio aagenda.bookings.cancel. El motivo queda en el historial de la cita, y el cupo se libera.
Repeticiones seguras
| Operación | Efecto | Clave de idempotencia |
|---|---|---|
agenda.bookings.create |
Escribe; idempotente: repetirla con la misma entrada no tiene ningún efecto adicional. | Ninguna |
agenda.bookings.reschedule |
Escribe; no idempotente: una repetición puede volver a actuar. | Ninguna |
agenda.bookings.cancel |
Elimina; idempotente. | Ninguna |
agenda.waitlist.join |
Escribe; idempotente: el mismo paciente, servicio y motivo devuelven la misma entrada abierta. | Ninguna |
agenda.appointments.create |
Escribe. Solo personas. | idempotencyKey, obligatorio y único dentro de la organización: reutilizarlo devuelve la cita original. |
Las operaciones de agendamiento no reciben clave de idempotencia, así que cuando no se conoce el resultado de una escritura, revisa con agenda.bookings.lookup o agenda.bookings.get antes de repetirla. Consulta Reintentos y Manejar errores y reintentos.
Estados
El status de una cita es uno de tentative, scheduled, confirmed, checked_in, completed, cancelled, no_show o unknown.
- Cancelar libera el cupo. Las citas canceladas y completadas no recuperan capacidad con un cambio de estado.
- Una cita cancelada no se puede editar (
APPOINTMENT_CLOSED), una cerrada no se puede mover (APPOINTMENT_NOT_MOVABLE), y una cancelada no tiene comprobante:slipesnull. statusChangeregistra el último cambio de estado: cuándo, quién lo hizo y el motivo que dio.- El personal cambia un estado, por ejemplo a
confirmedono_show, conagenda.appointments.changeStatus. Acepta solo personas, aplica las transiciones permitidas y requiere laexpectedVersionque leyeron.
Las entradas de la lista de espera tienen sus propios estados: consulta La lista de espera.