api / openapi.yaml
Mate11
Actualizar código y documentación según spec OpenAPI
a3cbeab
Raw History Blame
132 kB
openapi: 3.0.1 info: title: 'Módulo 6 - Internación y Gestión de Camas' description: > API REST del módulo de Internación y Gestión de Camas para la red hospitalaria Health Grid. ## Modelo de Dominio Un **EPISODIO DE INTERNACIÓN** comienza cuando se aprueba una solicitud de cama y termina cuando el Módulo 1 (HCE) notifica el alta médica. El flujo principal es: 1. Un médico solicita una cama desde HCE (M1) 2. La solicitud llega a este módulo como webhook entrante 3. Un administrativo la aprueba (con la cama pedida u otra), o la rechaza 4. Al aprobar → se asigna la cama al paciente (estado `OCUPADA`) 5. Los traslados también llegan como solicitudes desde HCE (M1) o se realizan directamente 6. El alta médica llega como webhook desde HCE (M1) ### Solicitudes Las solicitudes de internación y traslado llegan desde HCE (M1) y quedan en estado `PENDIENTE` hasta que un administrativo las resuelve. | Resolución | Efecto | |------------|--------| | `APROBAR` | Se ejecuta la acción (ingreso o traslado) con la cama solicitada | | `APROBAR_CON_CAMBIO` | Se ejecuta la acción con una cama distinta a la solicitada | | `RECHAZAR` | No se ejecuta ninguna acción. Se notifica a HCE | ## Leyenda de Endpoints - **Sin prefijo:** Endpoints PROPIOS de este módulo (implementados por nosotros) - **Tag [EXT]:** Endpoints de otros módulos, documentados como referencia. Mockeados localmente en la 2da entrega ## Webhooks Salientes (HTTP POST que este módulo dispara) | Evento | Receptor | Cuándo | |--------|----------|--------| | `SOLICITUD_RESUELTA` | Módulo 1 - HCE | Al aprobar o rechazar una solicitud | | `ALTA_MONITOREO` | Módulo 9 - Monitoreo | Al asignar una cama a un paciente (ingreso o traslado destino) | | `BAJA_MONITOREO` | Módulo 9 - Monitoreo | Al dar el alta médica o al trasladar un paciente (cama origen) | | `CAMA_LISTA` | Módulo 7 - Facturación | Al completar limpieza post-alta (cama pasa de EN_LIMPIEZA a DISPONIBLE) | ## Webhooks Entrantes (HTTP POST que recibimos de otros módulos) | Evento | Emisor | Cuándo | |--------|--------|--------| | Solicitud de internación | Módulo 1 - HCE | Un médico solicita cama para internar un paciente | | Solicitud de traslado | Módulo 1 - HCE | Un médico solicita trasladar un paciente internado | | Alta médica | Módulo 1 - HCE | Un médico da el alta al paciente | | Alerta de emergencia | Módulo 9 - Monitoreo | Se detecta un código rojo en un paciente | ## APIs Externas Consumidas | Módulo | Endpoint | Cuándo se usa | |--------|----------|---------------| | Core (M10) | `GET /usuarios/{pacienteId}` | Al aprobar una solicitud de internación | | Core (M10) | `POST /auth/validate-token` | En cada request (middleware JWT) | | HCE (M1) | `GET /pacientes/{pacienteId}/contraindicaciones` | Al aprobar una solicitud de internación | | HCE (M1) | `POST /hce/solicitudes/{solicitudHceId}/resultado` | Al resolver una solicitud | | HCE (M1) | `GET /hce/pacientes/{pacienteId}` | Al mostrar el detalle del paciente internado en una cama | | HCE (M1) | `POST /hce/movimientos` | Al asignar una cama o trasladar un paciente | | Turnos (M2) | `GET /turnos/{turnoId}` | Al aprobar solicitud con origen=CIRUGIA_PROGRAMADA | | Facturación (M7) | `POST /webhooks/internacion/cama-lista` | Al completar limpieza post-alta | | Monitoreo (M9) | `POST /webhooks/internacion/baja-monitoreo` | Al dar alta médica o trasladar (cama origen) | | Monitoreo (M9) | `POST /webhooks/internacion/alta-monitoreo` | Al asignar cama a un paciente (ingreso o traslado destino) | | HCE (M1) | `POST /hce/episodios/{episodioId}/eventos` | Al recibir alerta de emergencia de M9 | version: 4.0.0 contact: name: Grupo Módulo 6 - UADE license: name: Uso académico tags: - name: Camas - name: Solicitudes - name: Webhooks Entrantes - name: '[EXT] HCE - Módulo 1' - name: '[EXT] Turnos - Módulo 2' - name: '[EXT] Facturación - Módulo 7' - name: '[EXT] Monitoreo - Módulo 9' - name: '[EXT] Core - Módulo 10' paths: /camas: get: summary: Obtener mapa completo de camas deprecated: false description: > Retorna el estado actual de todas las camas del hospital con estadísticas agregadas. Permite filtrar por piso, sector, estado y hospital. > **Nota:** Las camas con estado `BAJA_PERMANENTE` **no** se incluyen por defecto. ## Comportamiento por rol | Rol | Comportamiento | |-----|----------------| | `ADMINISTRATIVO`, `MEDICO` | Ve todas las camas con todos los filtros | | `LIMPIEZA` | Solo ve camas con estado `EN_LIMPIEZA`. Los demás filtros de estado se ignoran. | ## Roles permitidos `MEDICO`, `ADMINISTRATIVO` y `LIMPIEZA`. operationId: getCamas tags: - Camas parameters: - name: piso in: query description: '' required: false schema: type: integer - name: sector in: query description: '' required: false schema: type: string - name: estado in: query description: '' required: false schema: type: string - name: hospital_id in: query description: '' required: false schema: type: string responses: '200': description: Mapa de camas con estadísticas content: application/json: schema: $ref: '#/components/schemas/CamaMapaResponse' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado headers: {} '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción headers: {} security: - BearerAuth: [] post: summary: Crear una nueva cama deprecated: false description: > Permite a un administrador dar de alta una nueva cama en el inventario hospitalario. ## Consideraciones - El `id` de la cama es un entero generado automáticamente por el sistema. - La cama se crea en estado `DISPONIBLE` por defecto. ## Roles permitidos Solo usuarios con rol `ADMINISTRATIVO` pueden ejecutar esta operación. operationId: crearCama tags: - Camas parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CamaCreateRequest' examples: cama_uti: value: numero: '210' piso: 2 sector: UTI tipo: CRITICA hospital_id: HOSP-001 contraindicaciones_incompatibles: - ALERGIA_LATEX summary: Nueva cama de UTI cama_sala: value: numero: '315' piso: 3 sector: SALA_COMUN tipo: ESTANDAR hospital_id: HOSP-001 contraindicaciones_incompatibles: [] summary: Nueva cama de sala común cama_quirofano: value: numero: Q01 piso: 5 sector: QUIROFANO tipo: CIRUGIA hospital_id: HOSP-001 specialty_id: 43 contraindicaciones_incompatibles: [] summary: Nuevo quirófano (CIRUGIA) con specialty_id required: true responses: '201': description: Cama creada exitosamente content: application/json: schema: $ref: '#/components/schemas/Cama' example: id: 210 numero: '210' piso: 2 sector: UTI tipo: CRITICA estado: DISPONIBLE paciente_id: null hospital_id: HOSP-001 contraindicaciones_incompatibles: - ALERGIA_LATEX ultima_actualizacion: '2025-06-01T09:00:00Z' specialty_id: null headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción security: - BearerAuth: [] /camas/{camaId}: get: summary: Obtener detalle de una cama deprecated: false description: | ## Roles permitidos `MEDICO` y `ADMINISTRATIVO`. operationId: getCamaById tags: - Camas parameters: - name: camaId in: path description: Identificador único de la cama (entero autogenerado) required: true example: 0 schema: type: integer example: 204 responses: '200': description: Detalle de la cama content: application/json: schema: $ref: '#/components/schemas/Cama' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción '404': $ref: '#/components/responses/CamaNoEncontrada' description: Cama no encontrada security: - BearerAuth: [] patch: summary: Actualizar estado o contraindicaciones incompatibles de una cama deprecated: false description: > Permite cambiar el estado de una cama manualmente o actualizar la lista de `contraindicaciones_incompatibles`. **Restricciones:** - El estado `OCUPADA` solo se asigna automáticamente al aprobar solicitudes o al asignar. - El estado `CODIGO_ROJO` solo lo setea el webhook de alerta de emergencia de M9. ## Roles permitidos `ADMINISTRATIVO` y `LIMPIEZA`. ## Restricciones por rol | Rol | Transiciones permitidas | |-----|------------------------| | `ADMINISTRATIVO` | Cualquier transición manual válida | | `LIMPIEZA` | Solo `EN_LIMPIEZA` → `DISPONIBLE` | ## Comportamiento especial: limpieza completada (post-alta) Cuando una cama pasa de `EN_LIMPIEZA` a `DISPONIBLE` y el último movimiento del paciente fue un **alta médica**: 1. Se dispara el webhook `CAMA_LISTA` al Módulo 7 (Facturación) con los datos del episodio para la liquidación de prestaciones. 2. Se emite evento `CAMA_ACTUALIZADA` por WebSocket. Si la cama estaba `EN_LIMPIEZA` por un **traslado** (no por alta), **no** se dispara el webhook a facturación. > **Nota:** En versiones anteriores, `CAMA_LISTA` se disparaba al > recibir el alta médica. Ahora se dispara al completar la limpieza. operationId: updateCamaEstado tags: - Camas parameters: - name: camaId in: path description: '' required: true example: 0 schema: type: integer example: 0 requestBody: content: application/json: schema: $ref: '#/components/schemas/CamaUpdateRequest' required: true responses: '200': description: Estado actualizado exitosamente content: application/json: schema: $ref: '#/components/schemas/Cama' headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado headers: {} '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción headers: {} '404': $ref: '#/components/responses/CamaNoEncontrada' description: Cama no encontrada headers: {} '409': description: Conflicto con el estado actual de la cama content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] delete: summary: Dar de baja permanente una cama deprecated: false description: > Realiza una **baja lógica** (soft delete) de la cama: la marca con estado `BAJA_PERMANENTE` y la excluye del inventario operativo. No se elimina el registro físico de la base de datos para preservar la trazabilidad histórica (episodios pasados que referenciaron esta cama siguen siendo válidos). ## Restricciones - Solo se puede dar de baja una cama que esté en estado `DISPONIBLE` o `FUERA_DE_SERVICIO`. - Si la cama está `OCUPADA` o `EN_LIMPIEZA` (lo que implica que estuvo ocupada recientemente), la operación es rechazada con `409 Conflict`. - Una cama con estado `BAJA_PERMANENTE` **no puede** ser reactivada a través de esta API (requiere intervención manual en base de datos o un proceso administrativo separado). ## Roles permitidos Solo usuarios con rol `ADMINISTRATIVO` pueden ejecutar esta operación. operationId: darDeBajaCama tags: - Camas parameters: - name: camaId in: path description: Identificador único de la cama (entero autogenerado) required: true example: 0 schema: type: integer example: 204 responses: '200': description: Cama dada de baja permanente exitosamente content: application/json: schema: $ref: '#/components/schemas/Cama' example: id: 210 numero: '210' piso: 2 sector: UTI tipo: CRITICA estado: BAJA_PERMANENTE paciente_id: null hospital_id: HOSP-001 contraindicaciones_incompatibles: [] ultima_actualizacion: '2025-06-15T14:00:00Z' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción '404': $ref: '#/components/responses/CamaNoEncontrada' description: Cama no encontrada '409': description: La cama no puede darse de baja en su estado actual content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: CAMA_EN_USO mensaje: No se puede dar de baja una cama en uso detalle: >- La cama 204 está OCUPADA por el paciente 123. Dé de alta al paciente antes de proceder. headers: {} security: - BearerAuth: [] /camas/{camaId}/asignar: post: summary: Asignar o trasladar un paciente a una cama deprecated: false description: > Permite asignar directamente un paciente a una cama (ingreso) o trasladarlo desde su cama actual a esta cama (traslado), sin requerir una solicitud previa. Antes de asignar, el sistema verifica que ninguna contraindicación del paciente esté en la lista `contraindicaciones_incompatibles` de la cama destino. Si alguna coincide, devuelve `HTTP 422 CONTRAINDICACION_DETECTADA`. ## Tipos de movimiento | Tipo | Descripción | |------|-------------| | `INGRESO` | Asigna el paciente a la cama. La cama pasa a estado `OCUPADA`. | | `TRASLADO` | Mueve al paciente desde su cama actual (`cama_origen_id`) a esta. La cama origen pasa a `EN_LIMPIEZA`, la destino a `OCUPADA`. | ## Efectos colaterales - **[EXT]** Notifica el movimiento a HCE (M1) vía `POST /hce/movimientos` - **[EXT]** Si `tipo=INGRESO`: emite `ALTA_MONITOREO` a M9 (el paciente entra en monitoreo) - Si `tipo=TRASLADO`: **no** se emiten eventos de monitoreo (el monitoreo sigue al paciente, no a la cama) ## Roles permitidos Solo usuarios con rol `ADMINISTRATIVO`. operationId: asignarCama tags: - Camas parameters: - name: camaId in: path description: Identificador único de la cama (entero autogenerado) required: true example: 0 schema: type: integer example: 204 requestBody: content: application/json: schema: $ref: '#/components/schemas/AsignacionCamaRequest' examples: ingreso: value: tipo: INGRESO paciente_id: 123 summary: Asignación de cama (ingreso) traslado: value: tipo: TRASLADO paciente_id: 123 cama_origen_id: 204 summary: Traslado a esta cama required: true responses: '200': description: Cama asignada o traslado realizado exitosamente content: application/json: schema: $ref: '#/components/schemas/AsignacionCamaResponse' example: mensaje: Paciente 123 asignado a la cama 315 cama_id: 315 paciente_id: 123 tipo: INGRESO cama_origen_id: null timestamp: '2025-01-15T10:30:00Z' headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción '404': $ref: '#/components/responses/CamaNoEncontrada' description: Cama no encontrada '409': description: Conflicto con el estado de la cama o del paciente content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: CAMA_NO_DISPONIBLE mensaje: La cama destino no está disponible detalle: La cama 315 está actualmente en estado OCUPADA headers: {} '422': description: Contraindicación del paciente incompatible con la cama destino content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: CONTRAINDICACION_DETECTADA mensaje: >- El paciente tiene contraindicaciones incompatibles con la cama destino detalle: La cama 204 es incompatible con ALERGIA_LATEX del paciente 123 headers: {} '502': description: Error al notificar movimiento a HCE (M1) content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: SERVICIO_EXTERNO_NO_DISPONIBLE mensaje: No se pudo notificar el movimiento a HCE detalle: >- El módulo HCE (M1) no respondió en el tiempo esperado. La asignación de cama fue completada. headers: {} security: - BearerAuth: [] /camas/{camaId}/reservas: get: summary: Listar reservas de un quirófano deprecated: false description: > Retorna las reservas de un quirófano con filtros opcionales. Por defecto devuelve reservas con estado `RESERVADA` y `EN_CURSO`. Solo aplica a camas con **sector=QUIROFANO y tipo=CIRUGIA**. Si la cama no cumple esta condición, responde `409 CAMA_NO_ES_QUIROFANO`. ## Roles permitidos `MEDICO` y `ADMINISTRATIVO`. operationId: getReservasQuirofano tags: - Camas parameters: - name: camaId in: path description: '' required: true example: 0 schema: type: integer example: 0 - name: estado in: query description: '' required: false schema: type: string - name: prioridad in: query description: >- Filtra las reservas por prioridad clínica. Acepta un único valor del enum `PrioridadQuirofanoEnum`. required: false schema: $ref: '#/components/schemas/PrioridadQuirofanoEnum' - name: fecha_desde in: query description: '' required: false schema: type: string format: date - name: fecha_hasta in: query description: '' required: false schema: type: string format: date responses: '200': description: Lista de reservas del quirófano content: application/json: schema: type: object properties: total: type: integer example: 2 reservas: type: array items: $ref: '#/components/schemas/ReservaQuirofanoResponse' headers: {} '401': description: No autenticado headers: {} '404': description: Cama no encontrada headers: {} '409': description: La cama no es un quirófano (sector!=QUIROFANO o tipo!=CIRUGIA) headers: {} security: - BearerAuth: [] post: summary: Crear reserva de quirófano programada deprecated: false description: > Crea una reserva de quirófano para una cirugía programada. **Este endpoint lo invoca exclusivamente M2 (Turnos)** cuando confirma un turno quirúrgico. No existe una UI en M6 para crear reservas: todo el flujo de reservas nace fuera de este módulo. ## Flujos de reserva en M6 M6 maneja reservas de quirófano sólo a través de estos cuatro caminos automáticos. Ninguno requiere intervención manual de un administrativo de M6: | Escenario | Entrada a M6 | Resultado | |-----------|--------------|-----------| | Cirugía programada | `POST /camas/{camaId}/reservas` ← M2 | Reserva `PROGRAMADA` con prioridad elegida por M2 | | Urgencia sin conflicto | `POST /webhooks/hce/cirugia-urgente` ← M1 | Reserva `EMERGENCIA` en un quirófano libre | | Urgencia con conflicto | `POST /webhooks/hce/cirugia-urgente` ← M1 | Reserva `EMERGENCIA` + desplazamiento de la programada de menor prioridad + aviso a M2 | | Cancelación de turno | `POST /turnos/{turnoId}/cancelacion-quirofano` ← M2 | Reserva pasa a `CANCELADA` | ## Semántica - `turno_id` es obligatorio. El `origen` resultante es siempre `PROGRAMADA`. - La respuesta HTTP es el resultado definitivo: - `201 Created`: la reserva quedó confirmada. - `409 Conflict`: no se pudo reservar (superposición, cama no disponible o cama que no corresponde a quirófano). `GET /camas/disponibilidad` puede usarse previamente desde M2 para mostrar opciones, pero no reemplaza esta validación. El check de superposición y la inserción de la reserva se ejecutan en una única transacción para evitar race conditions. ## Validaciones - La cama debe tener **sector=QUIROFANO y tipo=CIRUGIA**. - La cama no debe estar en `FUERA_DE_SERVICIO` ni `BAJA_PERMANENTE`. - `fecha_hora_inicio` debe ser anterior a `fecha_hora_fin_estimada`. - No debe existir otra reserva activa superpuesta para la misma cama. - `turno_id` es obligatorio y no debe existir otra reserva activa para ese turno (idempotencia: reintentos con el mismo `turno_id` devuelven la reserva existente con `200 OK` en vez de duplicarla). - `prioridad` es obligatoria. El valor `URGENTE` está reservado para el flujo automático de `/webhooks/hce/cirugia-urgente` y no se acepta por este endpoint (devuelve `HTTP 422 PRIORIDAD_URGENTE_NO_PERMITIDA`). ## Autorización Sólo M2 (Turnos). No hay rol humano con permiso para invocar este endpoint directamente. operationId: crearReservaQuirofano tags: - Camas parameters: - name: camaId in: path description: '' required: true example: 0 schema: type: integer example: 0 requestBody: content: application/json: schema: $ref: '#/components/schemas/ReservaQuirofanoCreateRequest' example: turno_id: 89 paciente_id: 123 medico_cirujano_id: 45 fecha_hora_inicio: '2025-01-18T09:00:00Z' fecha_hora_fin_estimada: '2025-01-18T11:00:00Z' prioridad: MEDIA observaciones: Colecistectomía laparoscópica programada required: true responses: '200': description: >- La reserva ya existía con ese `turno_id` (idempotencia). Devuelve la reserva previamente registrada sin crear una nueva. content: application/json: schema: $ref: '#/components/schemas/ReservaQuirofanoResponse' headers: {} '201': description: Reserva creada content: application/json: schema: $ref: '#/components/schemas/ReservaQuirofanoResponse' example: id: 15 cama_id: 501 turno_id: 89 origen: PROGRAMADA estado: RESERVADA prioridad: MEDIA paciente_id: 123 medico_cirujano_id: 45 fecha_hora_inicio: '2025-01-18T09:00:00Z' fecha_hora_fin_estimada: '2025-01-18T11:00:00Z' observaciones: Colecistectomía laparoscópica programada desplazada_por_reserva_id: null created_at: '2025-01-18T08:55:00Z' headers: {} '400': description: Error de validación headers: {} '401': description: No autenticado headers: {} '403': description: No autorizado headers: {} '404': description: Cama no encontrada headers: {} '409': description: Conflicto de reserva content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RESERVA_SUPERPUESTA mensaje: No se pudo crear la reserva detalle: >- El quirófano 501 ya posee una reserva activa entre 2025-01-18T09:30:00Z y 2025-01-18T10:30:00Z headers: {} '422': description: Prioridad no permitida para este flujo content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: PRIORIDAD_URGENTE_NO_PERMITIDA mensaje: La prioridad URGENTE no puede asignarse desde este endpoint detalle: >- URGENTE está reservada para el flujo automático de `/webhooks/hce/cirugia-urgente` headers: {} security: - BearerAuth: [] /camas/{camaId}/reservas/{reservaId}: get: summary: Obtener detalle de una reserva deprecated: false description: | Devuelve el detalle completo de una reserva de quirófano. ## Roles permitidos `MEDICO` y `ADMINISTRATIVO`. operationId: getReservaById tags: - Camas parameters: - name: reservaId in: path description: '' required: true example: 0 schema: type: integer example: 1 - name: camaId in: path description: '' required: true example: 0 schema: type: integer example: 501 responses: '200': description: Detalle de la reserva content: application/json: schema: $ref: '#/components/schemas/ReservaQuirofanoResponse' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Reserva o cama no encontrada content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Reserva no encontrada detalle: No existe reserva con ID 999 en la cama 501 headers: {} security: - BearerAuth: [] patch: summary: Actualizar estado de una reserva de quirófano deprecated: false description: > Permite cambiar el estado de una reserva de quirófano desde este módulo. ## Transiciones válidas | De | A | Efecto en la cama | |----|---|-------------------| | `RESERVADA` | `EN_CURSO` | Cama pasa a `OCUPADA` | | `RESERVADA` | `CANCELADA` | Sin cambio en la cama | | `EN_CURSO` | `COMPLETADA` | Cama pasa a `EN_LIMPIEZA` | ## Comportamiento Este endpoint `PATCH` queda para acciones internas de M6, por ejemplo iniciar la cirugía, completarla o cancelar una reserva Se usa para cancelaciones cuando la cancelación no nace en M2, sino dentro de Internación y Gestión de Camas. Por ejemplo: se requiere liberar un quirófano reservado para una cirugía programada para poder atender una cirugía de emergencia. - Cambia la reserva a estado `CANCELADA` y libera el recurso para nuevas reservas. - Si la reserva cancelada tiene `turno_id`, significa que estaba asociada a una cirugía programada de M2. En ese caso M6 debe informar a M2 por el mecanismo de integración acordado para que el turno quede cancelado o pendiente de reprogramación. - No reemplaza a `POST /turnos/{turnoId}/cancelacion-quirofano`: ese endpoint sigue siendo para cancelaciones iniciadas por M2. ## Roles permitidos `ADMINISTRATIVO`. operationId: updateEstadoReserva tags: - Camas parameters: - name: camaId in: path description: '' required: true example: 0 schema: type: integer example: 0 - name: reservaId in: path description: '' required: true example: 0 schema: type: integer example: 0 requestBody: content: application/json: schema: $ref: '#/components/schemas/ReservaEstadoUpdateRequest' required: true responses: '200': description: Estado actualizado headers: {} '400': description: Error de validación headers: {} '401': description: No autenticado headers: {} '403': description: No autorizado headers: {} '404': description: Reserva o cama no encontrada headers: {} '409': description: Transición de estado inválida headers: {} security: - BearerAuth: [] /camas/disponibilidad: get: summary: Consultar disponibilidad de quirófanos en un rango horario deprecated: false description: > Retorna los quirófanos (camas con **sector=QUIROFANO y tipo=CIRUGIA**) y, para cada uno, las reservas activas que caen total o parcialmente dentro del rango horario indicado. Incluye sólo quirófanos cuyo estado actual no es `FUERA_DE_SERVICIO` ni `BAJA_PERMANENTE`. Se usa para visualizar huecos disponibles. No es un prerrequisito de la reserva: la validación real de superposición se ejecuta de forma atómica dentro del flujo de creación (`POST /camas/{camaId}/reservas` para M2, o el motor de desplazamiento interno de `/webhooks/hce/cirugia-urgente` para M1). La disponibilidad devuelta por este endpoint no garantiza que el quirófano siga libre al momento de la creación. ## Quién lo usa - **M2 (Turnos):** consulta principal. Lo usa para mostrar opciones en la UI de reserva de turnos quirúrgicos. - **M6 (este módulo):** sólo lectura. Personal de M6 (`ADMINISTRATIVO`, `MEDICO`) puede visualizar la ocupación de quirófanos, pero no puede crear ni modificar reservas desde acá. operationId: getDisponibilidadQuirofanos tags: - Camas parameters: - name: desde in: query description: '' required: true schema: type: string format: date-time - name: hasta in: query description: '' required: true schema: type: string format: date-time - name: hospital_id in: query description: '' required: false schema: type: string - name: specialty_id in: query description: >- Filtra quirófanos por especialidad quirúrgica (referencia al `id` de M2). Útil para que M2 muestre solo los quirófanos compatibles con el tipo de cirugía del turno. required: false schema: type: integer example: 43 responses: '200': description: Quirófanos disponibles en el rango content: application/json: schema: type: object properties: desde: type: string format: date-time example: '2025-01-18T08:00:00Z' hasta: type: string format: date-time example: '2025-01-18T18:00:00Z' total_quirofanos: type: integer example: 3 quirofanos: type: array items: type: object properties: cama_id: type: integer example: 501 numero: type: string example: '501' piso: type: integer example: 5 hospital_id: type: string example: HOSP-001 estado: $ref: '#/components/schemas/EstadoCamaEnum' reservas_en_rango: type: array description: > Reservas activas (RESERVADA o EN_CURSO) que caen total o parcialmente dentro del rango solicitado. Permite ver los huecos disponibles. items: $ref: '#/components/schemas/ReservaQuirofanoResponse' specialty_id: type: integer description: >- Especialidad quirúrgica del quirófano (ID de M2). Permite a M2 filtrar por especialidad compatible. nullable: true example: 43 headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: No autenticado headers: {} '403': $ref: '#/components/responses/NoAutorizado' description: No autorizado headers: {} security: - BearerAuth: [] /solicitudes: get: summary: Listar solicitudes deprecated: false description: > Retorna las solicitudes de internación y traslado recibidas desde HCE (M1). Por defecto devuelve solo las solicitudes en estado `PENDIENTE`. ## Roles permitidos `MEDICO` (lectura) y `ADMINISTRATIVO`. operationId: getSolicitudes tags: - Solicitudes parameters: - name: estado in: query description: Filtrar por estado. Si se omite, devuelve solo PENDIENTE. required: false schema: $ref: '#/components/schemas/EstadoSolicitudEnum' - name: tipo in: query description: Filtrar por tipo de solicitud required: false schema: $ref: '#/components/schemas/TipoSolicitudEnum' - name: hospital_id in: query description: '' required: false schema: type: string example: HOSP-001 responses: '200': description: Lista de solicitudes content: application/json: schema: $ref: '#/components/schemas/SolicitudesListResponse' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción security: - BearerAuth: [] /solicitudes/{solicitudId}: get: summary: Obtener detalle de una solicitud deprecated: false description: | ## Roles permitidos `MEDICO` (lectura) y `ADMINISTRATIVO`. operationId: getSolicitudById tags: - Solicitudes parameters: - name: solicitudId in: path description: Identificador único de la solicitud required: true example: '' schema: type: string example: SOL-00123 responses: '200': description: Detalle de la solicitud content: application/json: schema: $ref: '#/components/schemas/Solicitud' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': $ref: '#/components/responses/SolicitudNoEncontrada' description: Solicitud no encontrada security: - BearerAuth: [] patch: summary: Resolver una solicitud (aprobar o rechazar) deprecated: false description: > Permite al administrativo aprobar o rechazar una solicitud de internación o traslado. ## Acciones posibles | Acción | Descripción | |--------|-------------| | `APROBAR` | Acepta la solicitud con la cama originalmente solicitada | | `APROBAR_CON_CAMBIO` | Acepta pero asigna una cama distinta (requiere `cama_asignada_id` y `motivo`) | | `RECHAZAR` | Rechaza la solicitud (requiere `motivo`) | ## Flujo al APROBAR solicitud de INTERNACION 1. **[EXT]** Valida existencia del paciente con Core (M10) 2. Verifica que ninguna contraindicación del paciente coincida con `contraindicaciones_incompatibles` de la cama destino; si coincide → `HTTP 422` 3. Marca la cama como `OCUPADA` y asigna el paciente 4. **[EXT]** Notifica el movimiento y el resultado a HCE (M1) vía `POST /hce/movimientos` con `tipo_movimiento=INGRESO` (M1 registra el movimiento y notifica al médico a cargo) 5. **[EXT]** Emite `ALTA_MONITOREO` a M9 vía `POST /webhooks/internacion/alta-monitoreo` ## Flujo al APROBAR solicitud de TRASLADO 1. Valida que la cama destino esté `DISPONIBLE` y compatible con las contraindicaciones del paciente 2. Cama origen → `EN_LIMPIEZA`, cama destino → `OCUPADA` 3. **[EXT]** Notifica el movimiento y el resultado a HCE (M1) vía `POST /hce/movimientos` con `tipo_movimiento=TRASLADO` 4. El monitoreo continúa sobre el mismo paciente: **no** se emite `ALTA_MONITOREO` ni `BAJA_MONITOREO` ## Flujo al RECHAZAR 1. Marca solicitud como `RECHAZADA` 2. **[EXT]** Notifica el rechazo a HCE (M1) vía `POST /hce/movimientos` con `tipo_movimiento=RESOLUCION_SOLICITUD`, `resultado=RECHAZADA` y el `motivo` > **Nota sobre contraindicaciones:** la consulta a HCE (M1) de contraindicaciones del paciente > es puramente informativa para la decisión del administrativo. La validación automática sólo > se ejecuta contra `contraindicaciones_incompatibles` de la cama. ## Roles permitidos Solo usuarios con rol `ADMINISTRATIVO`. operationId: resolverSolicitud tags: - Solicitudes parameters: - name: solicitudId in: path description: Identificador único de la solicitud required: true example: '' schema: type: string example: SOL-00123 requestBody: content: application/json: schema: $ref: '#/components/schemas/SolicitudResolucionRequest' examples: aprobar: value: accion: APROBAR summary: Aprobar con la cama solicitada aprobar_cambio: value: accion: APROBAR_CON_CAMBIO cama_asignada_id: 312 motivo: >- La cama solicitada quedó fuera de servicio; asigno alternativa del mismo sector summary: Aprobar con cama alternativa rechazar: value: accion: RECHAZAR motivo: >- No hay disponibilidad en el sector solicitado para las próximas 24hs summary: Rechazar la solicitud required: true responses: '200': description: Solicitud resuelta exitosamente content: application/json: schema: $ref: '#/components/schemas/Solicitud' headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '403': $ref: '#/components/responses/NoAutorizado' description: El rol del usuario no tiene permisos para esta acción '404': $ref: '#/components/responses/SolicitudNoEncontrada' description: Solicitud no encontrada '409': description: Conflicto con el estado de la solicitud o la cama content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: SOLICITUD_YA_RESUELTA mensaje: La solicitud ya fue resuelta detalle: La solicitud SOL-00123 fue APROBADA el 2025-01-15T10:30:00Z headers: {} '422': description: Contraindicación del paciente incompatible con la cama destino content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: CONTRAINDICACION_DETECTADA mensaje: >- El paciente tiene contraindicaciones incompatibles con la cama destino detalle: La cama 204 es incompatible con ALERGIA_LATEX del paciente 123 headers: {} '502': description: Error al consultar servicio externo content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: SERVICIO_EXTERNO_NO_DISPONIBLE mensaje: No se pudo completar la validación externa detalle: El módulo Core (M10) no respondió en el tiempo esperado headers: {} security: - BearerAuth: [] /webhooks/hce/solicitud: post: summary: '[M1] Recibir solicitud (internación o traslado)' deprecated: false description: > El Módulo 1 (HCE) llama a este endpoint cuando un médico solicita una cama para internar a un paciente o para trasladarlo a otra cama. El campo `tipo` discrimina entre ambos flujos. ## Acciones que ejecuta este módulo 1. Valida el payload según `tipo` (`INTERNACION` o `TRASLADO`). 2. Crea una solicitud en estado `PENDIENTE`. 3. Queda disponible para que un administrativo la resuelva vía `PATCH /solicitudes/{id}`. operationId: recibirSolicitudHce tags: - Webhooks Entrantes parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SolicitudHceWebhook' examples: internacion: value: tipo: INTERNACION solicitud_hce_id: HCE-SOL-00789 paciente_id: 123 medico_solicitante_id: 45 cama_solicitada_id: 204 origen: GUARDIA diagnostico_ingreso: Insuficiencia respiratoria aguda obra_social_id: OSDE-310 numero_afiliado: '123456789' prioridad: ALTA observaciones: Paciente requiere monitoreo continuo timestamp: '2025-01-15T08:00:00Z' summary: Solicitud de internación traslado: value: tipo: TRASLADO solicitud_hce_id: HCE-SOL-00790 paciente_id: 123 medico_solicitante_id: 45 cama_origen_id: 204 cama_destino_solicitada_id: 108 motivo_traslado: Mejoría clínica - pase a sala común timestamp: '2025-01-17T10:00:00Z' summary: Solicitud de traslado required: true responses: '200': description: Solicitud recibida y registrada como pendiente content: application/json: schema: type: object properties: mensaje: type: string example: Solicitud recibida y pendiente de aprobación solicitud_id: type: string description: ID interno de la solicitud en nuestro módulo example: SOL-00123 estado: type: string example: PENDIENTE headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado security: - BearerAuth: [] /webhooks/hce/alta-medica: post: summary: '[M1] Recibir alta médica' deprecated: false description: > El Módulo 1 (HCE) llama a este endpoint cuando un médico da el alta a un paciente internado. M1 es dueño del episodio: este módulo sólo reacciona sobre la cama y dispara los webhooks correspondientes. La cama del paciente se resuelve internamente a partir del `paciente_id` (este módulo mantiene su propio registro de asignaciones activas). M1 **no necesita enviar** el `cama_id` en el payload. ## Acciones que ejecuta este módulo 1. Busca la cama actualmente asignada al `paciente_id` recibido. 2. La cama pasa a estado `EN_LIMPIEZA`. 3. **[WEBHOOK]** Emite `BAJA_MONITOREO` al Módulo 9 (Monitoreo). 4. Se emite evento `CAMA_ACTUALIZADA` por WebSocket. > **Nota:** El webhook `CAMA_LISTA` a Facturación (M7) **NO** se dispara aquí. > Se dispara cuando el personal de limpieza marca la cama como `DISPONIBLE` > vía `PATCH /camas/{camaId}`. operationId: recibirAltaMedica tags: - Webhooks Entrantes parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AltaMedicaWebhook' example: paciente_id: 123 medico_firmante_id: 45 tipo_alta: ALTA_MEDICA timestamp: '2025-01-20T11:00:00Z' required: true responses: '200': description: Alta procesada exitosamente content: application/json: schema: type: object properties: mensaje: type: string example: Alta médica procesada. Cama en limpieza. cama_id: type: integer example: 204 estado_cama: type: string example: EN_LIMPIEZA headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado headers: {} '404': description: Paciente no encontrado o sin cama asignada content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] /webhooks/hce/cirugia-urgente: post: summary: '[M1] Recibir solicitud de cirugía urgente' deprecated: false description: > El Módulo 1 (HCE) llama a este endpoint cuando un médico decide que un paciente necesita una cirugía de emergencia y requiere quirófano de forma inmediata. ## Diferencia con el flujo de reserva programada Este endpoint es uno de los dos mecanismos automáticos por los que entran reservas a M6. Se diferencia del flujo de reserva programada (`POST /camas/{camaId}/reservas`, invocado por M2) en cuatro aspectos: | Aspecto | Este webhook | `POST /camas/{camaId}/reservas` | |---------|--------------|----------------------------------| | Cama destino | M6 la elige automáticamente | La fija M2 en el path | | Prioridad | Siempre `URGENTE` | Cualquiera excepto `URGENTE` | | Desplazamiento de otras reservas | Sí, automático | No | | Quién lo invoca | M1 (HCE) exclusivamente | M2 (Turnos) exclusivamente | En otras palabras: **este webhook es el único camino por el que una reserva URGENTE puede entrar al sistema**, y es el único flujo que puede cancelar automáticamente a otras reservas ya confirmadas. ## Acciones que ejecuta este módulo 1. Busca quirófanos disponibles (sector=QUIROFANO, tipo=CIRUGIA, estado distinto de FUERA_DE_SERVICIO y BAJA_PERMANENTE) en el rango [`fecha_hora_inicio`, `fecha_hora_fin_estimada`]. 2. **Si hay algún quirófano libre (sin reservas superpuestas):** crea la reserva con `origen=EMERGENCIA`, `prioridad=URGENTE` y `estado=RESERVADA`. Responde `201`. 3. **Si todos los quirófanos del rango tienen reservas activas:** selecciona la reserva candidata a desplazar según el siguiente criterio: 1. Menor prioridad (`MUY_BAJA` antes que `BAJA`, etc.). Sólo se consideran reservas con prioridad menor a `URGENTE`. 2. Dentro de las de menor prioridad, la que tiene `fecha_hora_inicio` más cercana al momento actual. 3. Si hay empate, la de menor `id`. 4. La reserva elegida pasa a `estado=CANCELADA` con `desplazada_por_reserva_id` apuntando a la nueva reserva urgente. 5. **[EXT]** Si la reserva desplazada tiene `turno_id`, se notifica a M2 vía `POST /turnos/{turnoId}/resultado-quirofano` con `resultado=CANCELADA` y `motivo_cancelacion=DESPLAZADA_POR_URGENCIA`. 6. Se crea la nueva reserva urgente en el quirófano liberado con `origen=EMERGENCIA`, `prioridad=URGENTE` y `estado=RESERVADA`. Responde `201`. 7. **Si no existe ninguna reserva desplazable** (todas las reservas activas son también `URGENTE`, o no hay quirófanos en el sistema), responde `409 SIN_QUIROFANO_DISPONIBLE`. M1 es responsable de decidir el siguiente paso (reprogramar, derivar a otro hospital, etc.). ## Idempotencia El payload debe incluir `solicitud_urgencia_hce_id`. Si ya existe una reserva URGENTE creada con ese mismo `solicitud_urgencia_hce_id`, el endpoint responde `200` con la reserva ya existente en vez de crear una nueva. Esto protege frente a reintentos de M1. operationId: recibirCirugiaUrgente tags: - Webhooks Entrantes parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CirugiaUrgenteWebhook' example: solicitud_urgencia_hce_id: HCE-URG-00045 paciente_id: 123 medico_cirujano_id: 45 medico_solicitante_id: 78 fecha_hora_inicio: '2025-01-18T14:00:00Z' fecha_hora_fin_estimada: '2025-01-18T16:00:00Z' diagnostico: Apendicitis aguda con sospecha de perforación hospital_id: HOSP-001 timestamp: '2025-01-18T13:45:00Z' required: true responses: '200': description: La reserva ya existía (idempotencia por `solicitud_urgencia_hce_id`) content: application/json: schema: $ref: '#/components/schemas/CirugiaUrgenteResponse' headers: {} '201': description: Reserva urgente creada (con o sin desplazamiento) content: application/json: schema: $ref: '#/components/schemas/CirugiaUrgenteResponse' examples: sin_desplazamiento: summary: Había quirófano libre value: mensaje: Reserva urgente creada exitosamente reserva: id: 22 cama_id: 502 turno_id: null origen: EMERGENCIA estado: RESERVADA prioridad: URGENTE paciente_id: 123 medico_cirujano_id: 45 fecha_hora_inicio: '2025-01-18T14:00:00Z' fecha_hora_fin_estimada: '2025-01-18T16:00:00Z' observaciones: Cirugía urgente solicitada por HCE (HCE-URG-00045) desplazada_por_reserva_id: null created_at: '2025-01-18T13:46:00Z' reserva_desplazada: null con_desplazamiento: summary: Se canceló una reserva de menor prioridad value: mensaje: >- Reserva urgente creada. Se desplazó la reserva 15 (prioridad BAJA) para liberar el quirófano 501. reserva: id: 23 cama_id: 501 turno_id: null origen: EMERGENCIA estado: RESERVADA prioridad: URGENTE paciente_id: 123 medico_cirujano_id: 45 fecha_hora_inicio: '2025-01-18T14:00:00Z' fecha_hora_fin_estimada: '2025-01-18T16:00:00Z' observaciones: >- Cirugía urgente solicitada por HCE (HCE-URG-00045). Desplazó reserva 15. desplazada_por_reserva_id: null created_at: '2025-01-18T13:46:00Z' reserva_desplazada: reserva_id: 15 cama_id: 501 turno_id: 89 prioridad_original: BAJA notificado_a_m2: true headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '409': description: No se puede ubicar la cirugía urgente content: application/json: schema: $ref: '#/components/schemas/Error' examples: sin_quirofanos: summary: No hay quirófanos desplazables value: codigo: SIN_QUIROFANO_DISPONIBLE mensaje: >- No hay quirófanos disponibles y no existe reserva desplazable de menor prioridad detalle: >- Todas las reservas activas en el rango solicitado tienen prioridad URGENTE. M1 debe reprogramar o derivar el paciente. headers: {} '502': description: >- No se pudo notificar el desplazamiento a M2. La reserva urgente se creó igualmente; M2 quedará desincronizado hasta el próximo reintento. content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: SERVICIO_EXTERNO_NO_DISPONIBLE mensaje: No se pudo notificar a M2 la cancelación por desplazamiento detalle: >- La reserva urgente 23 fue creada correctamente; el turno 89 de M2 quedará pendiente de actualización. headers: {} security: - BearerAuth: [] /turnos/{turnoId}: get: summary: Obtener detalle de un turno quirúrgico deprecated: false description: > **Pertenece al Módulo 2 (Turnos).** Se consume al aprobar una solicitud con `origen=CIRUGIA_PROGRAMADA` para validar que el turno sigue vigente. **Mock 2da entrega:** responde HTTP 200 con datos ficticios. operationId: ext_getTurno tags: - '[EXT] Turnos - Módulo 2' parameters: - name: turnoId in: path description: Identificador del turno quirúrgico en M2 required: true example: 0 schema: type: integer example: 89 responses: '200': description: Turno encontrado content: application/json: schema: $ref: '#/components/schemas/Ext_Turno' example: id: 89 estado: CONFIRMADO paciente_id: 123 medico_cirujano_id: 45 fecha_hora_inicio: '2025-01-18T09:00:00Z' fecha_hora_fin_estimada: '2025-01-18T11:00:00Z' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Turno no encontrado en M2 content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] /turnos/{turnoId}/cancelacion-quirofano: post: summary: '[M2] Cancelar reserva de quirófano por turno' deprecated: false description: > Endpoint implementado por M6 para que M2 informe la cancelación o reprogramación de una cirugía programada. M2 es dueño del turno quirúrgico. M6 no cancela el turno: únicamente cancela la reserva física del quirófano asociada al `turnoId` y libera el recurso si corresponde. ## Comportamiento - Busca una reserva activa con `turno_id = turnoId` y `origen = PROGRAMADA`. - Si la reserva está `RESERVADA`, cambia su estado a `CANCELADA`. - Si la reserva ya está `EN_CURSO` o `COMPLETADA`, responde `409` porque no se puede cancelar por este flujo. - La operación debe ser idempotente: si la reserva ya estaba `CANCELADA`, puede responder `200` con el estado actual. ## Autorización Sólo M2 (Turnos). No hay rol humano con permiso para invocar este endpoint directamente desde M6. operationId: cancelarReservaQuirofanoPorTurno tags: - Webhooks Entrantes parameters: - name: turnoId in: path description: Identificador del turno quirúrgico en M2. required: true example: 0 schema: type: integer example: 89 requestBody: content: application/json: schema: $ref: '#/components/schemas/CancelacionQuirofanoRequest' example: motivo: Paciente canceló el turno quirúrgico tipo_cancelacion: CANCELACION_TURNO timestamp: '2025-01-19T14:00:00Z' required: true responses: '200': description: Reserva cancelada o ya se encontraba cancelada content: application/json: schema: $ref: '#/components/schemas/CancelacionQuirofanoResponse' example: mensaje: Reserva de quirófano cancelada correctamente reserva_id: 15 turno_id: 89 cama_id: 501 estado: CANCELADA headers: {} '400': description: Error de validación headers: {} '401': description: No autenticado headers: {} '403': description: No autorizado headers: {} '404': description: No existe una reserva programada asociada al turno content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RESERVA_NO_ENCONTRADA mensaje: No se encontró una reserva activa para el turno informado detalle: No existe reserva de quirófano asociada al turno 89 headers: {} '409': description: La reserva no puede cancelarse por este flujo content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RESERVA_NO_CANCELABLE mensaje: La reserva no puede cancelarse detalle: La reserva está EN_CURSO o COMPLETADA headers: {} security: - BearerAuth: [] /webhooks/monitoreo/alerta-emergencia: post: summary: '[M9] Recibir alerta de emergencia' deprecated: false description: > El Módulo 9 (Monitoreo) llama a este endpoint cuando detecta un código rojo en un paciente internado. La cama se resuelve internamente a partir del `paciente_id` (este módulo mantiene su propio registro de asignaciones activas). M9 **no necesita enviar** el `cama_id` en el payload. ## Acciones que ejecuta este módulo 1. Busca la cama actualmente asignada al `paciente_id` recibido. 2. Setea `estado=CODIGO_ROJO` en esa cama. > **Nota:** M9 es quien notifica al médico a cargo del paciente. Este módulo > no registra eventos adicionales ni llama a otros módulos al recibir la alerta. operationId: recibirAlertaEmergencia tags: - Webhooks Entrantes parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AlertaEmergenciaRequest' example: paciente_id: 123 timestamp: '2025-01-15T14:22:33Z' required: true responses: '200': description: Alerta recibida; cama marcada en CODIGO_ROJO content: application/json: schema: $ref: '#/components/schemas/AlertaEmergenciaResponse' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Paciente no encontrado o sin cama asignada actualmente content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Paciente no encontrado detalle: No existe paciente con ID 999 en este módulo headers: {} security: - BearerAuth: [] /webhooks/monitoreo/alerta-resuelta: post: summary: '[M9] Recibir alerta resuelta' deprecated: false description: | El Módulo 9 (Monitoreo) llama a este endpoint cuando una alerta de emergencia (código rojo) se resuelve: los signos vitales del paciente volvieron a parámetros normales. ## Acciones que ejecuta este módulo: 1. La cama pasa de `CODIGO_ROJO` a `OCUPADA` 2. Se registra la resolución en el historial de alertas 3. Se emite evento `ALERTA_RESUELTA` por WebSocket Si la cama no está en estado `CODIGO_ROJO`, responde 409. **Mock 2da entrega:** Endpoint local que cambia el estado de la cama. operationId: recibirAlertaResuelta tags: - Webhooks Entrantes parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AlertaResueltaRequest' example: paciente_id: 123 motivo_resolucion: Frecuencia cardíaca estabilizada en 78 bpm timestamp: '2025-01-15T14:45:00Z' required: true responses: '200': description: Alerta resuelta, cama volvió a estado OCUPADA content: application/json: schema: $ref: '#/components/schemas/AlertaResueltaResponse' example: mensaje: Alerta resuelta. Cama 204 volvió a estado OCUPADA. cama_id: 204 estado_anterior: CODIGO_ROJO estado_actual: OCUPADA headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado headers: {} '404': description: No se encontró cama en CODIGO_ROJO para el paciente content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Paciente no encontrado en código rojo detalle: No existe cama en estado CODIGO_ROJO para el paciente 123 headers: {} '409': description: La cama del paciente no está en CODIGO_ROJO content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] /hce/pacientes/{pacienteId}/contraindicaciones: get: summary: Consultar contraindicaciones de un paciente deprecated: false description: > **Pertenece al Módulo 1 (HCE).** Consulta informativa. El administrativo puede usarla para revisar las contraindicaciones del paciente antes de resolver una solicitud. La validación automática se hace contra `contraindicaciones_incompatibles` de la cama. operationId: ext_getContraindicaciones tags: - '[EXT] HCE - Módulo 1' parameters: - name: pacienteId in: path description: '' required: true example: 0 schema: type: integer example: 123 responses: '200': description: Resultado de la consulta content: application/json: schema: $ref: '#/components/schemas/Ext_Contraindicaciones' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Paciente sin historia clínica content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] /hce/pacientes/{pacienteId}: get: summary: Obtener detalle del paciente internado deprecated: false description: > **Pertenece al Módulo 1 (HCE).** Se consume para mostrar la información clínica y demográfica de un paciente que está actualmente internado en una cama. Devuelve datos de contacto, obra social, diagnósticos activos y medicación vigente, permitiéndole al personal ver el perfil completo del paciente sin salir del módulo de internación. operationId: ext_getPacienteHCE tags: - '[EXT] HCE - Módulo 1' parameters: - name: pacienteId in: path description: '' required: true example: 0 schema: type: integer example: 123 responses: '200': description: Detalle del paciente content: application/json: schema: $ref: '#/components/schemas/Ext_PacienteHCE' example: id: 123 nombre: Juan apellido: Pérez dni: '30123456' fecha_nacimiento: '1985-03-15' telefono: +54 11 1234-5678 obra_social_id: OSDE-310 numero_afiliado: '123456789' grupo_sanguineo: A+ diagnosticos_activos: - codigo: J18.9 descripcion: Neumonía, no especificada fecha_inicio: '2025-01-10' medicacion_vigente: - nombre: Amoxicilina 500mg dosis: 1 comprimido cada 8hs via: oral headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Paciente no encontrado en HCE content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Paciente no encontrado detalle: No existe historia clínica para el paciente 999 headers: {} security: - BearerAuth: [] /hce/movimientos: post: summary: Registrar movimiento de paciente en HCE (endpoint unificado) deprecated: false description: > **Pertenece al Módulo 1 (HCE).** Endpoint unificado para notificar a HCE todos los movimientos de pacientes y resultados de solicitudes. M1 persiste el movimiento en la historia clínica y notifica al médico a cargo cuando corresponde. | `tipo_movimiento` | Cuándo se usa | |-------------------|---------------| | `INGRESO` | Al aprobar una internación o al ingresar directamente un paciente | | `TRASLADO` | Al aprobar un traslado o al trasladar directamente | | `ALTA` | Al procesar el alta médica | | `RESOLUCION_SOLICITUD` | Al rechazar una solicitud (sin movimiento físico) | operationId: ext_registrarMovimiento tags: - '[EXT] HCE - Módulo 1' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/Ext_MovimientoRequest' examples: ingreso: value: tipo_movimiento: INGRESO paciente_id: 123 cama_id: 315 solicitud_hce_id: HCE-SOL-00789 resultado: APROBADA medico_responsable_id: MED-0045 timestamp: '2025-01-15T10:30:00Z' summary: Notificar ingreso aprobado traslado: value: tipo_movimiento: TRASLADO paciente_id: 123 cama_id: 315 cama_origen_id: 204 solicitud_hce_id: HCE-SOL-00790 resultado: APROBADA medico_responsable_id: MED-0045 timestamp: '2025-01-17T10:00:00Z' summary: Notificar traslado aprobado alta: value: tipo_movimiento: ALTA paciente_id: 123 cama_id: 204 timestamp: '2025-01-20T11:00:00Z' summary: Notificar alta médica rechazo: value: tipo_movimiento: RESOLUCION_SOLICITUD paciente_id: 123 solicitud_hce_id: HCE-SOL-00789 resultado: RECHAZADA motivo: No hay disponibilidad en el sector solicitado timestamp: '2025-01-15T09:00:00Z' summary: Notificar solicitud rechazada required: true responses: '200': description: Movimiento registrado en HCE content: application/json: schema: type: object properties: mensaje: type: string example: Movimiento registrado en historia clínica del paciente movimiento_id: type: string example: MOV-HCE-00456 headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Paciente no encontrado en HCE content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Paciente no encontrado detalle: No existe historia clínica para el paciente 999 headers: {} security: - BearerAuth: [] /hce/episodios/{episodioId}/eventos: post: summary: Registrar evento en episodio de internación (HCE) deprecated: false description: > **Pertenece al Módulo 1 (HCE).** Se consume para registrar eventos en el episodio de internación (alertas, resoluciones, cambios clínicos). M1 persiste el evento y notifica al equipo médico cuando corresponde. **Mock 2da entrega:** responde HTTP 200. operationId: ext_registrarEventoEpisodio tags: - '[EXT] HCE - Módulo 1' parameters: - name: episodioId in: path description: Identificador del episodio de internación en HCE required: true example: 0 schema: type: integer example: 456 requestBody: content: application/json: schema: $ref: '#/components/schemas/Ext_EventoEpisodioRequest' example: tipo_evento: CODIGO_ROJO descripcion: Alerta de emergencia detectada por Monitoreo (M9) timestamp: '2025-01-15T14:22:33Z' required: true responses: '200': description: Evento registrado en HCE content: application/json: schema: type: object properties: mensaje: type: string example: Evento registrado en el episodio de internación evento_id: type: string example: EVT-HCE-00789 headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Episodio no encontrado en HCE content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] /turnos/{turnoId}/resultado-quirofano: post: summary: Notificar cancelación por desplazamiento a Turnos deprecated: false description: > **Pertenece al Módulo 2 (Turnos).** M6 invoca este endpoint **únicamente cuando una cirugía urgente recibida por `/webhooks/hce/cirugia-urgente` desplazó automáticamente a una reserva programada de menor prioridad**. No se usa para ningún otro escenario de cancelación: - Si M2 cancela un turno, M2 ya lo sabe: no hace falta que M6 le informe. - M6 no puede cancelar reservas por decisión propia (no existe ese flujo). M2 usa esta notificación para actualizar el estado del turno correspondiente, avisar al paciente y decidir si reprograma. **Mock 2da entrega:** Endpoint local que responde HTTP 200. operationId: ext_notificarResultadoQuirofano tags: - '[EXT] Turnos - Módulo 2' parameters: - name: turnoId in: path description: '' required: true example: 0 schema: type: integer example: 89 requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookResultadoQuirofano' examples: cancelacion_manual: value: resultado: CANCELADA reserva_id: 15 cama_id: 501 motivo_cancelacion: DESPLAZADA_POR_URGENCIA reserva_urgente_id: 23 motivo: Apendicitis aguda con sospecha de perforación timestamp: '2025-01-18T13:46:00Z' summary: Cancelación manual desde M6 desplazada_por_urgencia: value: resultado: CANCELADA reserva_id: 15 cama_id: 501 motivo_cancelacion: DESPLAZADA_POR_URGENCIA reserva_urgente_id: 23 motivo: Apendicitis aguda con sospecha de perforación timestamp: '2025-01-18T13:46:00Z' summary: Cancelación automática por cirugía urgente required: true responses: '200': description: M2 confirmó la recepción content: application/json: schema: type: object properties: mensaje: type: string example: Resultado de quirófano recibido headers: {} '401': description: No autenticado headers: {} '404': description: Turno no encontrado en M2 content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} security: - BearerAuth: [] /webhooks/internacion/cama-lista: post: summary: Notificar cama lista (dispara liquidación) deprecated: false description: > **Pertenece al Módulo 7 (Facturación).** Se llama cuando el personal de limpieza marca la cama como `DISPONIBLE` (transición `EN_LIMPIEZA` → `DISPONIBLE` post-alta médica) para iniciar la liquidación de prestaciones. El payload incluye los datos del episodio necesarios para facturar: obra social, historial de camas con timestamps, diagnósticos, etc. > **Nota:** se dispara al completar la limpieza, **no** al recibir el alta médica. El alta pone la cama en `EN_LIMPIEZA`; el webhook a > Facturación se dispara cuando limpieza la marca `DISPONIBLE`. operationId: ext_notificarCamaLista tags: - '[EXT] Facturación - Módulo 7' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookCamaLista' required: true responses: '200': description: Facturación confirmó la recepción content: application/json: schema: type: object properties: mensaje: type: string example: Datos de episodio recibidos para liquidación liquidacion_id: type: string description: ID de la liquidación creada (opcional) example: LIQ-2025-00123 headers: {} '400': $ref: '#/components/responses/ErrorValidacion' description: Error de validación en el body de la request '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado security: - BearerAuth: [] /webhooks/internacion/baja-monitoreo: post: summary: Notificar baja de monitoreo de paciente deprecated: false description: | **Pertenece al Módulo 9 (Monitoreo).** Se llama al procesar el alta médica para indicar al módulo de monitoreo que deje de monitorear al paciente dado de alta. operationId: ext_notificarBajaMonitoreo tags: - '[EXT] Monitoreo - Módulo 9' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookBajaMonitoreo' required: true responses: '200': description: Monitoreo confirmó la baja content: application/json: schema: type: object properties: mensaje: type: string example: Monitoreo del paciente 123 dado de baja headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Paciente no estaba siendo monitoreado content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Paciente no monitoreado detalle: El paciente 123 no tiene monitoreo activo headers: {} security: - BearerAuth: [] /webhooks/internacion/alta-monitoreo: post: summary: Notificar inicio de monitoreo de paciente deprecated: false description: > **Pertenece al Módulo 9 (Monitoreo).** Se llama al ingresar un paciente (aprobación de internación o asignación directa) para que M9 inicie el monitoreo. **No** se llama en traslados: el monitoreo sigue al paciente, no a la cama. operationId: ext_notificarAltaMonitoreo tags: - '[EXT] Monitoreo - Módulo 9' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookAltaMonitoreo' example: evento: ALTA_MONITOREO paciente_id: 123 timestamp: '2025-01-15T10:30:00Z' required: true responses: '200': description: Monitoreo confirmó el inicio de seguimiento content: application/json: schema: type: object properties: mensaje: type: string example: Monitoreo del paciente 123 iniciado headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Paciente no encontrado en el sistema de monitoreo content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Paciente no encontrado detalle: No existe paciente con ID 999 en el sistema de monitoreo headers: {} security: - BearerAuth: [] /auth/token: get: summary: Obtener JWT a partir de credenciales deprecated: false description: | **Pertenece al Módulo 10 (Core).** Devuelve un `access_token` (JWT) y un `refresh_token` a partir de las credenciales del usuario. operationId: ext_authToken tags: - '[EXT] Core - Módulo 10' parameters: - name: usuario in: query description: '' required: true schema: type: string example: admin01 - name: password in: query description: '' required: true schema: type: string format: password example: '********' responses: '200': description: Credenciales válidas content: application/json: schema: $ref: '#/components/schemas/Ext_AuthTokenResponse' headers: {} '401': description: Credenciales inválidas content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: NO_AUTENTICADO mensaje: Credenciales inválidas detalle: Usuario o contraseña incorrectos headers: {} security: [] /auth/refresh: get: summary: Renovar JWT a partir de un refresh token deprecated: false description: | **Pertenece al Módulo 10 (Core).** Emite un nuevo `access_token` a partir de un `refresh_token` válido. operationId: ext_authRefresh tags: - '[EXT] Core - Módulo 10' parameters: - name: refresh_token in: query description: '' required: true schema: type: string example: rft_8f4c6a... responses: '200': description: Token renovado content: application/json: schema: $ref: '#/components/schemas/Ext_AuthTokenResponse' headers: {} '401': description: Refresh token inválido o expirado content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: NO_AUTENTICADO mensaje: Refresh token inválido o expirado headers: {} security: [] /auth/validate-token: post: summary: Validar y decodificar un JWT deprecated: false description: > **Pertenece al Módulo 10 (Core).** Valida la firma y expiración de un JWT y devuelve los claims del usuario (id, rol, hospital_id). Usado como middleware de autenticación en cada request entrante a M6. **Mock 2da entrega:** responde HTTP 200 con claims ficticios. operationId: ext_validateToken tags: - '[EXT] Core - Módulo 10' parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/Ext_ValidateTokenRequest' example: token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... required: true responses: '200': description: Token válido. Devuelve los claims del usuario. content: application/json: schema: type: object properties: valid: type: boolean example: true user_id: type: integer example: 10 rol: type: string example: ADMINISTRATIVO hospital_id: type: string example: HOSP-001 headers: {} '401': description: Token inválido, expirado o malformado content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: NO_AUTENTICADO mensaje: Token JWT inválido o expirado headers: {} security: [] /usuarios/{pacienteId}: get: summary: Obtener datos básicos del usuario/paciente deprecated: false description: | **Pertenece al Módulo 10 (Core).** Devuelve los datos básicos del usuario/paciente identificado por `pacienteId`. operationId: ext_getPaciente tags: - '[EXT] Core - Módulo 10' parameters: - name: pacienteId in: path description: '' required: true example: 0 schema: type: integer example: 123 responses: '200': description: Usuario encontrado content: application/json: schema: $ref: '#/components/schemas/Ext_Paciente' headers: {} '401': $ref: '#/components/responses/NoAutenticado' description: Token JWT ausente, expirado o malformado '404': description: Usuario no encontrado en el sistema content: application/json: schema: $ref: '#/components/schemas/Error' example: codigo: RECURSO_NO_ENCONTRADO mensaje: Usuario no encontrado detalle: No existe usuario con ID 999 headers: {} security: - BearerAuth: [] components: schemas: EstadoSolicitudEnum: type: string enum: - PENDIENTE - APROBADA - RECHAZADA TipoSolicitudEnum: type: string enum: - INTERNACION - TRASLADO AccionResolucionEnum: type: string enum: - APROBAR - APROBAR_CON_CAMBIO - RECHAZAR PrioridadSolicitudEnum: type: string enum: - BAJA - MEDIA - ALTA - URGENTE Cama: type: object properties: id: type: integer example: 204 numero: type: string example: '204' piso: type: integer example: 2 sector: $ref: '#/components/schemas/SectorEnum' tipo: $ref: '#/components/schemas/TipoCamaEnum' specialty_id: type: integer description: >- ID de la especialidad quirúrgica asociada a este quirófano (referencia al `id` de M2). Solo aplica cuando `tipo=CIRUGIA`. Para todos los demás tipos de cama este campo es `null`. nullable: true example: 43 estado: $ref: '#/components/schemas/EstadoCamaEnum' paciente_id: type: integer nullable: true example: 123 hospital_id: type: string example: HOSP-001 contraindicaciones_incompatibles: type: array items: type: string example: - ALERGIA_LATEX ultima_actualizacion: type: string format: date-time example: '2025-01-15T10:30:00Z' CamaUpdateRequest: type: object properties: estado: $ref: '#/components/schemas/EstadoCamaEnum' contraindicaciones_incompatibles: type: array items: type: string CamaCreateRequest: type: object required: - numero - piso - sector - tipo - hospital_id properties: numero: type: string example: '210' piso: type: integer example: 2 sector: $ref: '#/components/schemas/SectorEnum' tipo: $ref: '#/components/schemas/TipoCamaEnum' specialty_id: type: integer description: >- Requerido si `tipo=CIRUGIA`. ID de la especialidad quirúrgica del quirófano, obtenido de M2 (`GET /specialties?is_high_complexity=1`). Ignorado si `tipo` no es `CIRUGIA`. nullable: true example: 43 hospital_id: type: string example: HOSP-001 contraindicaciones_incompatibles: type: array items: type: string example: - ALERGIA_LATEX Solicitud: type: object properties: id: type: string example: SOL-00123 solicitud_hce_id: type: string example: HCE-SOL-00789 tipo: $ref: '#/components/schemas/TipoSolicitudEnum' estado: $ref: '#/components/schemas/EstadoSolicitudEnum' paciente_id: type: integer example: 123 medico_solicitante_id: type: integer example: 45 cama_solicitada_id: type: integer nullable: true example: 204 cama_asignada_id: type: integer nullable: true example: 204 origen: $ref: '#/components/schemas/OrigenIngresoEnum' turno_id: type: integer nullable: true example: null diagnostico_ingreso: type: string nullable: true example: Insuficiencia respiratoria aguda obra_social_id: type: string nullable: true example: OSDE-310 numero_afiliado: type: string nullable: true example: '123456789' prioridad: $ref: '#/components/schemas/PrioridadSolicitudEnum' cama_origen_id: type: integer nullable: true example: null cama_destino_solicitada_id: type: integer nullable: true example: null motivo_traslado: type: string nullable: true example: null accion: allOf: - $ref: '#/components/schemas/AccionResolucionEnum' nullable: true description: Acción tomada al resolver. Null mientras la solicitud esté PENDIENTE. motivo: type: string nullable: true example: null resuelto_por: type: integer nullable: true example: null observaciones: type: string nullable: true example: Paciente requiere monitoreo continuo timestamp_solicitud: type: string format: date-time timestamp_resolucion: type: string format: date-time nullable: true SolicitudesListResponse: type: object properties: total: type: integer example: 5 solicitudes: type: array items: $ref: '#/components/schemas/Solicitud' SolicitudResolucionRequest: type: object required: - accion properties: accion: $ref: '#/components/schemas/AccionResolucionEnum' cama_asignada_id: type: integer description: Requerido si accion=APROBAR_CON_CAMBIO example: 312 motivo: type: string description: Requerido si accion=RECHAZAR o APROBAR_CON_CAMBIO example: No hay disponibilidad en el sector solicitado AltaMedicaWebhook: type: object required: - paciente_id - medico_firmante_id - tipo_alta - timestamp properties: paciente_id: type: integer medico_firmante_id: type: integer tipo_alta: $ref: '#/components/schemas/TipoAltaEnum' timestamp: type: string format: date-time AsignacionCamaRequest: type: object required: - tipo - paciente_id properties: tipo: type: string enum: - INGRESO - TRASLADO paciente_id: type: integer example: 123 cama_origen_id: type: integer description: Requerido si tipo=TRASLADO nullable: true example: 204 AsignacionCamaResponse: type: object properties: mensaje: type: string example: Paciente 123 asignado a la cama 315 cama_id: type: integer example: 315 paciente_id: type: integer example: 123 tipo: type: string example: INGRESO cama_origen_id: type: integer nullable: true example: null timestamp: type: string format: date-time AlertaEmergenciaRequest: type: object description: > Payload mínimo que envía M9 al detectar un código rojo. M9 resuelve internamente el detalle clínico (tipo de alerta, parámetros, valores) y notifica al médico a cargo. M6 sólo necesita identificar al paciente para poner su cama en `CODIGO_ROJO`. required: - paciente_id - timestamp properties: paciente_id: type: integer example: 123 observaciones: type: string description: Texto libre opcional con contexto clínico de la alerta. nullable: true timestamp: type: string format: date-time example: '2025-01-15T14:22:33Z' AlertaEmergenciaResponse: type: object properties: mensaje: type: string example: Alerta registrada. Cama 204 en CODIGO_ROJO. Enfermería notificada. cama_id: type: integer example: 204 sector: type: string example: UTI WebhookCamaLista: type: object description: | Enviado a M7 (Facturación) cuando limpieza completa la cama post-alta. properties: evento: type: string example: CAMA_LISTA cama_id: type: integer example: 204 paciente_id: type: integer example: 123 obra_social_id: type: string nullable: true example: OSDE-310 numero_afiliado: type: string nullable: true example: '123456789' tipo_alta: $ref: '#/components/schemas/TipoAltaEnum' fecha_ingreso: type: string format: date-time fecha_alta: type: string format: date-time fecha_limpieza_completada: type: string format: date-time diagnostico_ingreso: type: string diagnostico_egreso: type: string camas_utilizadas: type: array items: type: object properties: cama_id: type: integer sector: type: string desde: type: string format: date-time hasta: type: string format: date-time timestamp_evento: type: string format: date-time WebhookBajaMonitoreo: type: object description: > Enviado a M9 (Monitoreo) para que deje de monitorear a un paciente. Se dispara al procesar el alta médica. No se envía `cama_id`: el monitoreo está asociado al paciente, no a la cama. required: - evento - paciente_id - timestamp properties: evento: type: string enum: - BAJA_MONITOREO example: BAJA_MONITOREO paciente_id: type: integer example: 123 timestamp: type: string format: date-time example: '2025-01-20T11:00:00Z' WebhookAltaMonitoreo: type: object description: > Enviado a M9 (Monitoreo) para iniciar el seguimiento de un paciente. Se dispara al ingresar un paciente (aprobación de internación o asignación directa). No se envía en traslados: el monitoreo sigue al paciente, no a la cama. No se envía `cama_id` por el mismo motivo. required: - evento - paciente_id - timestamp properties: evento: type: string enum: - ALTA_MONITOREO example: ALTA_MONITOREO paciente_id: type: integer example: 123 timestamp: type: string format: date-time example: '2025-01-15T10:30:00Z' Ext_PacienteHCE: type: object description: '[EXT] Detalle del paciente en HCE (Módulo 1)' properties: id: type: integer example: 123 nombre: type: string apellido: type: string contraindicaciones: type: array items: type: string Ext_MovimientoRequest: type: object description: '[EXT] Payload para registrar movimiento en HCE (M1)' properties: tipo_movimiento: type: string enum: - INGRESO - TRASLADO - ALTA - RESOLUCION_SOLICITUD paciente_id: type: integer example: 123 cama_id: type: integer nullable: true example: 204 cama_origen_id: type: integer nullable: true solicitud_hce_id: type: string description: ID de la solicitud en HCE. Presente en INGRESO, TRASLADO y RESOLUCION_SOLICITUD. nullable: true example: HCE-SOL-00789 resultado: type: string description: 'Para RESOLUCION_SOLICITUD: APROBADA o RECHAZADA' nullable: true medico_responsable_id: type: integer description: ID del médico responsable del movimiento. nullable: true example: 45 motivo: type: string nullable: true timestamp: type: string format: date-time Ext_Paciente: type: object description: '[EXT] Respuesta del Módulo 10 (Core)' properties: id: type: integer example: 123 nombre: type: string example: Juan apellido: type: string example: Pérez dni: type: string example: '30123456' fecha_nacimiento: type: string format: date example: '1985-03-15' email: type: string example: juan.perez@email.com telefono: type: string example: +54 11 1234-5678 Ext_Contraindicaciones: type: object description: '[EXT] Respuesta del Módulo 1 (HCE)' properties: paciente_id: type: integer example: 123 tiene_contraindicaciones: type: boolean example: false detalle: type: array items: type: object properties: tipo: type: string enum: - ALERGIA - MEDICAMENTO_CONTRAINDICADO - CONDICION_PREVIA descripcion: type: string example: Alergia severa a penicilina severidad: type: string enum: - LEVE - MODERADA - SEVERA Error: type: object required: - codigo - mensaje properties: codigo: type: string example: NO_AUTENTICADO mensaje: type: string example: No Autenticado detalle: type: string nullable: true SolicitudHceWebhook: type: object description: Payload unificado que envía HCE (M1) para solicitudes required: - tipo - solicitud_hce_id - paciente_id - medico_solicitante_id - timestamp properties: tipo: $ref: '#/components/schemas/TipoSolicitudEnum' solicitud_hce_id: type: string example: HCE-SOL-00789 paciente_id: type: integer example: 123 medico_solicitante_id: type: integer example: 45 cama_solicitada_id: type: integer description: '[INTERNACION] Cama solicitada' nullable: true example: 204 origen: $ref: '#/components/schemas/OrigenIngresoEnum' turno_id: type: integer nullable: true example: null diagnostico_ingreso: type: string nullable: true example: Insuficiencia respiratoria aguda obra_social_id: type: string nullable: true example: OSDE-310 numero_afiliado: type: string nullable: true example: '123456789' prioridad: $ref: '#/components/schemas/PrioridadSolicitudEnum' observaciones: type: string nullable: true cama_origen_id: type: integer description: '[TRASLADO] Cama actual del paciente' nullable: true cama_destino_solicitada_id: type: integer description: '[TRASLADO] Cama destino solicitada' nullable: true motivo_traslado: type: string description: '[TRASLADO] Motivo' nullable: true timestamp: type: string format: date-time Ext_AuthTokenResponse: type: object description: '[EXT] Respuesta de login/refresh del Módulo 10 (Core)' properties: access_token: type: string refresh_token: type: string token_type: type: string example: bearer expires_in: type: integer example: 3600 SectorEnum: type: string enum: - UTI - SALA_COMUN - QUIROFANO - GUARDIA - NEONATOLOGIA TipoCamaEnum: type: string enum: - ESTANDAR - PEDIATRICA - AISLAMIENTO - CRITICA - CIRUGIA description: | Tipo de cama según equipamiento. `CIRUGIA` solo aplica a camas con sector=QUIROFANO (mesas quirúrgicas). EstadoCamaEnum: type: string enum: - DISPONIBLE - OCUPADA - EN_LIMPIEZA - FUERA_DE_SERVICIO - BAJA_PERMANENTE - CODIGO_ROJO OrigenIngresoEnum: type: string enum: - GUARDIA - CIRUGIA_PROGRAMADA TipoAltaEnum: type: string enum: - ALTA_MEDICA - ALTA_VOLUNTARIA - TRASLADO_EXTERNO - DEFUNCION AlertaResueltaRequest: type: object required: - paciente_id - timestamp properties: paciente_id: type: integer example: 123 motivo_resolucion: type: string nullable: true example: Frecuencia cardíaca estabilizada en 78 bpm timestamp: type: string format: date-time AlertaResueltaResponse: type: object properties: mensaje: type: string example: Alerta resuelta. Cama 204 volvió a estado OCUPADA. cama_id: type: integer example: 204 estado_anterior: type: string example: CODIGO_ROJO estado_actual: type: string example: OCUPADA WebhookResultadoQuirofano: type: object description: >- Enviado a M2 (Turnos) cuando M6 cancela automáticamente una reserva programada para liberar el quirófano ante una cirugía urgente recibida por `/webhooks/hce/cirugia-urgente`. Es el único caso en que M6 avisa a M2 sobre cancelaciones: cuando M2 cancela un turno, M2 ya lo sabe y no necesita ser notificado por M6. required: - resultado - motivo_cancelacion - reserva_id - cama_id - reserva_urgente_id - timestamp properties: resultado: type: string enum: - CANCELADA example: CANCELADA reserva_id: type: integer description: ID de la reserva que fue cancelada. example: 15 cama_id: type: integer description: Quirófano donde estaba la reserva cancelada. example: 501 motivo_cancelacion: type: string description: > Clasificación de la causa. Actualmente sólo existe el caso `DESPLAZADA_POR_URGENCIA` porque ése es el único escenario en que M6 inicia una cancelación. Se mantiene como enum para permitir extensiones futuras sin romper contrato. enum: - DESPLAZADA_POR_URGENCIA example: DESPLAZADA_POR_URGENCIA reserva_urgente_id: type: integer description: > ID de la reserva urgente creada por M6 que desplazó a esta. Permite a M2 correlacionar ambos turnos si lo necesita. example: 23 motivo: type: string description: > Texto libre complementario. Puede contener el diagnóstico de la urgencia que motivó el desplazamiento. nullable: true example: Apendicitis aguda con sospecha de perforación timestamp: type: string format: date-time ReservaQuirofanoCreateRequest: type: object required: - turno_id - paciente_id - medico_cirujano_id - fecha_hora_inicio - fecha_hora_fin_estimada - prioridad properties: turno_id: type: integer description: >- ID del turno quirúrgico en M2 (appointment_id). Obligatorio: este endpoint sólo recibe reservas programadas provenientes de M2. Las emergencias entran por `POST /webhooks/hce/cirugia-urgente`. example: 89 paciente_id: type: integer example: 123 medico_cirujano_id: type: integer example: 45 fecha_hora_inicio: type: string format: date-time example: '2025-01-18T09:00:00Z' fecha_hora_fin_estimada: type: string format: date-time example: '2025-01-18T11:00:00Z' prioridad: allOf: - $ref: '#/components/schemas/PrioridadQuirofanoEnum' description: > Prioridad clínica de la reserva, determinada por M2 al confirmar el turno. Acepta cualquier valor de `PrioridadQuirofanoEnum` **excepto `URGENTE`**: ese valor está reservado exclusivamente para el flujo automático de `/webhooks/hce/cirugia-urgente` y permite al sistema decidir si desplaza o no a otra reserva. observaciones: type: string nullable: true example: Colecistectomía laparoscópica programada description: | Datos necesarios para crear una reserva de quirófano programada. Todas las reservas creadas por este endpoint tienen `origen=PROGRAMADA` y provienen de M2 (Turnos). No existe un flujo manual para crear reservas desde M6. ReservaEstadoUpdateRequest: type: object required: - estado properties: estado: type: string enum: - EN_CURSO - COMPLETADA - CANCELADA observaciones: type: string nullable: true ReservaQuirofanoResponse: type: object required: - id - cama_id - origen - estado - prioridad - paciente_id - medico_cirujano_id - fecha_hora_inicio - fecha_hora_fin_estimada - created_at properties: id: type: integer example: 15 cama_id: type: integer example: 501 turno_id: type: integer nullable: true example: 89 origen: type: string enum: - PROGRAMADA - EMERGENCIA example: PROGRAMADA estado: type: string enum: - RESERVADA - EN_CURSO - COMPLETADA - CANCELADA example: RESERVADA prioridad: $ref: '#/components/schemas/PrioridadQuirofanoEnum' paciente_id: type: integer example: 123 medico_cirujano_id: type: integer example: 45 fecha_hora_inicio: type: string format: date-time example: '2025-01-18T09:00:00Z' fecha_hora_fin_estimada: type: string format: date-time example: '2025-01-18T11:00:00Z' observaciones: type: string nullable: true example: Colecistectomía laparoscópica programada desplazada_por_reserva_id: type: integer description: > Si la reserva fue cancelada automáticamente para liberar el quirófano ante una cirugía urgente, este campo indica el ID de la reserva urgente que la desplazó. Sólo se completa cuando `estado=CANCELADA` y el motivo fue un desplazamiento automático. nullable: true example: null created_at: type: string format: date-time example: '2025-01-18T08:55:00Z' CancelacionQuirofanoRequest: type: object required: - motivo - timestamp properties: motivo: type: string example: Paciente canceló el turno quirúrgico tipo_cancelacion: type: string enum: - CANCELACION_TURNO - REPROGRAMACION_TURNO - OTRO nullable: true example: CANCELACION_TURNO timestamp: type: string format: date-time example: '2025-01-19T14:00:00Z' CancelacionQuirofanoResponse: type: object properties: mensaje: type: string example: Reserva de quirófano cancelada correctamente reserva_id: type: integer example: 15 turno_id: type: integer example: 89 cama_id: type: integer example: 501 estado: type: string enum: - CANCELADA example: CANCELADA PrioridadQuirofanoEnum: type: string description: > Prioridad clínica de una reserva de quirófano. Ordenada de menor a mayor importancia. | Nivel | Uso típico | |-------|-----------| | `MUY_BAJA` | Procedimientos estéticos o diferibles sin impacto clínico | | `BAJA` | Cirugías programadas de baja complejidad, pacientes estables | | `MEDIA` | Cirugías programadas estándar | | `ALTA` | Cirugías programadas con riesgo clínico relevante si se posponen | | `MUY_ALTA` | Cirugías programadas que no pueden postergarse más de 24hs | | `URGENTE` | Cirugía de emergencia con riesgo vital | **Quién la asigna:** - M2 (Turnos) elige la prioridad al crear una reserva programada vía `POST /camas/{camaId}/reservas`. Puede usar cualquier valor **excepto `URGENTE`**. - `URGENTE` lo asigna M6 automáticamente cuando recibe una cirugía urgente por `/webhooks/hce/cirugia-urgente`. Ningún rol humano ni cliente HTTP puede asignar `URGENTE` desde otro endpoint. **Regla de desplazamiento:** una reserva `URGENTE` entrante puede desplazar automáticamente a otra reserva en estado `RESERVADA` de prioridad estrictamente menor. El criterio de elección es "menor prioridad y más cercana al horario requerido". Nunca se desplaza una reserva en estado `EN_CURSO` o `COMPLETADA`. enum: - MUY_BAJA - BAJA - MEDIA - ALTA - MUY_ALTA - URGENTE CirugiaUrgenteWebhook: type: object description: > Payload que envía HCE (M1) para solicitar un quirófano de forma urgente. A diferencia de una reserva programada, no se especifica cama destino: M6 decide qué quirófano utilizar y si desplaza o no una reserva de menor prioridad. required: - solicitud_urgencia_hce_id - paciente_id - medico_cirujano_id - medico_solicitante_id - fecha_hora_inicio - fecha_hora_fin_estimada - diagnostico - timestamp properties: solicitud_urgencia_hce_id: type: string description: > Identificador único de la solicitud de urgencia en HCE. Usado para idempotencia: si llega dos veces el mismo id, M6 devuelve la reserva ya creada sin duplicar. example: HCE-URG-00045 paciente_id: type: integer example: 123 medico_cirujano_id: type: integer description: Médico que ejecutará la cirugía. example: 45 medico_solicitante_id: type: integer description: > Médico que solicita la cirugía desde HCE (puede ser distinto del cirujano). example: 78 fecha_hora_inicio: type: string format: date-time example: '2025-01-18T14:00:00Z' fecha_hora_fin_estimada: type: string format: date-time example: '2025-01-18T16:00:00Z' diagnostico: type: string example: Apendicitis aguda con sospecha de perforación hospital_id: type: string description: > Hospital donde se requiere el quirófano. Si se omite, M6 evalúa todos los hospitales del sistema. nullable: true example: HOSP-001 observaciones: type: string nullable: true timestamp: type: string format: date-time description: Momento en que M1 disparó el webhook. example: '2025-01-18T13:45:00Z' CirugiaUrgenteResponse: type: object description: > Respuesta al webhook de cirugía urgente. Informa si hubo desplazamiento de una reserva existente y los datos de la nueva reserva creada. required: - mensaje - reserva properties: mensaje: type: string example: Reserva urgente creada exitosamente reserva: $ref: '#/components/schemas/ReservaQuirofanoResponse' reserva_desplazada: type: object description: > Presente sólo si se canceló una reserva de menor prioridad para ubicar la cirugía urgente. `null` si había quirófano libre. properties: reserva_id: type: integer example: 15 cama_id: type: integer example: 501 turno_id: type: integer description: >- Si la reserva desplazada tenía turno asociado en M2, aparece acá (es el appointment_id de M2). Indica que se disparó la notificación a M2. nullable: true example: 89 prioridad_original: $ref: '#/components/schemas/PrioridadQuirofanoEnum' notificado_a_m2: type: boolean description: > `true` si la reserva desplazada tenía turno y se pudo notificar a M2. `false` si no tenía turno o si la notificación falló (igual así la reserva urgente se creó). example: true nullable: true ErrorValidacion: type: object required: - codigo - mensaje - errores properties: codigo: type: string example: ERROR_VALIDACION mensaje: type: string example: Error de validación en los datos enviados errores: type: array items: type: object required: - campo - mensaje properties: campo: type: string example: paciente_id mensaje: type: string example: El campo es requerido CamaMapaResponse: type: object description: Respuesta del mapa completo de camas con estadísticas agregadas properties: total: type: integer example: 50 disponibles: type: integer example: 12 ocupadas: type: integer example: 30 en_limpieza: type: integer example: 5 fuera_de_servicio: type: integer example: 2 codigo_rojo: type: integer example: 1 camas: type: array items: $ref: '#/components/schemas/Cama' Ext_Turno: type: object description: '[EXT] Detalle de un turno quirúrgico en M2 (Turnos)' properties: id: type: integer example: 89 estado: type: string enum: - CONFIRMADO - PENDIENTE - CANCELADO - COMPLETADO example: CONFIRMADO paciente_id: type: integer example: 123 medico_cirujano_id: type: integer example: 45 fecha_hora_inicio: type: string format: date-time example: '2025-01-18T09:00:00Z' fecha_hora_fin_estimada: type: string format: date-time example: '2025-01-18T11:00:00Z' specialty_id: type: integer nullable: true example: 43 observaciones: type: string nullable: true Ext_EventoEpisodioRequest: type: object description: '[EXT] Payload para registrar un evento en un episodio de internación (HCE M1)' required: - tipo_evento - timestamp properties: tipo_evento: type: string description: Tipo de evento clínico a registrar example: CODIGO_ROJO descripcion: type: string description: Descripción libre del evento nullable: true example: Alerta de emergencia detectada por Monitoreo (M9) timestamp: type: string format: date-time example: '2025-01-15T14:22:33Z' Ext_ValidateTokenRequest: type: object description: '[EXT] Payload para validar un JWT en el Módulo 10 (Core)' required: - token properties: token: type: string description: JWT a validar example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... responses: NoAutenticado: description: Token JWT ausente, expirado o malformado content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: codigo: NO_AUTENTICADO mensaje: No Autenticado detalle: >- No se proporcionó token de autenticación en el header Authorization NoAutorizado: description: El rol del usuario no tiene permisos para esta acción content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: codigo: NO_AUTORIZADO mensaje: No Autorizado detalle: >- El usuario MED-0045 con rol MEDICO no tiene permiso para ejecutar esta acción CamaNoEncontrada: description: Cama no encontrada content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: codigo: RECURSO_NO_ENCONTRADO mensaje: Cama no encontrada detalle: No existe cama con ID 999 SolicitudNoEncontrada: description: Solicitud no encontrada content: application/json: schema: $ref: '#/components/schemas/Error' examples: Success: summary: Success value: codigo: RECURSO_NO_ENCONTRADO mensaje: Solicitud no encontrada detalle: No existe solicitud con ID SOL-99999 ErrorValidacion: description: Error de validación en el body de la request content: application/json: schema: $ref: '#/components/schemas/ErrorValidacion' examples: Success: summary: Success value: codigo: ERROR_VALIDACION mensaje: Error de validación en los datos enviados errores: - campo: paciente_id mensaje: El campo es requerido securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT servers: [] security: []
openapi: 3.0.1
info:
title: 'Módulo 6 - Internación y Gestión de Camas'
description: >
API REST del módulo de Internación y Gestión de Camas para la red
hospitalaria Health Grid.
## Modelo de Dominio
Un **EPISODIO DE INTERNACIÓN** comienza cuando se aprueba una solicitud de
cama y termina
cuando el Módulo 1 (HCE) notifica el alta médica.
El flujo principal es:
1. Un médico solicita una cama desde HCE (M1)
2. La solicitud llega a este módulo como webhook entrante
3. Un administrativo la aprueba (con la cama pedida u otra), o la rechaza
4. Al aprobar → se asigna la cama al paciente (estado `OCUPADA`)
5. Los traslados también llegan como solicitudes desde HCE (M1) o se
realizan directamente
6. El alta médica llega como webhook desde HCE (M1)
### Solicitudes
Las solicitudes de internación y traslado llegan desde HCE (M1) y quedan en
estado
`PENDIENTE` hasta que un administrativo las resuelve.
| Resolución | Efecto |
|------------|--------|
| `APROBAR` | Se ejecuta la acción (ingreso o traslado) con la cama
solicitada |
| `APROBAR_CON_CAMBIO` | Se ejecuta la acción con una cama distinta a la
solicitada |
| `RECHAZAR` | No se ejecuta ninguna acción. Se notifica a HCE |
## Leyenda de Endpoints
- **Sin prefijo:** Endpoints PROPIOS de este módulo (implementados por
nosotros)
- **Tag [EXT]:** Endpoints de otros módulos, documentados como referencia.
Mockeados localmente en la 2da entrega
## Webhooks Salientes (HTTP POST que este módulo dispara)
| Evento | Receptor | Cuándo |
|--------|----------|--------|
| `SOLICITUD_RESUELTA` | Módulo 1 - HCE | Al aprobar o rechazar una
solicitud |
| `ALTA_MONITOREO` | Módulo 9 - Monitoreo | Al asignar una cama a un
paciente (ingreso o traslado destino) |
| `BAJA_MONITOREO` | Módulo 9 - Monitoreo | Al dar el alta médica o al
trasladar un paciente (cama origen) |
| `CAMA_LISTA` | Módulo 7 - Facturación | Al completar limpieza post-alta
(cama pasa de EN_LIMPIEZA a DISPONIBLE) |
## Webhooks Entrantes (HTTP POST que recibimos de otros módulos)
| Evento | Emisor | Cuándo |
|--------|--------|--------|
| Solicitud de internación | Módulo 1 - HCE | Un médico solicita cama para
internar un paciente |
| Solicitud de traslado | Módulo 1 - HCE | Un médico solicita trasladar un
paciente internado |
| Alta médica | Módulo 1 - HCE | Un médico da el alta al paciente |