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)

​

Flujo de triaje (entrante)

​

Entornos

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

Escribe a [e-mail] 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:

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.

​

Formato de respuesta

Las respuestas correctas envuelven el contenido en data:

{ "data": { "id": "…" } }

Los listados añaden pagination:

{ "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:

{ "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)