# Salud de la aplicación

Cómo vigila UTILIA OS la salud de tu aplicación con su tráfico real, cuándo pasa a Revisar o a No funciona y a quién avisa.

Además de responderte cuando preguntas, UTILIA OS vigila la salud de cada aplicación con su tráfico real y con los cambios de su configuración, sin llamadas de prueba. La reevalúa a los pocos segundos de cada cambio (permisos, persona responsable, plan, avisos, facturación) y en un barrido cada hora, y avisa cuando deja de funcionar. Los estados son los mismos que devuelve el diagnóstico en `verdict.status` ([Cómo se lee el veredicto](https://os.utilia.ai/docs/developers/getting-started/diagnostics#cómo-se-lee-el-veredicto)).

## Los estados

**Estados de la salud de una aplicación**

1. **Sin comprobar** (`unknown`). Nunca se ha evaluado.
2. **Funciona** (`ok`). Se llega desde Sin comprobar cuando: Sin bloqueos ni avisos. Nada que revisar.
   - **Sin uso** (`idle`). Se llega desde Funciona cuando: 30 días sin usar la API. Sin bloqueos observados.
   - **Desactivada** (`paused`). Se llega desde Funciona cuando: Se desactiva o se elimina la aplicación. Sin avisos.
3. **Revisar** (`attention`). Se llega desde Funciona cuando: Dos evaluaciones seguidas, con 15 minutos entre ellas, lo ven. Hay algo pendiente, o funciona en parte.
4. **No funciona** (`failing`). Se llega desde Revisar cuando: Un fallo que ya rechaza llamadas o entregas. Llamadas o avisos que fallan.

Otras transiciones:

- Funciona → No funciona: Una causa de configuración ya rechaza las llamadas.
- No funciona → Funciona: Desaparece la causa.

_Desactivar o eliminar la aplicación la lleva a Desactivada desde cualquier estado. Salir de Sin comprobar no avisa a nadie._

En el panel, el estado `attention` se lee **Funciona en parte** cuando unas rutas fallan y otras van bien, y **Revisar** en los demás casos.

## Qué cambia en el acto y qué se confirma

Un fallo pasajero no debe encender **Revisar** ni mandar correos, y una hora buena no debe apagarlo. Por eso unos cambios se aplican en cuanto se ven y otros necesitan **dos evaluaciones seguidas, separadas al menos 15 minutos**, que vean lo mismo. Mientras llega la segunda, la salud se queda como estaba.

**Cuándo cambia la salud**

### En el acto (Basta una evaluación)

Pasar a Desactivada. Entrar en No funciona por una causa de configuración. Salir de No funciona. Pasar entre Funciona y Sin uso.

### Con confirmación (Dos evaluaciones, 15 minutos)

Entrar en Revisar. Salir de Revisar. Entrar en No funciona por el tráfico: rutas que fallan casi siempre o avisos que no llegan.

Al empeorar, la salud sube solo hasta donde lo vieron las dos evaluaciones: si la primera vio **Revisar** y la segunda **No funciona**, pasa a **Revisar**, y **No funciona** espera su propia confirmación. La primera evaluación de una aplicación, la que la saca de **Sin comprobar**, se aplica en el acto, salvo un fallo de tráfico, que la deja en **Revisar** hasta confirmarse.

## Cuándo pasa a No funciona

Hace falta que el fallo ya esté rechazando llamadas o entregas. Un bloqueo que ninguna llamada ha encontrado todavía (la facturación desactivada sin emisiones, los datos fiscales incompletos) se queda en **Revisar**, con el veredicto «Falta un paso», y no manda correo.

- **En el acto, por una causa de configuración que ya rechaza llamadas**: la persona responsable dada de baja o sin nombrar (con llamadas en los últimos 7 días), un aplicativo o una función fuera del plan, la facturación desactivada con permisos de facturas, una aplicación sin ningún permiso de la API, o la organización suspendida o de baja cuando se rechazan sus escrituras (las lecturas siguen funcionando).
- **Por la clave anterior que ya no vale**: si tu integración sigue llamando con ella y no ha llegado ninguna llamada con la nueva, pasa a **No funciona** cuando han pasado 15 minutos desde que dejó de valer. Antes es un aviso, porque quien renueva sin transición suele cambiarla enseguida.
- **Por el tráfico, con confirmación**: una ruta que falla casi siempre (el 90 % de 5 llamadas o más en 24 horas), la mitad o más de las llamadas de la última hora rechazadas (con 20 llamadas o más), o avisos a tu servidor que no llegan.

La falta de un permiso concreto nunca lleva a **No funciona**, ni la de la aplicación (`INSUFFICIENT_SCOPE`) ni la de su persona responsable (`APP_RESPONSIBLE_PERMISSION_DENIED`): cualquiera que tenga la clave puede provocar esos rechazos llamando a una ruta que la aplicación nunca usó. Dejan la salud, como mucho, en **Revisar**, sin correo.

Se sale de **No funciona** en el acto cuando desaparece la causa; si era el tráfico, cuando las últimas llamadas o entregas van bien o pasan dos horas sin fallos.

## Qué tráfico cuenta

Para que un fallo de tráfico ponga **Revisar** tiene que pesar algo. Por debajo, se sigue viendo en la pestaña **Pruebas** y en el diagnóstico, pero como información:

- **Llamadas rechazadas**: al menos 5 del mismo grupo y el 5 % de las llamadas de su ruta en 24 horas. Los rechazos que arregla la organización cuentan aunque sea uno, porque uno solo ya es un fallo de configuración; menos los de permiso de la API y de origen, que puede provocar cualquiera con la clave.
- **Un `404` al leer por identificador** (`GET` de una ruta con `:id`) se queda en información salvo que la ruta falle casi siempre: buscar algo que no existe es normal.
- **Límite de llamadas (`429`) y errores nuestros (`5xx`)**: al menos 5 y el 5 % de las llamadas de 24 horas.

## A quién se avisa y cuándo

Al pasar a **No funciona**, UTILIA OS avisa a la persona responsable (si está activa) y a quien puede editar la aplicación, hasta 50 personas. El aviso dice qué falla y cómo se arregla, y lleva a la pestaña **Pruebas** de la aplicación. Con la organización suspendida, el aviso llega dentro de UTILIA OS (en la aplicación y en el móvil) y nunca por correo: la suspensión ya manda los suyos.

**Los avisos de una caída**

1. **Caída**: «No funciona». En la aplicación y por correo, con la causa y cómo se arregla. Sin correo si la organización está suspendida.
2. **Vuelta**: «Vuelve a funcionar». Al salir hacia Funciona o Revisar. Solo dentro de UTILIA OS, sin correo ni móvil.
3. **Otra caída**: «No funciona», otra vez. Cada caída nueva vuelve a avisar.

- **Cada caída nueva avisa**, también si entre medias la aplicación solo llegó a **Revisar**: salir de **No funciona** hacia cualquier estado borra el «ya avisado».
- **La vuelta avisa al salir hacia Funciona o Revisar**, y dice si queda algo por revisar. Hacia **Sin uso** o **Desactivada** no hay aviso de vuelta, porque la aplicación no ha vuelto a funcionar: ha dejado de usarse o la han apagado.
- **La primera evaluación solo guarda el estado**: no avisa a nadie ni envía nada a tu servidor, y como no se avisó de esa caída, tampoco se avisa de la vuelta.

Cada persona elige por dónde le llega en **Mi perfil › Avisos**, apartado «Qué te avisamos», fila **Integraciones**, bloque **Salud de las aplicaciones**, aviso **Una aplicación deja de funcionar**. De fábrica llega en la aplicación y por correo. La fila aparece si el plan de tu organización incluye Integraciones, aunque no puedas ver la lista de aplicaciones: el aviso va también a la persona responsable.

## Cómo se entera tu servidor

Tu servidor recibe cada cambio de estado con el aviso [`APP_HEALTH_CHANGED`](https://os.utilia.ai/docs/developers/webhooks/events#salud-de-tu-aplicación), que trae el estado anterior y el nuevo y los hallazgos por su código. Hay dos excepciones: la primera evaluación y el paso a **Desactivada**, porque una aplicación desactivada rechaza todas sus llamadas con `APP_DISABLED`, que ya lo dice. Al volver a activarla, el primer aviso llega con `previousStatus: paused`.

Qué significa cada hallazgo y cómo se arregla está en [Hallazgos del diagnóstico](https://os.utilia.ai/docs/developers/getting-started/testing).

## Siguiente paso

- [La pestaña Pruebas](https://os.utilia.ai/docs/developers/api/apps-panel#la-pestaña-pruebas): El estado, el pulso de 24 horas y la acción que hace falta, en el panel.
- [Catálogo de eventos](https://os.utilia.ai/docs/developers/webhooks/events#salud-de-tu-aplicación): La forma del aviso APP_HEALTH_CHANGED que recibe tu servidor.