File size: 6,465 Bytes
9f05894 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 | # 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`](integrations/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:
```http
POST /auth/login
Content-Type: application/json
{ "email": "<cuenta-servicio-m2@...>", "password": "<...>" }
```
Respuesta `200`:
```json
{ "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
```http
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`:
```json
{
"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`):
```json
{
"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
- [`M6_EVENTOS_RABBITMQ.md`](M6_EVENTOS_RABBITMQ.md) — infraestructura completa de M6 en el bus (los 5 eventos entrantes, no solo el de M2).
- [`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) §7.5 — contexto de la migración de webhooks REST a eventos.
|