Introducción al módulo de Integraciones

Este módulo administra las llaves de API: la credencial que le permite a un sistema externo —un call center, un IVR telefónico, una aseguradora— hablar con BIAI Salud sin que una persona inicie sesión. Tiene dos pantallas: Llaves API y la Bandeja de errores, donde se revisan y reintentan los envíos fallidos hacia otros sistemas.

¿Qué resuelve este módulo?

• Emitir una llave para un sistema externo, con nombre, descripción y vencimiento opcional.
• Revocarla de inmediato si ya no se necesita o se sospecha que se filtró.
• Rotarla: cambiarla por una nueva sin borrar el registro ni perder el historial de uso.
• Auditar su uso: ver las últimas llamadas que hizo esa llave, con fecha, ruta, IP y resultado.

Qué puede hacer una llave hoy

Una llave de API no es una sesión de usuario: no ve pantallas ni navega el sistema. Sólo puede llamar a los endpoints públicos de integración, y hoy existe uno solo:

Función	Qué hace
Confirmar una cita	El sistema externo confirma, en nombre del paciente, una cita ya agendada — identificándolo por tipo y número de documento.

Una llave nace sin alcance elegido, y eso es a propósito. La pantalla de creación no pregunta "¿para qué la quiere?": la llave se emite con un alcance comodín que sirve para cualquier endpoint de integración que exista hoy o se agregue más adelante. En la práctica, mientras el catálogo de integraciones sea sólo "confirmar cita", una llave filtrada sólo puede confirmar citas — pero el día que se agregue una segunda función de integración, todas las llaves ya emitidas quedan habilitadas para ella sin que nadie tenga que volver a autorizarlas. Tenga esto presente al decidir a quién le entrega una llave.

Confirmar una cita por esta vía nunca genera un cobro ni una factura: si la cita tiene un valor pendiente a cargo del paciente (copago o cuota moderadora), el sistema la rechaza y remite al paciente a la institución. El cobro siempre se gestiona presencialmente, nunca por la API.

Cómo se custodia una llave, y qué pasa si se filtra

La llave completa se muestra una sola vez, en el instante en que se crea (o se rota): después de cerrar esa pantalla, BIAI Salud no la vuelve a mostrar en ningún lugar, ni siquiera a un superadministrador. Por eso:

• Entréguela por un canal seguro — nunca por correo sin cifrar ni por chat. Quien la va a usar debe guardarla como guarda cualquier contraseña de sistema: en un gestor de secretos, no en una nota.
• Si se pierde o se filtra, no se puede recuperar. La única salida es revocarla o rotarla desde este módulo — cualquiera de las dos deja inservible la llave anterior en el acto, sin período de gracia.
• Cada llamada queda auditada. La pestaña de llamadas de cada llave (ver Llaves API) muestra fecha, ruta, IP de origen y resultado — es lo primero que hay que revisar si sospecha de un uso indebido.

Acceso

• Menú: Integraciones > Llaves API y Integraciones > Bandeja de errores.
• Rutas: /integraciones/api-keys y /integraciones/bandeja-errores.

Cada pantalla tiene su propio permiso: integraciones.api-keys para las llaves (crear, revocar y rotar son acciones separadas dentro de ese mismo permiso) e integraciones.bandeja-errores para la bandeja.

Fuera de este módulo

La interoperabilidad con otros sistemas de salud (por ejemplo, el intercambio de historia clínica entre instituciones) es un frente aparte, que no tiene hoy una pantalla propia dentro de la plataforma: es trabajo de integración que coordina el equipo técnico de BIAI Salud directamente con la institución. Este módulo cubre las llaves de API de uso general y la bandeja donde se ven los envíos que fallaron.