Skip to main content
Las citas son consultas agendadas. Crea una reserva y, cuando la consulta se realiza, se enlaza a la cita automáticamente, de modo que la reserva pasa de booked a fulfilled por sí sola. Cada reserva lleva dos ids: el id público apt_... que devolvemos, y el consultationInternalId que tú eliges — tu propio id de la consulta, y la clave que enlaza la reserva con la visita.
Las citas están acotadas por la institución de tu clave API. Una clave de doctor o institutional puede agendar y actualizar; el alcance se aplica en el servidor, así que nunca pasas un id de cuenta o institución. Las escrituras necesitan scribe:write y las lecturas scribe:read.

​
Agendar una cita

POST /v1/appointments requiere consultationInternalId y un paciente. Referencia a un paciente existente por patientId (sp_...) o internalCode, o envía la identidad en línea (name, idCountry, idType, idValue) para crearlo. Campos de agenda opcionales: start, end, minutesDuration, serviceType, appointmentType, reason, description. Reenviar el mismo consultationInternalId actualiza la reserva en el sitio (idempotente), siempre que reenvíes con la llave dueña de la cita o con la llave que la creó. Una cita nueva empieza como booked.

​
A qué agenda entra la cita

Una cita pertenece a una sola cuenta, y solo esa cuenta la ve. Por defecto la cita entra en la agenda de la llave que la creó, así que una llave de doctor no necesita nada más. Una llave institucional agrega doctorId para agendar para uno de sus doctores: un id público de cuenta (acc_...) o tu propio internalCode para esa cuenta. El doctor ve la cita, y también la llave institucional que la creó. Una llave de doctor no puede agendar en la agenda de otro doctor. La agenda queda fija al crear la cita. Reenviar el mismo consultationInternalId con otro doctorId actualiza los horarios y el detalle clínico, y deja la cita donde está. Para mover una cita a otro doctor, cancélala y crea una nueva. Una llave que no es dueña de la cita ni la creó no puede reenviarla, y recibe 403. Si tu institución agenda con más de una llave, reenvía cada cita con la llave que la creó.
Respuesta:
Opcionalmente adjunta una plantilla — medicalRecordConfigurationId (mrc_...). Cuando está presente, el contexto de consulta del médico se prepara con antelación, de modo que está listo antes de la visita. Usa scribeSessionModality (IN_PERSON, TELEMEDICINE o DICTATION) para registrar cómo ocurre la consulta; solo surte efecto cuando se adjunta una plantilla.

​
Listar citas

GET /v1/appointments devuelve la agenda visible para tu clave, ordenada por hora de inicio. Filtra por un rango de hora de inicio (startFrom, startTo), uno o más valores de status (repetible), o un consultationInternalId. Pagina con page (base 1) y limit (1–50, por defecto 20).
Respuesta:
total y totalPages solo se calculan en la primera página — son null en las páginas siguientes para evitar un escaneo completo en cada clic. Usa hasMore para paginar de forma fiable; es preciso en todas las páginas.

​
Consultar una cita

GET /v1/appointments/{appointment_id} busca una única cita. El {appointment_id} puede ser el id público (apt_...) o el consultationInternalId que enviaste al crearla. Devuelve 404 si ninguna cita con ese id es visible para tu clave.
Respuesta:

​
Actualizar una cita

PATCH /v1/appointments/{appointment_id} cancela una reserva o la marca como ausencia, por su id público (apt_...) o consultationInternalId. Define status como cancelled o noshow — fulfilled lo define solo el servidor cuando la consulta se realiza. Envía exactamente uno de status o scribeSessionId. Devuelve 404 si ninguna cita con ese id es visible para tu clave.
Respuesta:
Para reparar una reserva cuya sesión no se enlazó automáticamente al crearla, envía scribeSessionId (el id ss_... de la sesión) en lugar de status. Adjunta la sesión y marca la reserva como fulfilled. Esto solo aplica a una reserva agendada y sin enlazar; cualquier otro caso devuelve 409.