> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Citas
> Agenda consultas y haz seguimiento por su id público estable
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ó.
```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/appointments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"consultationInternalId": "CONSULT-12345",
"patientId": "sp_a1b2c3d4e5f6g7h8",
"start": "2026-09-01T14:00:00.000Z",
"serviceType": "cardiology"
}'
```
**Respuesta:**
```json theme={null}
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "booked",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
```
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).
```bash theme={null}
curl "https://scribe-api.telepatia.ai/v1/appointments?startFrom=2026-09-01T00:00:00.000Z&status=booked&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Respuesta:**
```json theme={null}
{
"items": [
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "booked",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3,
"hasMore": true
}
```
`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.
```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/appointments/apt_a1b2c3d4e5f6g7h8 \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Respuesta:**
```json theme={null}
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "booked",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
```
## 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.
```bash theme={null}
curl -X PATCH https://scribe-api.telepatia.ai/v1/appointments/apt_a1b2c3d4e5f6g7h8 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "cancelled"
}'
```
**Respuesta:**
```json theme={null}
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "cancelled",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
```
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`.