api / documentation /integracion_m7_estado.md
Mate11
Integracion con M7 para las altas de las camas
0e75654
|
Raw History Blame Contribute Delete
13.5 kB
# Estado de Integración M6 ↔ M7 (Facturación)
> **Fecha de revisión:** 2026-07-12
> **Módulo origen:** M6 — Internación y Gestión de Camas
> **Módulo destino:** M7 — Facturación
> **Dirección del flujo:** unidireccional M6 → M7 (M7 no envía datos a M6)
---
## Método de integración
### Canal principal — Evento asincrónico vía Core/RabbitMQ (M10)
M6 publica un evento al bus del Core cuando se cierra una internación. M7 consume ese evento desde su cola `facturacion.requests`.
```
M6 backend
└─ POST /webhooks/hce/alta-medica (M1 avisa el alta médica)
└─ solicitud_service.procesar_alta_medica()
└─ facturacion.notify_cama_lista(cama, db)
└─ POST https://api.healthcare.cantero.ar/events/log
payload:
event_type_id: 19
publisher_module: "modulo_6"
payload: JSON.stringify({ evento: "CIERRE_INTERNACION", ... })
```
Datos del evento confirmados por M7:
```
event_name: facturacion.internacion.cama-lista.requested
event_type_id: 19
queue: facturacion.requests
publisher: modulo_6
```
### Canal fallback — REST directo a M7
Para testing manual o ante caída del Core, M7 expone dos endpoints REST que usan el mismo schema `InternacionM6Request`:
| Endpoint | Comportamiento |
|----------|---------------|
| `POST /api/v1/webhooks/internacion/cama-lista` | Persiste el evento, idempotente por `idEventoExterno` |
| `POST /api/integracion/internacion/cierre-episodio` | Igual + **si recibe paciente y episodio, consulta M1/HCE y registra los actos médicos facturables automáticamente** |
Ambos endpoints están implementados en `app/integrations/facturacion.py::notify_cama_lista()`.
> El endpoint `cierre-episodio` es el preferible para producción porque hace más trabajo automático del lado de M7.
---
## Schema `InternacionM6Request` (OpenAPI de M7)
Ambos endpoints REST usan el mismo schema. **Solo 2 campos son `required`.**
| Campo | Tipo | Req | Descripción |
|-------|------|-----|-------------|
| `idPacienteExterno` | `integer` | ✅ | ID numérico del paciente |
| `timestampEvento` | `datetime` | ✅ | Timestamp del cierre |
| `evento` | `string` | — | `"CIERRE_INTERNACION"` o `"CAMA_LISTA"` |
| `camaId` | `string` | — | ID de la cama |
| `idEventoExterno` | `string` | — | Clave de idempotencia |
| `idInternacionExterna` | `string` | — | ID de la solicitud HCE |
| `idEpisodioExterno` | `string` | — | ID del episodio clínico (M1) |
| `fechaIngreso` | `datetime` | — | Fecha de ingreso a la cama |
| `fechaAlta` | `datetime` | — | Fecha del alta médica |
| `tipoAlta` | `string` | — | Ej: `"ALTA_MEDICA"` |
| `medicoSolicitanteId` | `string` | — | ID del médico solicitante |
| `medicoFirmanteId` | `string` | — | ID del médico firmante del alta |
| `diagnosticoIngreso` | `string` | — | Diagnóstico de ingreso |
| `observaciones` | `string` | — | Observaciones adicionales |
| `camasUtilizadas` | `array` | — | Tramos de uso de cama (ver abajo) |
`camasUtilizadas[]` (cada ítem):
```json
{ "camaId": "101", "sector": "SALA_COMUN", "tipoCama": "SALA_COMUN",
"desde": "2026-06-20T14:30:00Z", "hasta": "2026-06-22T09:00:00Z" }
```
**Payload que enviamos actualmente** (canal Core/RabbitMQ — evento `CIERRE_INTERNACION`):
```json
{
"evento": "CIERRE_INTERNACION",
"idEventoExterno": "M6-CIERRE-INT-{cama_id}-{paciente_id}-{fecha}",
"idInternacionExterna": "{solicitud_hce_id}",
"idEpisodioExterno": null,
"idPacienteExterno": "{paciente_id}",
"fechaIngreso": "2026-06-20T14:30:00+00:00",
"fechaAlta": "2026-06-25T10:00:00+00:00",
"tipoAlta": "ALTA_MEDICA",
"timestampEvento": "2026-06-25T10:05:00+00:00"
}
```
> **Nota:** cuando M7 recibe `idPacienteExterno` + `idEpisodioExterno`, consulta M1/HCE automáticamente para registrar los actos médicos facturables del episodio. Sin `idEpisodioExterno` el cierre queda pendiente de completar de su lado.
---
## ✅ Hecho
| Qué | Dónde |
|-----|-------|
| Cliente de integración `notify_cama_lista()` | `app/integrations/facturacion.py` |
| Publicación de evento Core vía `publish_event()` | `app/integrations/core_events.py` |
| Payload rico `CIERRE_INTERNACION` (canal principal) | `facturacion.py` línea 51–64 |
| Payload mínimo `CAMA_LISTA` (canal fallback REST) | `facturacion.py` línea 40–48 |
| Persistencia de datos del episodio en `Cama` | `app/models/cama.py` (campos `solicitud_hce_id`, `fecha_ingreso`, `alta_tipo`, `alta_timestamp`) |
| Datos del episodio se guardan al aprobar internación | `solicitud_service.py` línea 202–203 |
| Datos del alta se guardan al procesar alta médica | `solicitud_service.py` línea 353–354 |
| Disparo en el momento correcto: alta médica (webhook de M1) | `solicitud_service.py::procesar_alta_medica` |
| Test de regresión: alta médica debe notificar a M7 | `tests/test_webhooks.py::test_alta_medica_notifica_a_facturacion` |
| Idempotencia del evento (`idEventoExterno` estable) | `facturacion.py` línea 38 |
| URL de M7 configurable | `config.py` → `m7_facturacion_url` |
| Variable de configuración `facturacion_cama_lista_event_type_id` | `config.py` línea 108 |
| Tests de integración (REST, evento Core, mock) | `tests/test_core_events.py` líneas 128–189 |
| Documentación del contrato de M7 | `documentation/integrations/M7_integration.md` |
---
## 🐛 Bugs encontrados al contrastar con el OpenAPI de M7
Hallados al comparar `app/integrations/facturacion.py` contra el schema real (`InternacionM6Request`):
### Bug 1 — REST fallback con nombres de campo incorrectos
El payload del canal REST fallback usa snake_case pero el schema espera camelCase:
| Código actual | Schema real |
|---------------|-------------|
| `"cama_id"` | `"camaId"` |
| `"paciente_id"` | `"idPacienteExterno"` |
| `"timestamp_evento"` | `"timestampEvento"` |
Esto significa que el canal REST fallback está enviando campos que M7 no reconoce (los ignora silenciosamente) y **no está enviando los campos que M7 sí lee**.
**Archivo:** `app/integrations/facturacion.py` línea 40–48.
### Bug 2 — `idPacienteExterno` enviado como string, el schema exige integer
El canal Core/RabbitMQ construye el payload con `"idPacienteExterno": str(paciente_id)`.
El OpenAPI de M7 define `idPacienteExterno` como `integer (int64)`.
**Archivo:** `app/integrations/facturacion.py` línea 57.
### Campos que M7 acepta y no estamos enviando (opcionales)
Los siguientes campos del schema están disponibles pero no los usamos todavía:
- `camaId` — ID de la cama (disponible en `cama.id`)
- `medicoFirmanteId` — ID del médico firmante (viene en `AltaMedicaWebhook.medico_firmante_id`, ya lo tenemos en el webhook pero no lo persistimos en `Cama`)
- `diagnosticoIngreso` — no se persiste en M6
- `camasUtilizadas[]` — tramos de uso de cama (ver sección dedicada abajo)
---
## 🟡 A medias / pendiente de activar
### 1. `idEpisodioExterno` va siempre como `null`
M1 no provee el ID del episodio clínico en el webhook `AltaMedicaWebhook`. El campo viaja como `null` en el evento a M7.
**Impacto:** M7 confirmó que el evento no se rechaza, pero queda "pendiente de completar" de su lado hasta que M1 lo provea.
**Desbloqueante:** coordinación con el equipo de M1 para que incluyan `episodio_id` en el payload del alta.
### 2. `FACTURACION_CAMA_LISTA_EVENT_TYPE_ID` ya configurado en `.env`, pero bloqueado por mock
El `event_type_id=19` está seteado en el `.env` real (`FACTURACION_CAMA_LISTA_EVENT_TYPE_ID=19`). Sin embargo, `MOCK_EXTERNAL_SERVICES=true` hace que `notify_cama_lista()` retorne `True` de inmediato sin hacer ningún request.
**Impacto:** el canal Core/RabbitMQ está configurado pero inactivo en dev. En producción, para que realmente dispare hay que asegurarse de que `MOCK_EXTERNAL_SERVICES=false`.
**Nota:** el `.env.example` lo tiene comentado por diseño (para que quien clone el repo no active el event bus sin querer).
### 3. Credenciales de cuenta de servicio no configuradas
El header `Authorization` de las llamadas al Core requiere `CORE_SERVICE_EMAIL` y `CORE_SERVICE_PASSWORD`. Sin estos, el POST a `/events/log` sale sin auth.
**Para activar:** obtener las credenciales con el equipo de M10 y agregarlas al `.env`.
---
## 🔴 Falta
No hay bloqueantes de backend para el flujo principal. El único pendiente es coordinar `idEpisodioExterno` con M1 (ver sección 🟡).
---
## Flujo completo (cuando todo esté activado)
```
1. M1 → POST /webhooks/hce/alta-medica
└─ cama pasa a EN_LIMPIEZA
└─ se persisten alta_tipo y alta_timestamp en la cama
└─ facturacion.notify_cama_lista(cama, db) ←── acá se dispara M7
2. notify_cama_lista():
a) REST fallback → POST M7_URL/api/v1/webhooks/internacion/cama-lista (payload mínimo)
b) Core/RabbitMQ → POST Core/events/log (payload rico CIERRE_INTERNACION, event_type_id=19)
3. Personal de limpieza → PATCH /camas/{id} { estado: DISPONIBLE }
└─ cama_service limpia los campos del episodio de la cama (paciente_id, alta_tipo, etc.)
└─ cama queda disponible para el próximo paciente
4. M7 recibe el evento desde su cola facturacion.requests
└─ consulta a M1 con idPacienteExterno + idEpisodioExterno
└─ factura la internación con su propio ABM de obras sociales
```
---
## `camasUtilizadas[]` — cómo reconstruir los tramos
El campo `camasUtilizadas` es opcional en el schema de M7. Representa los tramos de uso de cada cama durante toda la internación (relevante cuando hubo traslados).
### Caso sin traslados (mayoría de casos)
En el momento en que `notify_cama_lista(cama, db)` dispara, la `cama` ya tiene todos los datos del único tramo:
```python
camas_utilizadas = [{
"camaId": str(cama.id),
"sector": cama.sector,
"tipoCama": cama.tipo,
"desde": cama.fecha_ingreso.isoformat() if cama.fecha_ingreso else None,
"hasta": cama.alta_timestamp.isoformat() if cama.alta_timestamp else None,
}]
```
### Caso con traslados — reconstrucción desde auditoria
Si el paciente pasó por múltiples camas, la información está en la tabla `auditoria`. Los eventos relevantes son:
| Evento | Qué marca |
|--------|-----------|
| `CAMA_ASIGNADA` | Inicio del tramo en esa cama (campo `cama_id`, `creado_en`) |
| `SOLICITUD_APROBADA` (traslado) | Fin del tramo anterior + inicio del siguiente (`detalle.cama_origen_id`, `detalle.cama_asignada_id`) |
| `CAMA_ALTA` | Fin del último tramo |
**Reconstrucción para un paciente que pasó por cama A → cama B:**
```
auditoria (ordenada por creado_en ASC, filtrada por paciente_id):
T1 → CAMA_ASIGNADA cama_id=1 ← ingreso a cama A
T2 → SOLICITUD_APROBADA cama_id=2, detalle.cama_origen_id=1 ← traslado A→B
T3 → CAMA_ALTA cama_id=2 ← alta médica en cama B
Tramos resultantes:
{ camaId:"1", desde:T1, hasta:T2 } ← tramo cama A
{ camaId:"2", desde:T2, hasta:T3 } ← tramo cama B (= cama final)
```
Para `sector` y `tipoCama` de cada `camaId` histórico: query a `camas` por id. Se asume que no cambiaron de sector/tipo desde que el paciente estuvo ahí.
### Query a auditoria
```python
resp = db.table("auditoria") \
.select("*") \
.eq("paciente_id", paciente_id) \
.in_("evento", ["CAMA_ASIGNADA", "SOLICITUD_APROBADA", "CAMA_ALTA"]) \
.order("creado_en") \
.execute()
```
### Implementación pendiente
Para implementar `camasUtilizadas` completo se requiere:
1. Pasar `db: Client` a `notify_cama_lista(cama, db)` (hoy no recibe la sesión de DB)
2. Actualizar el call site en `cama_service.py` línea 145
3. Agregar la función `_reconstruir_tramos(db, paciente_id, cama_final)` en `facturacion.py`
4. Actualizar tests en `test_core_events.py` (nueva firma + assert del campo)
**Estado:** pendiente de implementar. El campo es opcional, M7 no lo requiere para procesar el cierre.
---
## Checklist para poner el canal principal en producción
**Fixes de código requeridos (ver sección 🐛):**
- [ ] Corregir nombres de campo del REST fallback: `cama_id`→`camaId`, `paciente_id`→`idPacienteExterno`, `timestamp_evento`→`timestampEvento` (`facturacion.py` línea 40–48)
- [ ] Corregir tipo de `idPacienteExterno`: de `str(paciente_id)` a `paciente_id` (int) (`facturacion.py` línea 57)
**Configuración:**
- [ ] ~~`FACTURACION_CAMA_LISTA_EVENT_TYPE_ID=19`~~ ya configurado en `.env` ✓ — verificar que esté en el deploy de producción
- [ ] Setear `MOCK_EXTERNAL_SERVICES=false` en producción (hoy bloquea toda llamada saliente)
- [ ] Configurar `CORE_SERVICE_EMAIL` y `CORE_SERVICE_PASSWORD` con las credenciales reales de M6 en M10
- [ ] Confirmar con M10 que la cola `facturacion.requests` está bindeada al `event_type_id=19`
**Coordinación entre módulos:**
- [ ] Coordinar con M1 para que provea `episodio_id` en el webhook de alta (desbloquea `idEpisodioExterno` → M7 factura automáticamente)
- [ ] Verificar con M7 que los eventos están llegando y siendo procesados
**Mejoras opcionales (enriquecen el payload):**
- [ ] Implementar `camasUtilizadas[]` reconstruyendo tramos desde auditoria (requiere pasar `db` a `notify_cama_lista`)
- [ ] Persistir `medico_firmante_id` en `Cama` al procesar el alta médica para poder enviarlo como `medicoFirmanteId`