> ## 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.

# Introducción a la API de OlivIA

> Visión general de la API de OlivIA: canales, entornos, autenticación y convenciones de integración

La **API de OlivIA** permite que un sistema externo —un EHR/HIS, un CRM o tu propio backend— integre el seguimiento clínico por voz de Omniloy: inscribir pacientes en protocolos, consultar el resultado de cada llamada y recibir eventos en tiempo real.

## Dos canales

OlivIA opera en dos direcciones. La API se centra en la parte que un integrador necesita controlar y consultar:

* **Llamadas salientes — seguimiento.** Inscribes a un paciente en un protocolo y OlivIA lo llama para completar el **cuestionario de seguimiento**, con programación y reintentos automáticos. Se opera **desde la API**.
* **Llamadas entrantes — triaje.** Un número de teléfono se configura para que, cuando el paciente llame, OlivIA ejecute un **cuestionario de triaje**. La configuración del número se realiza **con el equipo de Omniloy**; los resultados llegan por los mismos endpoints de lectura y por webhooks.

### Flujo de seguimiento (saliente)

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant C as Tu sistema
  participant O as OlivIA
  participant P as Paciente
  C->>O: POST /v1/enrollments/enroll-patient
  O-->>C: 201 Enrollment (primera llamada programada)
  O->>P: Llamada de seguimiento (cuestionario)
  P-->>O: Respuestas
  O-->>C: webhook run.status_changed (completado)
  C->>O: GET /v1/protocol-runs/{runId} (respuestas + score)
```

### Flujo de triaje (entrante)

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant P as Paciente
  participant O as OlivIA
  participant C as Tu sistema
  P->>O: Llama al número de triaje
  O->>P: Ejecuta el cuestionario de triaje
  O-->>C: webhooks (session.start, question.answered, run.status_changed)
  C->>O: GET /v1/protocol-runs/{runId} (resultado del triaje)
```

## Entornos

| Entorno    | URL                            |
| ---------- | ------------------------------ |
| Producción | `https://{your-prod-endpoint}` |
| Staging    | `https://{your-dev-endpoint}`  |

Escribe a [soporte@omniloy.com](mailto:soporte@omniloy.com) para obtener tus credenciales y las URLs reales de tu tenant.

## URL base y versión

Todos los endpoints cuelgan del prefijo **`/v1`**. Por ejemplo:

```bash theme={null}
https://{your-prod-endpoint}/v1/protocols
```

## Autenticación

Todas las operaciones usan una **API key personal** como bearer token:

```
Authorization: Bearer oc_sk_...
```

Consulta la guía de [Autenticación](/olivia/es/api/auth).

## Formato de respuesta

Las respuestas correctas envuelven el contenido en `data`:

```json theme={null}
{ "data": { "id": "…" } }
```

Los listados añaden `pagination`:

```json theme={null}
{ "data": [ … ], "pagination": { "total": 128, "limit": 50, "offset": 0 } }
```

Cada respuesta incluye la cabecera `x-request-id`, útil para soporte y trazabilidad.

## Errores

Los errores usan un único envoltorio:

```json theme={null}
{ "error": { "code": "validation_error", "message": "Invalid request", "details": [] } }
```

| Código HTTP | Cuándo                                                                       |
| ----------- | ---------------------------------------------------------------------------- |
| `400`       | Petición inválida (`validation_error` con `details`)                         |
| `401`       | Falta la API key o no es válida                                              |
| `403`       | La key no tiene el rol necesario para la operación                           |
| `404`       | El recurso no existe o no pertenece a tu organización                        |
| `409`       | Conflicto de estado (p. ej. archivar un protocolo con inscripciones activas) |