Configuración

Esta guía cubre los requisitos que debe cumplir tu sistema de salud y el flujo de configuración completo en Quralo One (Integraciones → Sistema de salud, ruta /interoperability/system-integration).

Requisitos del sistema externo

Antes de crear la integración, verificá que tu sistema de salud (HIS/EHR) cumpla estos requisitos:

1. API FHIR R4 — la verificación exige fhirVersion == 4.0.1 en /metadata.
2. Token endpoint OAuth 2.0 — debe aceptar grant_type=client_credentials con client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer y una client_assertion firmada con Private Key JWT.
   • Idealmente expone .well-known/smart-configuration en la base FHIR (auto-descubrimiento del token endpoint). Si no lo expone, se configura el token endpoint manualmente.
3. Registro de clientes con clave pública — debe permitir registrar un cliente M2M pegando un JWK (con use=sig, alg y kid). Quralo registrará el client_id que devuelva.
4. Algoritmos de firma soportados — RS384 (RSA) o ES384 (EC P-384). SMART Backend Services exige uno de estos dos.
5. IPs de salida de Quralo en allowlist (egress) — ver Verificación y monitoreo → IPs de salida.
6. Scopes SMART de tipo system/... que la API externa conceda — ver el catálogo de scopes.

Flujo de configuración paso a paso

Pasos numerados idénticos a la sección "Clave pública (JWKS)" de la vista.

Paso 1 — Crear la integración

1. Ir a Integraciones → Sistema de salud.
2. Completar:
   • URL base FHIR (obligatoria).
   • Algoritmo de firma (RS384 o ES384; el default es RS384).
   • Al menos un scope.
   • Client ID: puede dejarse vacío en este paso (se obtiene después de registrar la clave pública).
   • Opcionales: Token endpoint URL, Email de notificación, Unificar scopes.
3. Presionar "Crear integración" (el botón dice "Crear integración" si no existe la integración; "Guardar cambios" si ya existe).
4. El sistema crea la integración en estado draft y genera el par de claves automáticamente. La clave pública (JWK) aparece de inmediato en la sección "Clave pública (JWKS)".

Paso 2 — Registrar la clave pública en el sistema externo

1. En la sección "Clave pública (JWKS)", copiar o descargar el JWK (botones Copiar / Descargar; el archivo se descarga como jwks-<kid>.json).
2. En el sistema externo (HIS/EHR), registrar un nuevo cliente de API (SMART Backend Services) pegando la clave pública. El JWK incluye kid — ese identificador debe quedar registrado junto con la clave en el sistema externo.
3. El sistema externo devolverá un client ID.

Paso 3 — Completar el client ID

1. Volver a Integraciones → Sistema de salud.
2. Escribir el Client ID devuelto en el campo correspondiente y Guardar cambios.
3. Sin client ID no se puede verificar la conexión (el botón "Probar conexión" está deshabilitado y la UI lo avisa: "Completalo cuando tengas el client_id del sistema externo para poder verificar la conexión.").

Paso 4 — Verificar la conexión

Presionar "Probar conexión". Ver Verificación y monitoreo para el detalle de qué valida y qué significa cada estado.

Paso 5 (opcional) — Configurar notificaciones

Completar Email de notificación para recibir avisos de caída/restauración. Ver Verificación y monitoreo → Emails de notificación.

Campos de configuración

Campo (label en UI)	Obligatorio	Descripción / validación
URL base FHIR	Sí	URL base de la API FHIR R4 del sistema de salud (ej. https://his.ejemplo.com/fhir). Debe ser HTTPS en producción. En entornos de desarrollo Quralo acepta http (para servidores FHIR locales). Validación: "La URL debe ser HTTPS." / "La URL no es válida." / "La URL base FHIR es obligatoria."
Token endpoint URL (opcional)	No	URL del servidor de autenticación (token endpoint). Si se deja vacío, Quralo la descubre automáticamente desde {fhir_base_url}/.well-known/smart-configuration. Se usa este campo solo si el sistema externo no expone smart-configuration. Debe ser HTTPS en producción.
Client ID	No al crear / Sí para verificar	El identificador de cliente que asigna el sistema externo después de registrar la clave pública. Sin client ID la verificación es rechazada con: "client_id no configurado. Registrá la clave pública en tu sistema externo y completá el client_id antes de verificar la conexión."
Algoritmo de firma	Sí	RS384 (RSA — recomendado) o ES384 (EC P-384). Debe coincidir con lo que espera el sistema externo. Cambiar el algoritmo regenera el par de claves (la anterior queda inactiva y hay que re-registrar la pública). Ver Gestión de claves.
Scopes	Sí (al menos 1)	Lista curada de scopes SMART (ver catálogo). Validación: "Seleccioná al menos un scope."
Email de notificación (opcional)	No	Email al que Quralo notifica cuando la integración se cae o se restablece. Si se deja vacío, no se envían notificaciones. Validación de formato: "El email no es válido."
Unificar scopes	No	Si el sistema externo no soporta solicitar subconjuntos de scopes, marcarlo para que Quralo siempre solicite todos los scopes configurados (unión). Si el sistema externo lo soporta, Quralo pedirá solo el subconjunto que necesita cada add-on (menor privilegio por token).

Nota técnica sobre "Unificar scopes"

Por defecto (sin marcar), Quralo solicita a futuro el subset de scopes que requiera cada add-on dentro de los configurados. Si el servidor externo rechaza pedir subsets, se marca esta opción y Quralo pide siempre la unión completa.

Qué sigue

• Catálogo de scopes — los permisos que podés otorgar.
• Verificación y monitoreo — cómo confirmar que todo funciona.