> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Seguimiento (llamadas salientes)

> Inscribir pacientes en un protocolo y programar llamadas de seguimiento con cuestionario

El seguimiento es el flujo **saliente**: inscribes a un paciente en un protocolo y OlivIA lo llama para completar el cuestionario, aplicando la programación y los reintentos definidos en el protocolo.

## 1. Encuentra el protocolo

Necesitas la `protocol_key` (o el `id`) del protocolo en el que vas a inscribir.

```bash theme={null}
curl "https://{your-prod-endpoint}/v1/protocols?status=active" \
  -H "Authorization: Bearer oc_sk_..."
```

| Método   | Ruta                      | Uso                                                                                                          |
| -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `GET`    | `/v1/protocols`           | Lista protocolos. Query: `search`, `status` (`draft\|active\|archived`), `limit` (1–100, def. 50), `offset`. |
| `GET`    | `/v1/protocols/{idOrKey}` | Obtiene un protocolo por UUID o `protocol_key`, con su versión activa.                                       |
| `DELETE` | `/v1/protocols/{idOrKey}` | Archiva un protocolo. Requiere rol `integrator`/`admin`. Devuelve `409` si tiene inscripciones activas.      |

## 2. Inscribe al paciente

`POST /v1/enrollments/enroll-patient` crea (o reutiliza) el paciente por su teléfono, lo inscribe en el protocolo y programa la **primera llamada saliente**.

```bash theme={null}
curl -X POST "https://{your-prod-endpoint}/v1/enrollments/enroll-patient" \
  -H "Authorization: Bearer oc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+34612345678",
    "first_name": "Ana",
    "last_name": "García",
    "protocol_key": "seguimiento-epoc",
    "language": "es",
    "preferred_timezone": "Europe/Madrid",
    "custom_variable_values": { "medico": "Dra. Menéndez" }
  }'
```

Campos del cuerpo:

| Campo                                      | Requerido | Notas                                                                                                                        |
| ------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `phone`                                    | sí        | Formato E.164. Identifica y deduplica al paciente.                                                                           |
| `first_name`, `last_name`                  | sí        | Datos del paciente.                                                                                                          |
| `protocol_key` **o** `protocol_version_id` | sí        | Indica **exactamente uno**. Con `protocol_key` puedes añadir `version`; si lo omites, se usa la versión activa.              |
| `language`                                 | no        | Etiqueta BCP-47 (p. ej. `es`, `en`). Por defecto, el idioma del protocolo.                                                   |
| `preferred_timezone`                       | no        | Zona IANA para respetar las ventanas horarias.                                                                               |
| `started_at`                               | no        | Cuándo empieza el seguimiento (ISO 8601).                                                                                    |
| `freq_config`                              | no        | Sobrescribe parcialmente la programación de la versión (cadencia, ventana de reintentos, franjas, rango de fechas, máximos). |
| `custom_variable_values`                   | no        | Valores para las variables personalizadas del protocolo.                                                                     |

Respuesta `201`:

```json theme={null}
{
  "data": {
    "id": "…enrollmentId…",
    "patient_id": "…",
    "protocol_version_id": "…",
    "status": "active",
    "language": "es",
    "started_at": "2026-08-05T09:00:00Z",
    "freq_config": { },
    "custom_variable_values": { "medico": "Dra. Menéndez" }
  }
}
```

<Info>
  `enroll-patient` es **idempotente por diseño**: si el paciente ya tiene una inscripción activa equivalente, se reutiliza; si los datos cambian, la inscripción anterior se reemplaza en cascada. No necesitas cabecera de idempotencia.
</Info>

## 3. Programa cuestionarios adicionales (opcional)

Para lanzar otro cuestionario dentro de una inscripción existente:

```bash theme={null}
curl -X POST "https://{your-prod-endpoint}/v1/protocol-runs" \
  -H "Authorization: Bearer oc_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enrollment_id": "…",
    "scheduled_at": "2026-08-12T10:00:00Z",
    "language": "es"
  }'
```

## 4. Consulta el estado de la inscripción

```bash theme={null}
curl "https://{your-prod-endpoint}/v1/enrollments/{enrollmentId}" \
  -H "Authorization: Bearer oc_sk_..."
```

Devuelve la inscripción y sus `protocol_runs` (cada uno con su `questionnaire_status`). Para leer respuestas, transcripción y grabación de cada llamada, consulta [Resultados](/olivia/es/api/resultados).

## Programación (freq\_config)

La cadencia de las llamadas la define el protocolo mediante `freq_config`: cadencia base, ventana y número de reintentos, franjas u horarios permitidos, rango de fechas y zona horaria. Puedes sobrescribirla por inscripción enviando un `freq_config` parcial en `enroll-patient`. OlivIA calcula la primera llamada y reprograma los reintentos automáticamente.