Guías técnicas

Servicio Web API SWPP (documentación técnica)

Descargar PDF

1. Introducción

Este manual tiene el propósito de dar las indicaciones necesarias para el consumo y acceso a datos de Prevengos a otras aplicaciones a través del Servicio Web Público de Prevengos.

 

2. Descripción del protocolo de comunicación

Para una mayor compatibilidad con otros sistemas la comunicación contra este servicio se realizará bajo el protocolo RESTful. 

Así mismo, los datos que devuelve este servicio podrán estar en formato JSON ó XML (a elección del usuario).

 

3. Parámetros generales y autenticación

Para consumir este servicio debe conocer ciertos datos. Estos datos se los debe proporcionar su cliente o proveedor. Los datos que le deberá proporcionar su cliente son:

La autenticación de la API se realiza mediante HTTP Basic Auth. Deberá proporcionar sus credenciales en cada petición que realice a la API. Para proteger estas credenciales, todas las solicitudes a la API deben hacerse a través de HTTPS.

 

4. Devolución de datos al cliente

Todas las operaciones expuestas de este servicio devuelven una misma cabecera. Esta cabecera se denomina “Resultado” y contiene:

  • Success: Indica si se ha procesado la solicitud (0: Error, 1: Ok).
  • FaultCode: Si Success=0 indica el código de error al procesar la solicitud.
  • FaultMessage: Si Success=0 indica el texto descriptivo del error.
  • Data: Si Success=1 este parámetro contendrá el resultado de la operación que se haya solicitado. Los datos que se devuelvan en este objeto variarán según la operación que se consuma.

Para conocer con exactitud los código de error devueltos en FaultCode consulte el apartado correspondiente.

 

5. Operaciones del servicio

Trabajador (estado)

Devuelve el control de acceso de un trabajador: Acceso permitido o Acceso denegado (true o false).

Definición de la operación

Método: GET

URL de acceso a la operación: [URL]/Prevengos/[formato]/ctrlacc/acceso/trab?i=[i]&t=[t]

Donde:

  • [URL]: Url de acceso al servicio.
  • [formato]: Formato de datos (sustituir este valor por xml o json).
  • [i]: DNI o código de tarjeta a consultar.
  • [t]: Valor que indica si buscar por DNI o código de tarjeta:
    • 0 -> DNI
    • 1 -> Código tarjeta.

En el caso de encontrar varios trabajadores con el mismo identificador o varios nodos donde puedan entrar, se devolverá el caso más permisivo. Es decir, si el trabajador puede entrar en un nodo del proyecto de los 17 asignados devolverá Acceso Permitido.

Ejemplo de llamada usando cualquier explorador (para JSON):

https://demo.prevengos.com/SWapi/Prevengos/json/ctrlacc/acceso/trab?i=11111111A&t=0

Ejemplo de llamada usando cualquier explorador (para XML):

https://demo.prevengos.com/SWapi/Prevengos/xml/ctrlacc/acceso/trab?i=11111111A&t=0

Devolverá dentro del objeto Data un valor booleano:

  • True -> Acceso permitido
  • False -> Acceso denegado

En el caso de no encontrar al trabajador en el sistema se devolverá error 1500 (ver apartado de códigos de error)

 

Trabajador (estado con nombre)

Devuelve el control de acceso de un trabajador (al igual que la función anterior) sólo que con más datos, como el nombre, dni y empresa a la que pertenece.

Definición de la operación

Método: GET

URL de acceso a la operación: [URL]/Prevengos/[formato]/ctrlacc/acceso/displayName/trab?i=[i]&t=[t]

Donde:

  • [URL]: Url de acceso al servicio.
  • [formato]: Formato de datos (sustituir este valor por xml o json).
  • [i]: DNI o código de tarjeta a consultar.
  • [t]: Valor que indica si buscar por DNI o código de tarjeta:
    • 0 -> DNI
    • 1 -> Código tarjeta.

En el caso de encontrar varios trabajadores con el mismo identificador o varios nodos donde puedan entrar, se devolverá el caso más permisivo. Es decir, si el trabajador puede entrar en un nodo del proyecto de los 17 asignados devolverá Acceso Permitido.

Ejemplo de llamada usando cualquier explorador (para JSON):

https://demo.prevengos.com/SWapi/Prevengos/json/ctrlacc/acceso/displayName/trab?i=11111111A&t=0

Ejemplo de llamada usando cualquier explorador (para XML):

https://demo.prevengos.com/SWapi/Prevengos/xml/ctrlacc/acceso/displayName/trab?i=11111111A&t=0

Devolverá dentro del objeto Data un objeto con los siguientes valores:

 Campo  Descripción
 cif  CIF de la empresa
 empresa  Nombre de la empresa
 trabajador  Nombre del trabajador
 dni  DNI del trabajador
 controlacceso  1 -> Acceso permitido
 2 -> Acceso denegado


En el caso de no encontrar al trabajador en el sistema se devolverá error 1500 (ver apartado de códigos de error)

 

Trabajador (listado)

Devuelve el listado de trabajadores de un proyecto, junto con su estado, para el control de acceso.

