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.


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:

POST /auth/login
Content-Type: application/json

{ "email": "<cuenta-servicio-m1@...>", "password": "<...>" }

Respuesta 200:

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

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:

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)

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:

{
  "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 — infraestructura completa de M6 en el bus (los 5 eventos entrantes, no solo los de M1).
  • integrations/M10_integration.md — tutorial genérico del bus de eventos del Core.
  • 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.