1. Introducción

1.1 ¿Qué es una API?

Una API (del inglés Application Programming Interface, interfaz de programación de aplicaciones) es un conjunto de reglas y protocolos que permite que dos sistemas informáticos se comuniquen entre sí e intercambien información de forma controlada y segura.

En términos sencillos, una API actúa como intermediario entre dos aplicaciones, definiendo cómo deben realizarse las solicitudes de datos y cómo deben devolverse las respuestas. De este modo, una aplicación externa puede acceder a determinados datos o funcionalidades de otro sistema sin necesidad de acceder directamente a su base de datos.

En el caso de Prevengos, el Servicio Web API permite que aplicaciones externas puedan consultar o introducir datos en la plataforma de forma automatizada, siempre dentro de los límites y permisos que el administrador haya configurado.

 

1.2 Introducción

Prevengos dispone de un Servicio Web API que permite habilitar el acceso a determinados datos de la plataforma desde cualquier ubicación externa. Este servicio ofrece varias funcionalidades: por un lado, permite la introducción de datos en Prevengos a través de un fichero en formato XML con una estructura definida; por otro, dispone de diversas funciones de consulta que permiten extraer información de la base de datos, como datos de empresas, contratos o formación a trabajadores.

La utilización de este servicio requiere una configuración previa en Prevengos, que se detalla a lo largo de este manual. Toda la información y las opciones relacionadas con el Servicio Web API se han agrupado en una herramienta específica accesible desde la pantalla principal del programa, tal y como se muestra en la siguiente captura:

 

 

2. Configuración

Antes de proceder a la configuración, es necesario haber instalado previamente el Servicio Web API. El instalador está disponible en el área cliente de soporte.prevengos.com/descargas para aquellos usuarios que tengan contratado este módulo.

Para acceder a la configuración, el usuario debe dirigirse a la pantalla principal de Prevengos y, desde el desplegable Configuración, pulsar sobre la opción API Web Service de Prevengos (WSAPI). Una vez dentro, se mostrará una ventana similar a la siguiente imagen:

Dentro de esta ventana tenemos que habilitar el acceso a la propia API, para ello marcaremos el check Habilitar acceso a la API por parte de terceros. Una vez habilitado el servicio podrán pasar a las opciones de configuración de la misma

Este apartado permite controlar y restringir el acceso a la API mediante la definición de las direcciones IP públicas desde las que se autoriza realizar llamadas al servicio. Dispone de tres opciones de configuración:

• No limitar. Permitir cualquier comunicación No se aplicará ningún bloqueo ni filtro sobre las direcciones IP que accedan a la API, permitiendo realizar llamadas desde cualquier dirección sin restricción.
• Sólo permitir las direcciones IP indicadas en la lista Únicamente se permitirá el acceso a la API desde las direcciones IP que el usuario haya añadido al listado habilitado para ello. Cualquier dirección IP que no figure en la lista tendrá el acceso denegado. Esta opción es la más recomendable cuando se desea restringir el acceso a ubicaciones concretas y conocidas, como la propia oficina.
• Denegar las solicitudes de las direcciones IP indicadas en la lista Se utilizará el mismo listado de IPs, pero con efecto inverso: se permitirá el acceso desde cualquier dirección IP que no esté incluida en la lista, bloqueando únicamente las que sí figuren en ella. Esta opción resulta útil cuando se detecta un intento de intrusión o ataque desde una dirección IP concreta y se desea bloquearla de forma inmediata.

Sobre el listado de IP, la aplicación permite añadir una IP determinada o un rango de IP, tal y como se explica en la ventana donde se establecen:

 

Pasamos ahora a la segunda pestaña presente en la ventana de configuración, denominada Usuarios de la API, similar a la siguiente imagen:

Dentro de este apartado vamos a establecer los usuarios que van a tener acceso a la API, para ello disponemos de opciones para crear, editar y eliminar usuarios dentro del desplegable Usuarios, al igual que para activar/desactivar usuarios ya existentes.  A la hora de crear usuarios nuevos, se mostrará la siguiente ventana.

El primer campo, denominado Login, lo usaremos para indicar el usuario que se usará para conectar con la API. 

Seguidamente podemos establecer la contraseña de acceso para ese usuario, en el campo Password. Prevengos permite que se genere una contraseña aleatoria mediante el botón "Generar contraseña aleatoria", por defecto se asignará una contraseña 'fuerte'. Además, dentro de este bloque, podemos establecer una descripción sobre el usuario, o marcarlo como usuario desactivado cuando sea necesario (la misma opción de activar/desactivar que veíamos en el desplegable Usuarios de la ventana anterior).

Para cada usuario podremos limitar las empresas a las que puede acceder, esto lo realizaremos desde el apartado de 'Configuración de seguridad' de cada usuario. De tal manera, podemos no establecer ningún tipo de limite, con lo que podrá acceder a todas las empresas, o indicar a cuales puede acceder. Esta opción exige añadir dichas empresas en la parte inferior desde el desplegable "Empresas", teniendo en cuenta que aquellas empresas que no estén en el listado estarán bloqueadas para el usuario que estamos creando.

Por último pasamos a la pestaña Funciones con Permiso del usuario que estamos creando, donde podemos establecer los permisos que va a tener con la aplicación, tal y como podemos ver en la siguiente imagen:

Encontramos permisos relacionados con las funciones que podrá ejecutar el usuario al llamar a la API. Estas funciones pueden ser de importación de datos o de exportación de datos. Si habilitamos la columna 'RW', estaremos permitiendo al usuario el uso de esa función, mientras que si usamos la columna 'D', estaremos denegando al usuario el uso de esa función.

Desde la pestaña 2. Funciones con permiso de la ficha del usuario de la API, se configuran las funciones a las que dicho usuario tendrá acceso:

Las funciones disponibles se organizan por áreas:

• General a todo Prevengos Incluye la importación de datos mediante fichero XML y la descarga de documentación generada por Prevengos.
• Gestión General Permite el acceso al listado de empresas y a la ficha de datos de una empresa concreta.
• Administración Incluye el acceso al listado de contratos con los distintos elementos producidos en Prevengos vinculados a cada contrato.
• Formación Permite consultar el listado de trabajadores vinculados a acciones formativas.
• Medicina Incluye la gestión de la agenda médica.
• Coordinación de Actividades Empresariales Permite consultar el estado de la documentación requerida a nivel general para el control de accesos, tanto para contratas como para trabajadores.
• Consultas e informes Incluye el listado de trabajadores frente a su último reconocimiento médico, el listado de trabajadores frente a su última formación en materia del artículo 19 de la LPRL, y los datos registrados en la aplicación en un período determinado.

La función de 'Importación de datos XML', permitirá al usuario importar datos a Prevengos a través de un archivo con formato XML. Si el usuario no tiene este permiso habilitado y llama a esta función, la API devolverá un mensaje de acceso denegado.

El resto de las funciones son todas de consulta, es decir, las llamadas a la API con estas funciones devolverán datos almacenados en Prevengos de Empresas, contratos y trabajadores en formación. Se usarán para extraer datos de Prevengos (función GET).

Aceptaríamos ambas ventanas con lo que tendríamos creado el usuario con la configuración establecida y podremos lanzar las consultas mediante la API