Claves API
Una clave API permite que otro sistema de tu empresa —un ERP, un cuadro de mando, un script— lea o escriba en goPrevina a través de la API REST, sin usar la cuenta de ninguna persona. Todas las llamadas van a la ruta base /api/v1.
1. Qué hay en la pantalla
Arriba, el bloque «Crear una clave» con el campo «Nombre», los «Ámbitos» («Lectura», «Escritura», «Analíticas (webhook FHIR)» y “Proveedor de salud laboral (solo envío)”), el selector «Alcance» y el botón «Crear una clave». Debajo, el desplegable «Permisos por recurso (API pública)» la lista de claves de la empresa (si no hay ninguna, dice “Aún no hay claves API.”) y, al final, “Envíos de proveedores”.
Cuando hay al menos una clave, sobre la lista aparecen cuatro tarjetas de estado con su recuento: “Caducadas”, “Caducan en 30 días”, “Revocadas” y “Activas”. Pulsa una para ver solo esas claves; púlsala otra vez para volver a ver todas.
2. Crear una clave
1. Escribe un «Nombre» que diga quién la usa (por ejemplo, “ERP de nóminas” o “cuadro de mando de dirección”).
2. Marca los «Ámbitos»: «Lectura» si el sistema solo consulta datos; añade «Escritura» solo si tiene que crear o modificar registros. «Analíticas (webhook FHIR)» solo se marca para un laboratorio que envía resultados por FHIR. “Proveedor de salud laboral (solo envío)” es para la clave de un proveedor de salud laboral o de cribado de Irlanda o Reino Unido: sustituye a los demás ámbitos y el alcance queda en «Esta empresa». Con ella el proveedor envía citas, resultados de aptitud, certificados y resultados de cribado (JSON, FHIR R4 o CSV de audiómetro y espirómetro) a tu empresa y lee solo los recuentos de sus propios envíos, nada más.
3. En «Alcance» elige «Esta empresa», «Todas las empresas del grupo» (solo un propietario o administrador de la cuenta) o «Todos los clientes del SPA» (solo un administrador del SPA).
4. Si la clave debe tocar solo algunos datos, abre «Permisos por recurso (API pública)» y marca lectura o escritura por recurso. «Lectura» y «Escritura» no cubren la aptitud médica ni el registro de auditoría: cada uno necesita su permiso.
5. Pulsa «Crear una clave». Aparece “Copia esta clave ahora — no se volverá a mostrar:”. Cópiala, guárdala en el sistema que la va a usar y pulsa “Hecho”.
3. Rotar, revocar y vigilar el uso
Cada clave de la lista muestra su nombre, sus ámbitos, su alcance si no es la empresa y su “último uso”. “Rotar” genera un valor nuevo para la misma clave (el anterior deja de valer) y lo enseña una sola vez. “Revocar” abre la confirmación “Revocar clave API”: al aceptar, la clave deja de funcionar de inmediato y no se puede deshacer. Úsalo cuando un sistema deja de necesitarla o si sospechas que se ha filtrado.
Una clave revocada o caducada sale marcada como “revocada” o “caducada” y ya no tiene botones. El consumo de la API frente a la cuota de tu plan se ve en “Monitorización de integraciones”.
“Envíos de proveedores” lista lo que ha enviado cada clave de proveedor: el proveedor (el nombre de la clave), el tipo (citas, resultados de aptitud, certificados, resultados de cribado, FHIR, CSV de audiómetro o de espirómetro), los envíos “Aceptados”, “Repetidos” y “Rechazados” y la fecha de recepción. Solo muestra recuentos, nunca datos clínicos.
4. Una clave por sistema
Crea una clave distinta para cada sistema que se conecte: así, si uno se retira o se compromete, revocas solo la suya y los demás siguen funcionando, y en “último uso” ves cuál está activo. La tarjeta “Caducan en 30 días” avisa de las que hay que renovar con tiempo.
La clave da acceso a los datos de la empresa con los ámbitos que le diste: guárdala en el gestor de secretos del sistema que la usa, nunca en un correo ni en una hoja de cálculo.