|
Download documentation/M6_INTEGRACION_M1_HCE.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 13.3 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/M6_INTEGRACION_M1_HCE.md
- Command line
-
hf download hf://spaces/Modulo-6/api/documentation/M6_INTEGRACION_M1_HCE.md
-
curl -L -o M6_INTEGRACION_M1_HCE.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/M6_INTEGRACION_M1_HCE.md
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. | |