api / documentation /M6_INTEGRACION_M1_HCE.md
juampisor's picture
Fix a integracion M7
2f4ab65
|
Raw History Blame Contribute Delete
13.3 kB
# Guía de integración: publicar eventos a Internación (M6) desde HCE (M1)
**Health Grid · Módulo 6 (Internación y Gestión de Camas) — para el equipo de Módulo 1**
> Esta guía es para el equipo de **HCE (M1)**: explica cómo publicar los eventos que le corresponden a M1 en el bus del Core (M10) para que M6 los procese. La cola y los eventos **ya están creados** en el Core — no hace falta dar de alta nada, solo publicar. Para el contrato genérico del bus (login, formato de mensajes) ver [`M10_integration.md`](integrations/M10_integration.md).
---
## 1. Qué le corresponde a M1
M1 tiene **dos** eventos hacia M6:
| `event_type_id` | `name` | Cuándo se dispara |
|---|---|---|
| **14** | `internacion.solicitud.creada` | Un médico solicita internar o trasladar un paciente |
| **15** | `internacion.alta-medica.registrada` | Un médico da el alta de un paciente internado |
Estos eventos reemplazan, en paralelo durante la transición, a los webhooks REST que M1 llama hoy: `POST /api/v1/webhooks/hce/solicitud` y `POST /api/v1/webhooks/hce/alta-medica`. **Esos endpoints REST siguen activos** — no hace falta migrar de un día para el otro; M1 puede seguir usándolos mientras integra la publicación por bus, y ambos caminos conviven hasta que se coordine el retiro del REST.
M6 ya tiene la cola `internacion.requests` creada y ambos eventos dados de alta y bindeados a esa cola. **M1 no necesita crear ninguna cola ni evento propio para esto** — solo necesita publicar.
### ⚠️ Cirugía urgente: queda fuera, sigue siendo solo REST
M1 tiene un tercer webhook hacia M6, `POST /api/v1/webhooks/hce/cirugia-urgente`, que **no tiene evento equivalente en el bus** y no lo va a tener por ahora. Ese endpoint responde sincrónicamente qué quirófano y reserva se asignaron (y qué reservas se desplazaron), algo que un mensaje fire-and-forget no puede resolver sin un canal de respuesta aparte. Migrarlo requeriría acordar con M6 un evento de respuesta (`correlation_id` + `response_event_id`, patrón `billing`/`appointments` de `M10_integration.md`), lo cual no está planificado todavía. **Seguí usando el REST directo para cirugía urgente.**
---
## 2. Prerrequisito: tu propia cuenta de servicio en el Core
M1 necesita su propia cuenta en el Core (M10) con permiso `events:log:publish`. Se loguea como cualquier otro cliente:
```http
POST /auth/login
Content-Type: application/json
{ "email": "<cuenta-servicio-m1@...>", "password": "<...>" }
```
Respuesta `200`:
```json
{ "token": "eyJhbGciOiJSUzI1NiIs...", "user": { "id": 8, "email": "...", ... } }
```
Guardar el `token` y usarlo como `Authorization: Bearer <token>` en la publicación (§3). El token del Core dura 24 h — renovar el login cuando expire.
---
## 3. Cómo publicar cada evento
### 3.1 Solicitud creada (`event_type_id: 14`)
Ejemplo de **internación**:
```http
POST /events/log
Authorization: Bearer <token de tu cuenta de servicio>
Content-Type: application/json
{
"event_type_id": 14,
"publisher_module": "hce",
"payload": "{\"tipo\":\"INTERNACION\",\"solicitud_hce_id\":\"HCE-SOL-00123\",\"paciente_id\":123,\"medico_solicitante_id\":10,\"origen\":\"GUARDIA\",\"diagnostico_ingreso\":\"Neumonía\",\"prioridad\":\"ALTA\",\"hospital_id\":\"HOSP-1\",\"timestamp\":\"2026-07-10T14:00:00Z\"}"
}
```
Ejemplo de **traslado**:
```http
POST /events/log
Authorization: Bearer <token de tu cuenta de servicio>
Content-Type: application/json
{
"event_type_id": 14,
"publisher_module": "hce",
"payload": "{\"tipo\":\"TRASLADO\",\"solicitud_hce_id\":\"HCE-SOL-00124\",\"paciente_id\":123,\"medico_solicitante_id\":10,\"cama_origen_id\":204,\"cama_destino_solicitada_id\":315,\"motivo_traslado\":\"Requiere UTI\",\"hospital_id\":\"HOSP-1\",\"timestamp\":\"2026-07-10T15:00:00Z\"}"
}
```
### 3.2 Alta médica registrada (`event_type_id: 15`)
```http
POST /events/log
Authorization: Bearer <token de tu cuenta de servicio>
Content-Type: application/json
{
"event_type_id": 15,
"publisher_module": "hce",
"payload": "{\"paciente_id\":123,\"medico_firmante_id\":10,\"tipo_alta\":\"ALTA_MEDICA\",\"timestamp\":\"2026-07-10T16:00:00Z\"}"
}
```
Notar: `payload` va **como string JSON** (no como objeto anidado) — es el formato que exige el Core para todo `POST /events/log`, no algo específico de M6.
Respuesta `201` en ambos casos:
```json
{
"id": 89,
"event_type_id": 15,
"publisher_module": "hce",
"payload": "...",
"status": "pending",
...
}
```
Con eso, el Core enruta el mensaje a `internacion.requests` (ya bindeado) y M6 lo procesa de forma asíncrona. No hay respuesta síncrona sobre el resultado del procesamiento — es fire-and-forget, igual que hoy son los webhooks REST.
---
## 4. Contrato de payload
### 4.1 `internacion.solicitud.creada` (id 14)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `tipo` | `INTERNACION` \| `TRASLADO` | **sí** | Determina qué otros campos importan (ver abajo). |
| `solicitud_hce_id` | string | **sí** | Id de la solicitud en M1. Es la clave de idempotencia — ver §5. |
| `paciente_id` | integer | **sí** | Id del paciente en el Core. |
| `medico_solicitante_id` | integer | **sí** | Id del médico que solicita. |
| `hospital_id` | string | no | Sede del hospital. |
| `observaciones` | string | no | Texto libre. |
| `timestamp` | string (ISO 8601, UTC) | **sí** | Momento de la solicitud. |
Campos específicos de `tipo=INTERNACION`:
| Campo | Tipo | Descripción |
|---|---|---|
| `cama_solicitada_id` | integer, opcional | Si el médico ya sugiere una cama puntual. |
| `origen` | `GUARDIA` \| `CIRUGIA_PROGRAMADA` | Origen del ingreso. Si es `CIRUGIA_PROGRAMADA`, M6 valida el turno contra M2 antes de aprobar — enviar también `turno_id`. |
| `turno_id` | integer, opcional | Requerido si `origen=CIRUGIA_PROGRAMADA`. |
| `diagnostico_ingreso` | string, opcional | |
| `obra_social_id` / `numero_afiliado` | string, opcional | |
| `prioridad` | `MUY_BAJA`\|`BAJA`\|`MEDIA`\|`ALTA`\|`MUY_ALTA`\|`URGENTE` | |
| `episodio_id` | integer | **Requerido para `tipo=INTERNACION`** (ver §4.3 — movido acá desde `alta-medica`, 2026-07). M1 lo crea al crear la solicitud, no en el alta. Si falta, M6 rechaza la aprobación de la solicitud (`400 ERROR_VALIDACION`) en vez de dejar que el evento a M7 salga con `idEpisodioExterno: null`. |
Para `tipo=TRASLADO`, `episodio_id` no se manda — es el mismo episodio ya abierto en la
cama origen; M6 lo hereda internamente (ver §5).
Campos específicos de `tipo=TRASLADO`:
| Campo | Tipo | Descripción |
|---|---|---|
| `cama_origen_id` | integer | Cama actual del paciente. |
| `cama_destino_solicitada_id` | integer, opcional | Cama sugerida como destino, si aplica. |
| `motivo_traslado` | string, opcional | |
El schema no rechaza combinaciones cruzadas (por ejemplo, mandar campos de `TRASLADO` con `tipo=INTERNACION` no da error) — enviar solo los campos relevantes al `tipo` real, los demás quedan en `null`.
### 4.2 `internacion.alta-medica.registrada` (id 15)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `paciente_id` | integer | **sí** | Paciente que recibe el alta. Tiene que tener una cama `OCUPADA` o `CODIGO_ROJO` asignada en M6. |
| `medico_firmante_id` | integer | **sí** | Médico que firma el alta. |
| `tipo_alta` | `ALTA_MEDICA`\|`ALTA_VOLUNTARIA`\|`TRASLADO_EXTERNO`\|`DEFUNCION` | **sí** | |
| `timestamp` | string (ISO 8601, UTC) | **sí** | Momento del alta. |
`episodio_id` **ya no viaja en este webhook** (ver §4.3 — corrección 2026-07): M6 lo obtiene
de la solicitud de internación, no del alta.
### 4.3 `episodio_id`: de dónde sale realmente (corrección 2026-07)
M7 (Facturación) confirmó su integración real con M6 y pide, para poder facturar,
`idEpisodioExterno` — el id del episodio clínico en M1.
**Historia:** originalmente se pidió este campo en `internacion.alta-medica.registrada`
(id 15), asumiendo que M1 podía mandarlo recién al cerrar el episodio. Se corrigió al
confirmar con el equipo de M1 el dominio real: **M1 crea el `episodio_id` al crear la
solicitud de internación, no al darla de alta.** Por eso el campo se movió a
`internacion.solicitud.creada` (id 14, ver §4.1) — requerido para `tipo=INTERNACION` — y
se retiró de `alta-medica`.
**Ciclo de vida en M6:**
- Se persiste en la propia `Solicitud` al recibir el webhook de solicitud.
- Al aprobar una `INTERNACION`, se copia a `Cama.episodio_id`.
- Al aprobar un `TRASLADO`, `Cama.episodio_id` se **hereda** de la cama origen (es el mismo
episodio del paciente, no uno nuevo) — M1 no necesita mandarlo en el evento de traslado.
- Cuando el paciente deja una cama (alta o traslado) y esa cama se libera de verdad
(`EN_LIMPIEZA → DISPONIBLE`), M6 limpia `episodio_id` de esa cama — no debe arrastrarse
al próximo paciente que la ocupe.
- El webhook de alta médica ya no toca `episodio_id`: el valor que viaja a M7 en
`facturacion.notify_cama_lista` es el que ya estaba cargado en la cama desde la
internación/traslado, sin pisarlo con el alta.
**Nota de tipo:** `episodio_id` es `integer` de este lado y M6 lo reenvía a M7 como número
JSON en `idEpisodioExterno`. El DTO real de M7 (`InternacionM6Request.idEpisodioExterno`)
lo tipa como `String`, pero Jackson coerciona un número a string sin problema del otro
lado — decisión tomada para mantener consistencia con `idPacienteExterno` (también
`integer`/`Long`), no por un requisito de M1.
Ver `M6_DISEÑO.md` §14 para el detalle completo del lado de M6.
---
## 5. Qué hace M6 al recibir cada evento
**Solicitud creada (14):**
1. Busca si ya existe una solicitud con ese `solicitud_hce_id`. Si existe, **no crea una nueva** — devuelve/usa la existente (idempotente: reintentar el mismo `solicitud_hce_id` es seguro, no duplica solicitudes).
2. Si no existe, crea la solicitud en estado `PENDIENTE`. Queda visible para un administrativo, que la resuelve (`APROBAR`/`APROBAR_CON_CAMBIO`/`RECHAZAR`) desde el frontend de M6 — este evento no dispara ninguna asignación de cama por sí solo.
3. Al resolverse (fuera de este flujo, por acción del administrativo), M6 le notifica el resultado a M1 vía `SOLICITUD_RESUELTA` — ese es un evento **saliente** de M6 hacia M1 (dual-write REST + bus, hoy con el lado bus todavía apagado porque M1 no compartió su `event_type_id` — ver `M6_EVENTOS_RABBITMQ.md` §7 si tu equipo quiere habilitar también ese canal).
**Alta médica (15):**
1. Busca la cama `OCUPADA`/`CODIGO_ROJO` del paciente. Si no tiene cama asignada, el mensaje se descarta (equivalente al `404` que hoy devuelve el REST) — no hay retry automático de M6 hacia M1.
2. La cama pasa a `EN_LIMPIEZA`, M6 notifica la baja a Monitoreo (M9) fire-and-forget, y dispara la notificación a Facturación (M7) con `episodio_id` ya cargado desde la internación/traslado (ver §4.3) — no depende de M1 en ese punto.
3. Cuando el personal de limpieza marca la cama como `DISPONIBLE`, M6 limpia `episodio_id`/`solicitud_hce_id`/`fecha_ingreso` de esa cama — no se arrastran al próximo paciente.
---
## 6. Errores comunes
| Síntoma | Causa probable |
|---|---|
| `401` al publicar | Token vencido o cuenta sin permiso `events:log:publish` |
| `400` al publicar | Falta `event_type_id` o `publisher_module` en el body de `POST /events/log` |
| Se publican dos solicitudes para el mismo caso | No debería pasar — si ambas tienen el mismo `solicitud_hce_id`, M6 es idempotente. Si usaste ids distintos para el mismo evento real, revisar cómo generás `solicitud_hce_id` de tu lado |
| El alta médica se publica (`201`) pero M6 nunca actúa | Verificar que el paciente tenga una cama `OCUPADA`/`CODIGO_ROJO` real en M6 — si la solicitud de internación original nunca se aprobó (o se resolvió por otra vía), no hay cama que dar de alta |
| Necesito la cirugía urgente por el bus | No está disponible — seguir usando `POST /api/v1/webhooks/hce/cirugia-urgente` (ver §1) |
---
## 7. Checklist de integración
- [ ] Cuenta de servicio de M1 en el Core, con permiso `events:log:publish`.
- [ ] Login (`POST /auth/login`) y manejo de renovación del token (24 h).
- [ ] Publicar `POST /events/log` con `event_type_id: 14` al crear una solicitud de internación o traslado, con `solicitud_hce_id` estable y único por solicitud.
- [ ] Enviar solo los campos relevantes al `tipo` (`INTERNACION` vs `TRASLADO`) en el payload de la solicitud.
- [ ] Publicar `POST /events/log` con `event_type_id: 15` al registrar un alta médica.
- [ ] Seguir usando el REST directo para cirugía urgente — no migra a este bus.
- [ ] Coordinar con el equipo de M6 cuándo dejar de llamar también a los REST directos (`/webhooks/hce/solicitud`, `/webhooks/hce/alta-medica`) — mientras tanto, no hay problema en llamar a ambos.
---
## 8. Referencias
- [`M6_EVENTOS_RABBITMQ.md`](M6_EVENTOS_RABBITMQ.md) — infraestructura completa de M6 en el bus (los 5 eventos entrantes, no solo los de M1).
- [`integrations/M10_integration.md`](integrations/M10_integration.md) — tutorial genérico del bus de eventos del Core.
- [`M6_DISEÑO.md`](M6_DISEÑO.md) §5.1/§5.2/§5.3 — flujos de negocio de internación, traslado y alta médica; §7.5 — contexto de la migración de webhooks REST a eventos.