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 agregadoctorId 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ó.
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).
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.
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.
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.