api / documentation /M6_INTEGRACION_M2_TURNOS.md
juampisor's picture
Implementacion cola de eventos para informacion entrante de otros modulos.
9f05894
|
Raw History Blame Contribute Delete
6.47 kB

Guía de integración: publicar eventos a Internación (M6) desde Turnos (M2)

Health Grid · Módulo 6 (Internación y Gestión de Camas) — para el equipo de Módulo 2

Esta guía es para el equipo de Turnos (M2): explica cómo publicar el evento que le corresponde a M2 en el bus del Core (M10) para que M6 lo procese. La cola y el evento 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 M2

M2 solo tiene un evento hacia M6:

event_type_id name Cuándo se dispara
18 internacion.turno.cancelado Se cancela o reprograma un turno quirúrgico que M6 tiene reservado

Este evento reemplaza, en paralelo durante la transición, al webhook REST que M2 llama hoy: POST /api/v1/turnos/{turnoId}/cancelacion. Ese endpoint REST sigue activo — no hace falta migrar de un día para el otro; M2 puede seguir usándolo 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, el evento internacion.turno.cancelado (id 18) dado de alta y bindeado a esa cola. M2 no necesita crear ninguna cola ni evento propio para esto — solo necesita publicar.


2. Prerrequisito: tu propia cuenta de servicio en el Core

M2 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-m2@...>", "password": "<...>" }

Respuesta 200:

{ "token": "eyJhbGciOiJSUzI1NiIs...", "user": { "id": 12, "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 (mismo patrón que ya usás para tus otras integraciones contra M10).


3. Cómo publicar el evento

POST /events/log
Authorization: Bearer <token de tu cuenta de servicio>
Content-Type: application/json

{
  "event_type_id": 18,
  "publisher_module": "turnos",
  "payload": "{\"turno_id\":5501,\"motivo\":\"Paciente cancela el turno\",\"tipo_cancelacion\":\"CANCELACION_PACIENTE\",\"timestamp\":\"2026-07-10T14: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:

{
  "id": 90,
  "event_type_id": 18,
  "publisher_module": "turnos",
  "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 es el webhook REST.


4. Contrato del payload (internacion.turno.cancelado)

Campo Tipo Obligatorio Descripción
turno_id integer sí Id del turno cancelado en M2. Importante: en el webhook REST este valor viaja en la URL (/turnos/{turnoId}/cancelacion); acá no hay "URL", así que tiene que ir en el payload — es el campo que M6 usa para encontrar la reserva de quirófano asociada.
motivo string sí Motivo de la cancelación. Texto libre.
tipo_cancelacion string no Opcional, texto libre (ej. CANCELACION_PACIENTE, REPROGRAMACION).
timestamp string (ISO 8601, UTC) sí Momento de la cancelación en M2.

Ejemplo completo (el JSON interno, antes de serializarlo a string para el campo payload):

{
  "turno_id": 5501,
  "motivo": "Paciente cancela el turno",
  "tipo_cancelacion": "CANCELACION_PACIENTE",
  "timestamp": "2026-07-10T14:00:00Z"
}

5. Qué hace M6 al recibir el evento

  1. Busca la reserva de quirófano programada (origen=PROGRAMADA) asociada a turno_id. Si no existe, el mensaje se descarta (va a la DLQ) — no hay respuesta de error hacia M2, es la misma limitación que ya tiene el webhook REST hoy (404 sin retry automático de M6 hacia M2).
  2. Si la reserva ya está CANCELADA, no hace nada (idempotente) — reintentar el mismo evento (por ejemplo, ante un timeout de tu lado) es seguro.
  3. Si la reserva está EN_CURSO o COMPLETADA, no se puede cancelar — el mensaje se descarta (equivalente al 409 que hoy devuelve el REST).
  4. Si todo está bien, la reserva pasa a CANCELADA y se libera el quirófano.

Idempotencia de tu lado: no hace falta ningún id de correlación adicional — turno_id ya es la clave. Reintentar el mismo turno_id con el mismo motivo es seguro, no duplica nada.


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
El evento se publica (201) pero M6 nunca actúa Revisar que turno_id corresponda a una reserva PROGRAMADA real en M6; si el turno nunca tuvo reserva de quirófano asociada, no hay nada que cancelar del lado de M6
Necesito saber si M6 proceso bien el evento Hoy no hay canal de respuesta — es fire-and-forget. Si tu flujo necesita confirmación, seguir usando el REST directo mientras tanto

7. Checklist de integración

  • Cuenta de servicio de M2 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: 18 cuando se cancele/reprograme un turno quirúrgico.
  • payload (string JSON) con turno_id, motivo, tipo_cancelacion (opcional) y timestamp.
  • Coordinar con el equipo de M6 cuándo dejar de llamar también al REST directo (POST /api/v1/turnos/{turnoId}/cancelacion) — mientras tanto, no hay problema en llamar a ambos.

8. Referencias