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

# Integraciones EHR/HIS

> Cómo conectar el EHR/HIS con MarIA para gestión de citas, directorios y autenticación de pacientes

Esta guía explica cómo conectar tu EHR/HIS con MarIA para que el agente pueda consultar beneficios y huecos, y crear o cancelar citas en tiempo real durante las llamadas entrantes de pacientes. Los webhooks de MarIA hacia tu HIS se firman con `webhookHmac`.

## Para quién

* Integradores del hospital/aseguradora (equipo de interoperabilidad)
* Producto que define el flujo de citas

## Flujos principales

### 1) Obtener beneficios/prestaciones (catálogo de motivos/consultas)

* Ruta: `webhooks > appointment.getBenefits`
* Entrada: `collectiveId` (ID del seguro para filtrar si es necesario), `centerId`, `serviceId`
* Uso: Prepara el catálogo para calcular huecos.

### 2) Obtener huecos disponibles

* Ruta: `webhooks > appointment.getSlots`
* Entrada: `benefitId`, `centerId`, `serviceId`, `collectiveId`, `fromDateEpoch`, …
* Uso: Presentar opciones a pacientes/operadores.

### 3) Crear cita

* Ruta: `webhooks > appointment.create`
* Entrada: `slot`, `patientId`, `benefitId`
* Salida: `appointmentId`, `status`

### 4) Cancelar cita

* Ruta: `webhooks > appointment.cancel`
* Entrada: `appointmentId`, `reason`

### 5) Marcar cita pendiente de reprogramación (WIP)

* Ruta: `webhooks > appointment.reschedulePending`

### 6) Listar citas de un paciente

* Ruta: `webhooks > appointment.getList`

### 7) Directorios

* `directory.centers` y `directory.professionals`

### 8) Autenticación/Onboarding de paciente

* `patient.authenticate` y `patient.onboard`

## Secuencia de solicitud y creación de cita (llamada entrante)

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User as Paciente (llamada entrante)
    participant MarIA as MarIA
    participant HIS as EHR/HIS

    User->>MarIA: "Quiero pedir una cita"
    MarIA-->>User: "¿En qué centro/servicio necesitas la cita?"
    User-->>MarIA: Centro y/o servicio
    MarIA->>HIS: webhook appointment.getBenefits (con contexto del usuario)
    HIS-->>MarIA: Lista de beneficios disponibles
    MarIA->>HIS: webhook appointment.getSlots (benefitId, centerId, serviceId,...)
    HIS-->>MarIA: Huecos disponibles
    MarIA-->>User: Propuesta de fechas/horas (opciones)
    User-->>MarIA: Selecciona fecha/hora concreta
    MarIA->>HIS: webhook appointment.create (slot, patientId, benefitId)
    HIS-->>MarIA: appointmentId / status
    MarIA-->>User: Cita confirmada por teléfono
```

## Ejemplos (ilustrativos)

<Info>
  Estas rutas son webhooks que MarIA invoca hacia tu HIS. Se muestran sólo para ilustrar los payloads esperados.
</Info>

### appointment.create (request de MarIA hacia tu HIS)

```json theme={null}
{
  "slot": {"start": "2025-09-01T09:00:00Z", "centerId": "H1", "serviceId": 12},
  "patientId": 4567,
  "benefitId": 789
}
```

Respuesta esperada:

```json theme={null}
{ "appointmentId": 12345, "status": "CONFIRMED" }
```

### appointment.getSlots

```json theme={null}
{
  "benefitId": 789,
  "centerId": "H1",
  "serviceId": 12,
  "collectiveId": 55,
  "fromDateEpoch": 1754006400000
}
```

## Recomendaciones de integración

* Responder siempre con `200` y cuerpo válido; usar 4xx para validaciones.
* Trazabilidad: incluir `appointmentId` y `patientId` en logs.
* Idempotencia para `appointment.create` usando un `requestId` si aplica.
* Timezones: usar UTC y formatos ISO 8601.

## Checklist de producción

* [ ] Entorno de preproducción con datos anonimizados.
* [ ] Monitoreo de latencia y tasa de error por endpoint.
* [ ] Retención/mascarado de PII en logs.