Solución de problemas

Acá vas a encontrar los errores más comunes de la integración de Sistema de salud, su causa probable y qué hacer para resolverlos.

Tabla de errores típicos

Síntoma en UI / email	Causa probable	Qué hacer
"● Con errores": connect ECONNREFUSED <host>	El sistema externo no está accesible (caído o IP/puerto bloqueado)	Verificar disponibilidad del servidor; revisar allowlist de IP de salida
"El token endpoint rechazó la autenticación: ..."	client_id incorrecto, clave pública no registrada o kid no reconocido, algoritmo distinto al esperado	Re-registrar la JWK vigente (mismo kid), verificar client_id y algoritmo
"El servidor FHIR no reporta R4 (fhirVersion=...)"	El servidor externo no es FHIR R4 o el /metadata devuelve otra versión	Confirmar que la base es FHIR R4 (4.0.1)
"No se pudo descubrir la configuración SMART (HTTP ...)" o error al auto-descubrir	El sistema externo no expone .well-known/smart-configuration	Configurar manualmente el campo Token endpoint URL
"Faltan recursos requeridos en /metadata: ..."	El servidor no reporta recursos exigidos por la configuración de la integración	Ajustar el servidor externo para que reporte esos recursos o contactar a soporte@quralo.com
"client_id no configurado..." al verificar	Falta completar el Client ID	Registrar la clave pública y completar el Client ID
No llega el email de caída	La integración ya estaba en error (no hay transición) o no hay email configurado	Verificar email_de_notificacion; la notificación es solo en transiciones
El monitoreo no detecta la caída rápidamente	Backoff activo (fallos consecutivos espacian los chequeos)	Usar "Probar conexión" manual; el monitoreo normal retoma al vencer el cooldown (máx ~20 min)

Errores comunes y cómo diagnosticarlos

1. El token endpoint rechaza la autenticación

Es el error más frecuente al dar de alta la integración. Suele deberse a:

• client_id incorrecto: verificá que el que cargaste en Quralo sea exactamente el que te devolvió el sistema externo.
• Clave pública no registrada o kid no reconocido: el sistema externo verifica la firma usando la JWK que registraste. Si registraste una versión vieja de la clave (otro kid), la firma no valida. Re-registrá la JWK vigente.
• Algoritmo distinto: el sistema externo puede estar configurado para esperar RS384 y la integración está en ES384 (o viceversa). Hacé que coincidan.

Para diagnosticar, mirá el detalle del error que muestra la UI ("Último check: ...") y el mensaje que guarda Quralo.

2. No se descubre el token endpoint

Si Quralo no puede auto-descubrir la configuración SMART, es porque el sistema externo no expone .well-known/smart-configuration en la base FHIR. Solución: configurá el campo Token endpoint URL manualmente con la URL exacta del endpoint de tokens.

3. La base no reporta FHIR R4

Quralo exige fhirVersion == 4.0.1. Si el /metadata devuelve otra versión (por ejemplo, un servidor FHIR R5 o DSTU2), la verificación falla. Confirmá que la URL base FHIR apunta a una base R4 y que el servidor realmente implementa R4.

4. No llegan los emails de notificación

Los emails solo se envían en transiciones de estado (active → error y error → active). Si la integración ya estaba en error cuando se cayó más, no hay transición y no se manda un nuevo email. También verificá que el Email de notificación esté configurado.

Para probar las notificaciones de inmediato:

1. Con la integración active, tira abajo tu servidor FHIR.
2. Presioná "Probar conexión" (o esperá el monitoreo, ≤ 1 min).
3. Deberías recibir el email de caída. Cuando lo levantes de nuevo, el monitoreo (o una verificación manual) dispara el email de restauración.

5. El monitoreo parece "lento" en detectar caídas

Si hubo fallos consecutivos, el backoff espacia los chequeos (hasta 20 min de cooldown). No es un problema: el sistema retoma el ritmo de 1 minuto al recuperarse. Para chequear al instante, usá "Probar conexión" manual.

6. Cambiaste la clave o el algoritmo y ahora falla

Regenerar claves o cambiar el algoritmo invalida la JWK registrada en el sistema externo. Re-registrá la nueva clave pública (con su kid) y, si corresponde, actualizá el client_id. Ver Gestión de claves.

Checklist rápido de conexión

1. ✅ La URL base FHIR apunta a una API FHIR R4 (https en producción).
2. ✅ El token endpoint es accesible (manual o por auto-descubrimiento).
3. ✅ La JWK vigente está registrada en el sistema externo (mismo kid).
4. ✅ El Client ID es el que devolvió el sistema externo.
5. ✅ El algoritmo de firma coincide con el del sistema externo.
6. ✅ Las IPs de salida de Quralo están en la allowlist.
7. ✅ Los scopes configurados son concedidos por el sistema externo.