Saltar al contenido principal
Las citas son consultas agendadas. Crea una cita y, cuando se realiza la consulta, esta se vincula automáticamente a la cita, de modo que la cita pasa de booked a fulfilled por sí sola. Cada cita tiene dos ids: el id público apt_... que devolvemos y el consultationInternalId que tú eliges, que es tu propio id de la consulta y la clave que vincula la cita con la atención.
El acceso a las citas está limitado a la institución de tu API key. Una clave doctor o institutional puede agendar y actualizar citas; el alcance se aplica en el servidor, así que nunca envías un id de cuenta o de institución. Las escrituras requieren scribe:write y las lecturas, scribe:read.

Agendar una cita

POST /v1/appointments requiere consultationInternalId y un paciente. Referencia un paciente existente por patientId (sp_...) o internalCode, o envía los datos de identificación inline (name, idCountry, idType, idValue) para crearlo. Campos opcionales de agendamiento: start, end, minutesDuration, serviceType, appointmentType, reason, description. Volver a enviar el mismo consultationInternalId actualiza la cita existente (idempotente), siempre que lo hagas con la clave dueña de la cita o con la clave que la creó. Una cita nueva empieza en booked.

En qué agenda queda la cita

Una cita pertenece a una sola cuenta, y solo esa cuenta la ve. Por defecto, la cita queda en la agenda de la clave que la creó, así que una clave de médico no necesita nada adicional. Una clave institucional agrega doctorId para agendar a nombre de uno de sus médicos: un id público de cuenta (acc_...) o tu propio internalCode para esa cuenta. Así, el médico ve la cita, y también la clave institucional que la creó. Una clave de médico no puede agendar en la agenda de otro médico. La agenda queda fija al crear la cita. Volver a enviar el mismo consultationInternalId con otro doctorId actualiza los horarios y el detalle clínico, pero deja la cita en la misma agenda. Para pasar una cita a otro médico, cancélala y crea una nueva. Una clave que no es dueña de la cita ni la creó no puede volver a enviarla y recibe 403. Si tu institución agenda con más de una clave, vuelve a enviar cada cita con la clave que la creó.
Respuesta:
Opcionalmente, adjunta una plantilla: medicalRecordConfigurationId (mrc_...). Si está presente, la plantilla se guarda en la cita y se devuelve en cada lectura, de modo que la agenda del médico abre la cita con esa plantilla y el contexto de la consulta del médico queda precargado con antelación. Define scribeSessionModality (IN_PERSON, TELEMEDICINE o DICTATION) para registrar la modalidad de la consulta. Se guarda en la cita y se devuelve en cada lectura, de modo que una cita TELEMEDICINE inicia como teleconsulta en Scribe, tenga o no una plantilla adjunta.

Listar citas

GET /v1/appointments devuelve la agenda visible para tu API key, ordenada por hora de inicio. Filtra por un rango de hora de inicio (startFrom, startTo), por uno o más valores de status (repetible) o por 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 recorrido completo en cada cambio de página. Usa hasMore para paginar de forma confiable; es exacto 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 tu API key no tiene visibilidad sobre ninguna cita con ese id.
Respuesta:

Actualizar una cita

PATCH /v1/appointments/{appointment_id} cancela una cita o la marca como inasistencia, usando su id público (apt_...) o su consultationInternalId. Define status como cancelled o noshow; fulfilled solo lo asigna el servidor cuando se realiza la consulta. Envía exactamente uno de los dos: status o scribeSessionId. Devuelve 404 si tu API key no tiene visibilidad sobre ninguna cita con ese id.
Respuesta:
Para corregir una cita cuya sesión no se vinculó automáticamente al crearla, envía scribeSessionId (el id ss_... de la sesión) en lugar de status. Esto vincula la sesión y marca la cita como fulfilled. Solo aplica a una cita en estado booked sin sesión vinculada; cualquier otro caso devuelve 409.