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