Hay que tener en cuenta que en Prevengos un trabajador puede estar indicado más de una vez en el mismo proyecto en función de la empresa que contrata los servicios (incluso siendo contratada por la misma empresa pero para trabajos diferentes). Por este motivo, es importante tener en cuenta que puede venir más de una vez indicado el mismo trabajador de una misma empresa en este listado.

Definición de la operación

Método: GET

URL de acceso a la operación: [URL]/Prevengos/[formato]/ctrlacc/acceso/listarTrabs

Donde:

  • [URL]: Url de acceso al servicio.
  • [formato]: Formato de datos (sustituir este valor por xml o json).

Ejemplo de llamada usando cualquier explorador (para JSON):

https://demo.prevengos.com/SWapi/Prevengos/json/ctrlacc/acceso/listarTrabs

Ejemplo de llamada usando cualquier explorador (para XML):

https://demo.prevengos.com/SWapi/Prevengos/xml/ctrlacc/acceso/listarTrabs

Devolverá dentro del objeto Data un objeto con los siguientes valores:

 Campo  Descripción
 referencia     Referencia del proyecto
 proyecto  Nombre del proyecto
 items  Array que contiene el listado de maquinaria   


Array de trabajadores (objeto item)

 Campo  Descripción
 empresa  Nombre de la empresa
 contratadaPor     Nombre de la empresa que le ha contratado   
 nombre  Nombre del trabajador
 dni  DNI del trabajador
 codTarjeta  Código de tarjeta del trabajador
 controlacceso  1 -> Acceso permitido
 2 -> Acceso denegado

 

Maquinaria (estado)

Devuelve el control de acceso de una maquinaria: Acceso permitido o Acceso denegado (true o false).

Definición de la operación

Método: GET

URL de acceso a la operación: [URL]/Prevengos/[formato]/ctrlacc/acceso/maq?i=[i]

Donde:

  • [URL]: Url de acceso al servicio.
  • [formato]: Formato de datos (sustituir este valor por xml o json).
  • [i]: Referencia o matrícula a consultar.

Ejemplo de llamada usando cualquier explorador (para JSON):

https://demo.prevengos.com/SWapi/Prevengos/json/ctrlacc/acceso/maq?i=1111AAA

Ejemplo de llamada usando cualquier explorador (para XML):

https://demo.prevengos.com/SWapi/Prevengos/xml/ctrlacc/acceso/maq?i=1111AAA

Devolverá dentro del objeto Data un valor booleano:

  • True -> Acceso permitido
  • False -> Acceso denegado

En el caso de no encontrar la maquinaria en el sistema se devolverá error 1501 (ver apartado de códigos de error)

 

Maquinaria (listado)

Devuelve el listado de maquinaria de un proyecto junto con su estado para el control de acceso.

Hay que tener en cuenta que en Prevengos una maquinaria puede estar indicada más de una vez en el mismo proyecto en función de la empresa que contrata los servicios (incluso siendo contratada por la misma empresa pero para trabajos diferentes). Por este motivo, es importante tener en cuenta que puede venir más de una vez indicada la misma maquinaria de una misma empresa en este listado.

Definición de la operación

Método: GET

URL de acceso a la operación: [URL]/Prevengos/[formato]/ctrlacc/acceso/listarMaq?proy=[proy]

Donde:

  • [URL]: Url de acceso al servicio.
  • [formato]: Formato de datos (sustituir este valor por xml o json).

Ejemplo de llamada usando cualquier explorador (para JSON):

https://demo.prevengos.com/SWapi/Prevengos/json/ctrlacc/acceso/listarMaq

Ejemplo de llamada usando cualquier explorador (para XML):

https://demo.prevengos.com/SWapi/Prevengos/xml/ctrlacc/acceso/listarMaq

Devolverá dentro del objeto Data un objeto con los siguientes valores:

 Campo  Descripción
 referencia     Referencia del proyecto
 proyecto  Nombre del proyecto
 items  Array que contiene el listado de maquinaria   


Array de maquinaria (objeto item)

 Campo  Descripción
 empresa  Nombre de la empresa
 contratadaPor     Nombre de la empresa que la ha contratado   
 nombre  Nombre de la maquinaria
 referencia  Referencia de la maquinaria
 matricula  Matrícula de la maquinaria
 controlacceso  1 -> Acceso permitido
 2 -> Acceso denegado

 

6. Códigos de error

Como se ha indicado en el apartado 4, este servicio puede devolver códigos de error al cliente en la variable FaultCode. A continuación, se describen los posibles errores:

 FaultCode  Descripción
 0  No hay error
 200  Llamada a la operación no válida.
 Este error puede darse si ha indicado un valor vacío para un parámetro requerido.    
 950  Credenciales de acceso no válidas.
 1500  Error de control de accesos. Trabajador no identificado en el sistema.
 1501  Error de control de accesos. Maquinaria no identificada en el sistema.
 10200  Ha ocurrido un error inesperado mientras se procesaba la solicitud.
 Llamar al cliente en caso de recibir este error.
 90501, 90502      El servicio web no está disponible en este momento.
 Llamar al cliente en caso de recibir este error.